Core Product

Colide Code v4.0

Shulker's ultra-powerful agentic terminal IDE. It reads your codebase, writes code, executes commands, observes the results, and loops autonomously until your project actually works — all from inside your terminal.

Updated recently 18 min read v4.0 Live

Introduction

The Colide Loop
Read → Analyze → Act → Observe. Loops autonomously until the outcome is correct. Up to 3× auto-retry with different strategies.
Rich Terminal UI
Syntax-highlighted diffs, animated spinners, live command output, tab-complete with path quoting — inside your existing terminal.
50+ Commands
Built-in slash commands: /fix, /scan, /review, /patch, /test, /commit, /arch, and more.
Surgical PATCH Edits
Line-level patch blocks instead of full-file rewrites. Red/green diff shows exactly what changed and where.
Vision + @mentions
Attach images and files mid-conversation with @path/to/file. Images decoded and sent as base64 context.
Persistent Sessions
Resumable encrypted sessions stored on Shulker's infrastructure. Full history, searchable, never used for training.

Powered by Colide Pro — Colide Code uses Shulker's own AI model with a 700,000-token context window. Requires a Shulker account and API key from AI Studio.

Download & Install

Colide Code is distributed as a standalone, zero-dependency application. Simply download the binary for your operating system to get up and running in seconds.

Get Colide Code
Pre-compiled binaries for all major platforms.
Download App
macOS, Windows, Linux

Windows Users — While Colide Code runs natively on Windows, we highly recommend using Windows Terminal or WSL2 to ensure rich ANSI colors and terminal UI elements render perfectly.

Configuration

On first launch, Colide Code runs an interactive setup wizard. Your API key and preferences are stored in a local config file.

Config file location

macOS
~/.config/colide/config.json
Linux
~/.config/colide/config.json
Windows
%APPDATA%\colide\config.json

Config schema

~/.config/colide/config.json
{
  "api_key":      "YOUR_COLIDE_API_KEY",
  "theme":        "dark",           // "dark" | "light" | "auto"
  "auto_confirm": false,          // skip confirmation prompts
  "max_retries":  3,              // auto-retry limit on failure
  "history_path": "~/.config/colide/history"
}

Config fields

Key Type Default Description
api_key string Required Your Colide API key from AI Studio.
theme string dark Terminal color theme. auto follows OS preference.
auto_confirm boolean false When true, skips "Apply patch?" confirmation prompts. Use with care.
max_retries integer 3 Maximum automatic retry loops on failure. Set to 0 to disable.
history_path string ~/.config/colide/history Path for prompt_toolkit command history persistence.

Environment variable override — Override the API key at runtime with COLIDE_API_KEY. Useful in CI or when managing multiple keys. Set COLIDE_DEBUG=1 to enable verbose error tracebacks.

First Run

Start Colide Code by running colide in any terminal. On first launch, the setup wizard prompts for your API key. After that, you're dropped into the interactive prompt.

Terminal output
   ██████╗  ██████╗ ██╗     ██╗██████╗ ███████╗
  ██╔════╝ ██╔═══██╗██║     ██║██╔══██╗██╔════╝
  ██║      ██║   ██║██║     ██║██║  ██║█████╗
  ██║      ██║   ██║██║     ██║██║  ██║██╔══╝
  ╚██████╗ ╚██████╔╝███████╗██║██████╔╝███████╗
   ╚═════╝  ╚═════╝ ╚══════╝╚═╝╚═════╝ ╚══════╝

  CODE  v4.0 · Ultra Agentic Terminal Assistant · Colide API

  /help for commands · /open <dir> to start · @file.py for context

   session #42

~/projects/myapp ❯ _

Opening a project

Prompt
 /open ~/projects/my-app        # open a project directory
   ~/projects/my-app

 /scan                           # get an AI overview of the project
 fix the login bug               # natural language — no slash needed

Keyboard shortcuts

Tab Autocomplete paths, commands, and @mentions
↑ ↓ Navigate command history
Ctrl+C Interrupt current AI generation or command
Ctrl+D Exit Colide Code gracefully
Ctrl+R Fuzzy-search through history
Alt+Enter Insert newline within a multi-line message

