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.
Introduction
/fix, /scan, /review, /patch, /test, /commit, /arch, and more.@path/to/file. Images decoded and sent as base64 context.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.
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
Config schema
{
"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.
██████╗ ██████╗ ██╗ ██╗██████╗ ███████╗ ██╔════╝ ██╔═══██╗██║ ██║██╔══██╗██╔════╝ ██║ ██║ ██║██║ ██║██║ ██║█████╗ ██║ ██║ ██║██║ ██║██║ ██║██╔══╝ ╚██████╗ ╚██████╔╝███████╗██║██████╔╝███████╗ ╚═════╝ ╚═════╝ ╚══════╝╚═╝╚═════╝ ╚══════╝ 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
❯ /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
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.
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
❯ 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
| Command | Description |
|---|---|
| /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). |
| /tree | Print the project directory tree (max depth 4). Excludes common noise dirs. |
| /help | Show all available slash commands with descriptions. |
AI-Powered Project Commands
| Command | Description |
|---|---|
| /scan | Full project audit — architecture, issues, improvements, code quality. |
| /fix | Auto-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. |
| /test | Generate unit tests for the current project or a specific file. |
| /arch | High-level architecture analysis — explain the system and suggest improvements. |
| /refactor [file] | Refactor code for readability, performance, and best practices. |
| /optimize | Performance analysis and optimization recommendations. |
| /security | Vulnerability 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. |
| /readme | Generate 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. |
| /commit | Generate a git commit message from current staged changes. |
| /pr | Generate a pull request title and description from recent commits. |
Session & Utility
| Command | Description |
|---|---|
| /session new [name] | Create a new session with optional name. Clears conversation history. |
| /session load <id> | Load a previously saved session by ID. |
| /session list | List all sessions for the current API key. |
| /session export | Export the current session as a Markdown file. |
| /clear | Clear the terminal screen (also: type clear without slash). |
| /status | Show current session info, API quota usage, and active working directory. |
| /exit | Exit 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
❯ 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
.yml, .toml, .json, .md, .env, .sql, and more..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.
# 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
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
Runs in the working directory. Long-running commands stream live output. Timeout: 90s (300s for install commands).
Surgical line-level edits wrapped in [PATCH]…[/PATCH] blocks. Displayed as red/green diffs in the terminal.
Automatic OS normalisation — Colide Code detects your OS and normalises commands automatically. python → python3, 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
[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
🩹 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 └─
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.
| Context | What completes | Example |
|---|---|---|
| /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
| Command | Behaviour |
|---|---|
| cd <path> | Changes the working directory used by both the shell and Colide's context. Updates the prompt path indicator. |
| clear / cls | Clears the terminal and reprints the Colide Code ASCII banner. |
| ls / ll / la | Passes through to ls with --color=auto. ll/la add -la flags automatically. |
| pwd | Prints 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.
❯ 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
| Format | MIME type | Notes |
|---|---|---|
| .png | image/png | Full support |
| .jpg / .jpeg | image/jpeg | Full support |
| .gif | image/gif | First frame only |
| .webp | image/webp | Full 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.
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
| Parameter | Where | Description |
|---|---|---|
| token | URL query | Your API key from config. |
| session_id | URL query | Active session ID to load conversation history (last 30 messages). |
| message | POST body | Full message including system context, cwd info, and @file contents prepended. |
| image_content | POST body (multipart) | Base64-decoded image file when an @image mention is present. |
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
data: {"token": "Here"}
data: {"token": " is"}
data: {"token": " the fix:"}
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] 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]
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 action | Arguments | Description |
|---|---|---|
| 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.
✗ Error: Connection failed — check internet. Returns to prompt immediately. No crash.[ERROR] patch failed is shown with the mismatch. The file is not modified.Debug mode — Set COLIDE_DEBUG=1 before running Colide Code to enable full Python tracebacks on unexpected errors:
COLIDE_DEBUG=1 colide
Command Reference
Environment & OS
Colide Code auto-detects your environment on startup and injects this context into every API call. No configuration needed.
| Detection | Used for | Example |
|---|---|---|
| OS / platform | Command normalisation, shell selection | macOS, Linux, Windows |
| Python command | Always uses the right python binary | python3, python |
| Node package manager | Install commands use the detected PM | npm, yarn, pnpm, bun |
| System package manager | For system-level dependencies | apt, brew, winget, pacman |
| Project type | Informs AI of framework/language context | Node.js, Python, Go, Rust… |
| Available tools | AI only suggests tools that exist on the system | git, docker, node, cargo… |