The Colide Loop Key Concept

The defining capability of Colide Code. Unlike tools that generate code and stop, Colide Code executes an autonomous feedback loop — writes code, runs it, reads the actual output, re-plans if something is wrong, and repeats until the outcome matches your intent.

01
Read
Scans your codebase, reads relevant files, ingests error logs, understands project structure. Supports @file and @image mentions for explicit context injection.
02
Analyze
Understands root cause, identifies the minimal change set, chooses the best approach. The 700K-token context means it sees the full picture before acting.
03
Act
Applies surgical PATCH blocks, writes new files, runs shell commands, installs packages. Every action is shown in the terminal with live output.
04
Observe → Repeat
Reads real command output. If errors exist, re-plans and tries again — up to max_retries times with different approaches. Stops when successful.

Always interruptible — Press Ctrl+C at any point to interrupt the loop. Colide will cleanly stop mid-execution and return you to the prompt with any partial progress preserved.

Feedback loop example

Colide Code — auto-retry in action
 fix the failing tests

   thinking…
  ────────────────────────────────────────
  I'll run the tests to see what's failing.
  ────────────────────────────────────────

  ⚡ execute · ~/projects/myapp
  pytest tests/ -v

  FAILED tests/test_auth.py::test_login - AssertionError
  FAILED tests/test_api.py::test_create_user - 422

   analyzing failures, applying fix…

  🩹 patch applied  −3  +5
  ┌─ src/auth.py  lines 42+
  │  − if user.password == password:− raise ValueError("Invalid")+ if not check_password_hash(user.password, password):+ return None
  └─

  ⚡ execute  pytest tests/ -v
   2 passed, 0 failed

  All tests passing. Fixed password comparison to use
  check_password_hash instead of direct string equality.

Slash Commands

Slash commands give you direct control over Colide Code's behaviour. Type /help at any time for a full list. You can also send any natural-language message without a slash.

Navigation & Project

CommandDescription
/open <dir>Open a directory as your project workspace. Tab-completion supported.
/read <file>Read a file and inject its contents into the next AI message as context.
/cd <path>Change working directory (also supported without slash: cd ~/projects).
/treePrint the project directory tree (max depth 4). Excludes common noise dirs.
/helpShow all available slash commands with descriptions.

AI-Powered Project Commands

CommandDescription
/scanFull project audit — architecture, issues, improvements, code quality.
/fixAuto-detect and fix all bugs in the current project. Loops until tests pass.
/review [file]Deep code review of a specific file or the whole project.
/testGenerate unit tests for the current project or a specific file.
/archHigh-level architecture analysis — explain the system and suggest improvements.
/refactor [file]Refactor code for readability, performance, and best practices.
/optimizePerformance analysis and optimization recommendations.
/securityVulnerability scan — checks for common security issues and CVEs.
/debug [error]Deep-dive debug of an error message or stack trace.
/docs [file]Generate or improve documentation for a file or whole project.
/readmeGenerate or rewrite the project README.md.
/scaffold <type>Scaffold a new project. E.g. /scaffold flask-api, /scaffold nextjs.
/explain [file]Plain-English explanation of what a file or codebase does.
/commitGenerate a git commit message from current staged changes.
/prGenerate a pull request title and description from recent commits.

Session & Utility

CommandDescription
/session new [name]Create a new session with optional name. Clears conversation history.
/session load <id>Load a previously saved session by ID.
/session listList all sessions for the current API key.
/session exportExport the current session as a Markdown file.
/clearClear the terminal screen (also: type clear without slash).
/statusShow current session info, API quota usage, and active working directory.
/exitExit Colide Code gracefully. Equivalent to Ctrl+D.

Unknown commands — If you type an unknown slash command, Colide Code shows "Unknown command. Type /help for a list." — it does not forward unknown slash commands to the AI. Only natural-language messages (without a slash) are sent to the model.

File Context

Include files and images directly in any message using @mention syntax. Mentions are tab-completed, support path quoting for spaces, and are replaced with actual file contents before being sent to the AI.

@mention syntax

Prompt examples
 explain @src/auth/login.py
 why does @src/api/users.py throw a 422?
 refactor @'src/components/My Component.tsx'   # paths with spaces auto-quoted
 what's in @config.yml that's causing this?     # resolves relative to cwd
 fix the issue shown in @screenshot.png         # images sent as vision context
Code files
File contents are injected with line numbers and syntax context. Supported: all code extensions + .yml, .toml, .json, .md, .env, .sql, and more.
Image files
Images (.png, .jpg, .gif, .webp) are base64-encoded and sent as vision input to the Colide Pro model.

Tab completion for @mentions — Type @ followed by a partial path and press Tab to autocomplete. Paths with spaces are automatically wrapped in single quotes. Directories complete with a trailing /. Completion works anywhere in the message.

Session Management

Sessions store your full conversation history on Shulker's servers, encrypted and tied to your API key. Resume any session at any time, export logs, and manage multiple ongoing projects.

Session commands
# Create a new named session
 /session new my-project-auth
   session #57 "my-project-auth" created

# List all sessions
 /session list
  #42  my-project-auth     2025-01-15  12 messages
  #38  api-refactor        2025-01-14   8 messages
  #31  devops-setup        2025-01-12   5 messages

# Resume a previous session
 /session load 38
   loaded session #38 "api-refactor" (8 messages)

# Export current session as Markdown
 /session export
   exported → colide_session_38_20250115.md
Encrypted storage
All messages stored encrypted in Shulker's database, scoped to your API key. Never accessible to other users, never used for model training.
Context window
On session resume, the last 30 messages are loaded as conversation context. The 700K-token model can hold extensive history without truncation.

Auto-created on start — A new session is silently created automatically when you launch Colide Code. The session ID is shown in the startup confirmation: ✓ session #42.

Agent Mode

In agent mode, Colide Code operates as a fully autonomous coding agent — reads files, writes patches, runs commands, installs dependencies, and loops until the task is complete with no manual approval steps.

Filesystem access — Agent mode reads and writes files in your working directory. Always run inside a project directory you own. Colide Code will not operate above the working directory root. Use /open <dir> to set the working directory first.

Available agent actions

File Operations
read_file write_file delete_file rename_file create_folder list_directory
Command Execution
execute_command

Runs in the working directory. Long-running commands stream live output. Timeout: 90s (300s for install commands).

Patch System
PATCH block

Surgical line-level edits wrapped in [PATCH]…[/PATCH] blocks. Displayed as red/green diffs in the terminal.

Search & Inspect
find_files grep file_hash disk_usage

Automatic OS normalisation — Colide Code detects your OS and normalises commands automatically. pythonpython3, correct package manager (apt/brew/winget), correct path separators, and the right shell executable.

PATCH System

Instead of rewriting entire files, Colide Code uses a precise patch format that targets specific line ranges. Patches are displayed as red/green diffs before application, and the original file is backed up in-memory for rollback.

PATCH block format

AI response — PATCH block
[PATCH]
filepath: src/auth/login.py
line_start: 42
line_end: 45
new_content:
    if not check_password_hash(user.password_hash, password):
        return {"error": "Invalid credentials"}, 401
    session["user_id"] = user.id
    return {"token": generate_token(user)}, 200
[/PATCH]

How it renders

Terminal — patch diff display
  🩹 patch applied  −4  +4
  ┌─ src/auth/login.py  lines 42+
  │  −  if user.password == password:−      raise ValueError("Invalid")−  session["uid"] = user.id−  return True+  if not check_password_hash(user.password_hash, password):+      return {"error": "Invalid credentials"}, 401+  session["user_id"] = user.id+  return {"token": generate_token(user)}, 200
  └─
Surgical
Only the changed lines are modified. The rest of the file is untouched.
Verified
Line count and content are verified before application. Mismatches are reported.
Multi-file
A single AI response can contain multiple PATCH blocks across different files.

Tab Completion

Colide Code's completer is context-aware. It activates only on Tab press, and handles slash commands, path arguments, and @mention paths — including smart quoting for names with spaces.

ContextWhat completesExample
/slash commands All registered slash commands /sc → /scaffold, /scan, /security
/open, /read, /cd Filesystem paths, dirs with trailing / /open src/ → src/api/, src/auth/
@mentions Filesystem paths inline in messages @src/au → @src/auth/
paths with spaces Auto-wrapped in single quotes @'My Component.tsx'
bare shell commands Path argument for cd, ls, rm, etc. cd ~/pro → ~/projects/

complete_while_typing is OFF — Completion only triggers on an explicit Tab press. This prevents the dropdown from appearing mid-sentence when composing a natural-language message.

Shell Integration

You don't need to leave Colide Code to run shell commands. Common shell commands typed without a slash are intercepted and executed natively — no forwarding to the AI, no extra step.

Handled natively

cd
ls
ll
la
pwd
clear
cls
rm
rmdir
mkdir
mv
cp
touch
cat
echo
find
grep
git
python
python3
node
npm
pip
pip3
docker
make

Special behaviours

CommandBehaviour
cd <path>Changes the working directory used by both the shell and Colide's context. Updates the prompt path indicator.
clear / clsClears the terminal and reprints the Colide Code ASCII banner.
ls / ll / laPasses through to ls with --color=auto. ll/la add -la flags automatically.
pwdPrints the current working directory tracked by Colide Code.

Not a full shell — Shell commands are executed via subprocess, not a persistent shell session. Shell built-ins like export and piping (|) work, but shell aliases, functions, and interactive shell features are not available. For complex shell work, open a separate terminal.

Image Input

Colide Code supports sending images alongside your messages. Useful for sharing screenshots of errors, UI mockups, or diagrams. Images are base64-encoded and sent as vision input to the Colide Pro model.

Using @image mentions
 what error is shown in @/tmp/error_screenshot.png
 recreate this UI in React: @mockup.webp
 the diagram in @architecture.png — implement it in Python
FormatMIME typeNotes
.pngimage/pngFull support
.jpg / .jpegimage/jpegFull support
.gifimage/gifFirst frame only
.webpimage/webpFull support

First image per message — If a message contains multiple @image mentions, only the first image is sent as vision input. Additional images are referenced as context notes. This aligns with the Colide API's single image per request model.

Colide API Client

Colide Code communicates with Shulker's Colide API Gateway — the same endpoint powering Colide AI Studio. All requests are HTTP POST with multipart form data, and responses stream as Server-Sent Events.

POST https://shulker.in/api/colide_api_gateway-v1.0/

Single endpoint. All Colide Code interactions use this URL via HTTP POST. Responses stream via SSE. See the full Colide API documentation for the complete reference.

Key parameters used by Colide Code

ParameterWhereDescription
tokenURL queryYour API key from config.
session_idURL queryActive session ID to load conversation history (last 30 messages).
messagePOST bodyFull message including system context, cwd info, and @file contents prepended.
image_contentPOST body (multipart)Base64-decoded image file when an @image mention is present.
Python — how Colide Code calls the API
import requests, json

url     = "https://shulker.in/api/colide_api_gateway-v1.0/"
params  = {"token": api_key, "session_id": session_id}

with requests.post(
    url, params=params,
    data={"message": full_prompt},
    stream=True, timeout=240
) as resp:
    for raw in resp.iter_lines(decode_unicode=True):
        if not raw or not raw.startswith("data: "): continue
        ev = json.loads(raw[6:])
        if "token"   in ev: full_text += ev["token"]
        if ev.get("done"): session.update(ev); break
        if "error"   in ev: raise APIError(ev["error"])

Context injection — Before sending to the API, Colide Code automatically prepends a [CONTEXT] block containing: working directory, OS info, Python/Node/package-manager versions, project type and frameworks, and a directory listing.

Streaming (SSE)

Colide Code consumes the Colide API's Server-Sent Events stream. A braille-character spinner shows while the model generates. Once complete, the accumulated text is rendered as formatted Markdown — once, with no raw token output shown.

Event types consumed

Token event — received silently, accumulated
data: {"token": "Here"}
data: {"token": " is"}
data: {"token": " the fix:"}
Done event — triggers render + PATCH/TOOL extraction
data: {
  "done": true,
  "usage": {
    "input_words":  84,
    "output_words": 320,
    "total_words":  404
  },
  "session_id": 42
}

Render once, not twice — Colide Code accumulates all tokens silently while showing a spinner. When the done event arrives, it renders the full response exactly once using the Markdown renderer — syntax-highlighted code blocks, headings, tables, blockquotes, and inline formatting.

Response Format

After the SSE stream ends, Colide Code parses the full accumulated text for structured blocks. TOOL blocks are processed first (file operations, commands), then PATCH blocks (code edits).

TOOL block — file/command operations
[TOOL]
read_file: src/api/users.py
execute_command: pytest tests/test_users.py -v
write_file: src/api/users.py|content: ...file content here...
[/TOOL]
PATCH block — line-level code edit
[PATCH]
filepath: src/api/users.py
line_start: 15
line_end: 17
new_content:
    validated = UserSchema().load(request.json)
    user = User(**validated)
    db.session.add(user)
[/PATCH]
TOOL actionArgumentsDescription
read_file<path>Read file and feed contents back as context
write_file<path>|content:…Write or overwrite a file with given content
delete_file<path>Delete a file
rename_file<old>|<new>Rename or move a file
create_folder<path>Create directory (with parents)
list_directory<path>List directory contents
execute_command<command>Run shell command, stream output
find_files<pattern> [root]Glob-pattern file search
grep<pattern> [root]Search file contents by regex

Error Handling

Errors in Colide Code are surfaced as formatted terminal panels. API errors, command failures, and patch errors are all displayed distinctly.

Connection errors
Shown as ✗ Error: Connection failed — check internet. Returns to prompt immediately. No crash.
Timeouts
Streaming timeout is 240s. Command timeout is 90s (300s for install commands). Both reported cleanly without hanging.
Patch failures
If a PATCH block targets lines that no longer match, a [ERROR] patch failed is shown with the mismatch. The file is not modified.
Quota exceeded
Returns HTTP 429. Colide Code shows the error and stops. Check your daily/monthly quota in AI Studio.

Debug mode — Set COLIDE_DEBUG=1 before running Colide Code to enable full Python tracebacks on unexpected errors:

COLIDE_DEBUG=1 colide

Command Reference

/open
Open project dir
/read
Inject file into context
/cd
Change directory
/tree
Print project tree
/help
Show all commands
/scan
Full project audit
/fix
Auto-fix bugs
/review
Code review
/test
Generate tests
/arch
Architecture analysis
/refactor
Refactor code
/optimize
Performance tuning
/security
Vulnerability scan
/debug
Debug errors
/docs
Generate docs
/readme
Generate README
/scaffold
Scaffold project
/explain
Explain code
/commit
Git commit msg
/pr
PR description
/session
Session management
/clear
Clear terminal
/status
Show status
/patch
Apply manual patch
/exit
Quit Colide Code

Environment & OS

Colide Code auto-detects your environment on startup and injects this context into every API call. No configuration needed.

DetectionUsed forExample
OS / platformCommand normalisation, shell selectionmacOS, Linux, Windows
Python commandAlways uses the right python binarypython3, python
Node package managerInstall commands use the detected PMnpm, yarn, pnpm, bun
System package managerFor system-level dependenciesapt, brew, winget, pacman
Project typeInforms AI of framework/language contextNode.js, Python, Go, Rust…
Available toolsAI only suggests tools that exist on the systemgit, docker, node, cargo…

Quick Reference

colide
Launch Colide Code in the current directory
/open ~/projects/myapp
Set working directory to your project
fix the failing tests
Natural language — no slash needed for AI messages
@src/api.py explain this file
Attach a file as context with @mention
/fix
Auto-fix all bugs. Runs the loop until tests pass.
/scan
Full project audit — start here on any new project
Ctrl+C
Stop current generation or command at any time
COLIDE_DEBUG=1 colide
Enable full error tracebacks for debugging
/session new project-name
Start a named session for a new project context
/session load 42
Resume a previous session with full history
pip install colide-code --upgrade
Update to the latest version
/help
Full command list with descriptions