# Codeep

Codeep Logo

Deep into Code.

Codeep terminal UI with agent timeline, changed files, checks, and resource estimates

Autonomous AI coding agent that reads your project, runs commands, and writes & verifies code — deeper than autocomplete. Any model (Claude, Gemini, DeepSeek, GLM, OpenAI, or your own local/custom), in the terminal and your editor.

npm version npm downloads license

## Contents - [Install](#installation) · [Quick start](#quick-start) · [Upgrading](#upgrading) - [One agent, every surface](#one-agent-every-surface) · [Features](#features) · [Dashboard](#codeep-dashboard) - [Commands](#commands) · [Keyboard shortcuts](#keyboard-shortcuts) · [Configuration](#configuration) - [Zed (ACP)](#zed-editor-integration-acp) · [VS Code](#vs-code-extension) · [Contributing](#contributing) Full documentation: **[codeep.dev/docs](https://codeep.dev/docs)** ## One agent, every surface Codeep keeps the same project context, provider configuration, sessions, and agent workflow wherever you work: - **[Terminal / TUI](https://codeep.dev/docs/installation)** — the primary CLI experience, with Plan → Read → Edit → Verify → Summary, live file changes, checks, token cost, and estimated energy and cooling-water impact. - **[macOS app](https://codeep.dev/docs/mac)** — a native SwiftUI workbench with project conversations and Run Inspector. - **[VS Code extension](https://github.com/VladoIvankovic/Codeep-vscode)** — the same agent over ACP, directly inside the editor. Also available on the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=VladoIvankovic.codeep). - **[Web dashboard](https://codeep.dev/dashboard)** — synced sessions, usage, costs, tasks, and project activity. ## Installation ### Option 1: npm (Recommended) ```bash npm install -g codeep ``` **Update:** ```bash npm update -g codeep ``` ### Option 2: curl For a machine without Node. The script is served from codeep.dev and fetched from this repository's newest release, so the command does not change if the repository moves. ```bash curl -fsSL https://codeep.dev/install.sh | bash ``` **Custom installation directory:** ```bash curl -fsSL https://codeep.dev/install.sh | INSTALL_DIR=~/.local/bin bash ``` **Specific version:** ```bash curl -fsSL https://codeep.dev/install.sh | VERSION=3.1.1 bash ``` ### Option 3: Manual Binary Download the latest binary for your platform from [GitHub Releases](https://github.com/VladoIvankovic/Codeep/releases): | Platform | Binary | |----------|--------| | macOS Apple Silicon (M1/M2/M3/M4) | `codeep-macos-arm64` | | macOS Intel | `codeep-macos-x64` | | Linux x86_64 | `codeep-linux-x64` | ```bash # Example for macOS Apple Silicon: curl -fsSL https://github.com/VladoIvankovic/Codeep/releases/latest/download/codeep-macos-arm64 -o codeep chmod +x codeep sudo mv codeep /usr/local/bin/ ``` ## Quick Start ```bash # Navigate to your project directory cd /path/to/your/project # Start Codeep codeep # On first run, enter your API key # Get one at: https://z.ai/subscribe?ic=NXYNXZOV14 ``` After installation, `codeep` is available globally in your terminal. Simply run it from any project directory to start coding with AI assistance. ## Upgrading Running `npm install -g codeep@latest` picks up the new version — config, saved profiles, project memory, MCP servers, and skill bundles all carry over. Breaking changes (if any) are listed at the top of each release in [CHANGELOG.md](CHANGELOG.md); the last breaking change was [2.0.0](CHANGELOG.md#200--2026-05-18) (MCP `clientInfo` version bump, transport-agnostic `McpServer` shape). ## Features ### Multi-Provider Support - **Z.AI (ZhipuAI)** — GLM models (Coding Plan & pay-per-use API, international & China) - **OpenAI** — GPT models (flagship, Mini, Nano) - **Anthropic** — Claude models (Fable, Opus, Sonnet, Haiku) - **DeepSeek** — DeepSeek models (Pro, Flash) - **Google AI** — Gemini models (Pro, Flash) - **MiniMax** — MiniMax models (Coding Plan & pay-per-use API, international & China) - **Ollama** — Run any model locally or on a remote server, no API key required. Models are fetched dynamically from your Ollama instance. - **OpenRouter** — One key, 100+ models from Anthropic, OpenAI, Google, Meta, Mistral, DeepSeek, Qwen, xAI and more. Per-call cost reported directly by OpenRouter (matches their dashboard exactly). Use `openrouter/auto` to let OpenRouter pick the best model. Tune routing with `/openrouter prefer|ignore|fallbacks|privacy`. - **Custom (OpenAI-compatible)** — Point Codeep at any self-hosted or proxied OpenAI-compatible endpoint (vLLM, LiteLLM, LM Studio, text-generation-webui). Set the base URL in `/settings` → **Custom Base URL** (config key `customBaseUrl`, e.g. `http://host:8000/v1`), then pick your model with `/model` (fetched from the server's `/models`). No API key required unless your endpoint enforces one. The `openai` provider also honors the `OPENAI_BASE_URL` env var for proxies that serve `gpt-*` model names. - Switch between providers with `/provider` - Configure different API keys per provider - Both OpenAI-compatible and Anthropic API protocols supported ### Project Context Awareness When started in a project directory, Codeep automatically: - Detects project type (Node.js, Python, etc.) - Reads file paths mentioned in your messages - Attaches file contents to conversations - Understands your project structure - Can suggest and apply code changes (with write permission) ### Session Management - **Auto-save** - Conversations are automatically saved - **Session picker** - Choose which session to continue on startup - **Per-project sessions** - Sessions stored in `.codeep/sessions/` - **Rename sessions** - Give meaningful names with `/rename` - **AI session titles** - Sessions auto-title themselves with an LLM one-liner ("OAuth2 migration for auth module") instead of a truncated first message. This makes one small background API call per session; turn it off with the `autoSessionTitle` setting (`/settings`) if you prefer zero unsolicited calls - **Search current session** - Find text in the open conversation with `/search` - **Cross-session recall** - `/recall ` searches across **all** saved sessions, ranked by relevance + recency. Add `--resume` to load the top match, or `--summarize` for an LLM recap of what you accomplished across matches - **Cross-device resume (`/cloud`)** - Sessions you run on one device (CLI, Mac app, VS Code) sync to `codeep.dev`. `/cloud` lists them and pulls the selected one back locally, so you can start a session on your desktop and continue on your laptop. Run `codeep account` once to link your devices; scoped to the current project when one is open. - **Export** - Save to Markdown, JSON, or plain text - `/cost` - Per-session token usage and estimated cost (per provider/model) - `/compact [keepN]` - AI-summarize older messages to free up context (keeps last N, default 4) - `/checkpoint [name]` - Snapshot the current session (conversation + provider/model + agent-touched files + git HEAD) - `/checkpoints` - List saved checkpoints for this workspace - `/rewind ` - Restore a checkpoint; file rollback is handled via git (hint printed after rewind) ### Git Integration - `/diff` - Review unstaged changes with AI assistance - `/diff --staged` - Review staged changes - `/commit` - Generate conventional commit messages ### Code Block Management - Automatic syntax highlighting for 12+ languages - Copy code blocks to clipboard with `/copy [n]` - Code blocks are numbered for easy reference ### Clipboard Paste - **`/paste` command** - Paste content from clipboard into chat - Type `/paste` and press Enter to read clipboard content - Shows preview with character/line count before sending - Press Enter to send, Escape to cancel - Works reliably in all terminals (no Ctrl+V issues) ### File Context (`/add`, `/drop`, `@mentions`) Explicitly add files to the conversation context: - **`/add `** - Add one or more files to context - **`/add`** (no args) - Show currently added files - **`/drop `** - Remove a specific file from context - **`/drop`** (no args) - Remove all files from context - **`@path/to/file`** - Inline mention: type `@` followed by a file path anywhere in your message and its contents are attached for that message only. Supports relative paths (`@src/index.ts`), absolute (`@/etc/hosts`), home (`@~/.codeep/profile.md`), and quoted paths with spaces (`@"my file.ts"`). In the CLI, typing `@` opens an autocomplete file picker — ↑↓ to navigate, Tab to insert. - **`@folder `** (alias `@dir`) - Attach an entire directory: type `@folder src/components` and every source file under it is loaded recursively. Skips `node_modules`, `.git`, `dist`, binary extensions (images, archives, lockfiles), and files over the per-file size cap. Stops at a 200 KB total cap per mention (with a notification when it hits the limit). Quoted paths supported: `@folder "my components"`. - **`@web `** - Inline web fetch: type `@web https://example.com/docs` (or `@web example.com/docs`) and the page is fetched, converted to readable text, and attached to the message. HTML is stripped; plain text and JSON pass through as-is. Capped at 32 KB, 12 s timeout. Successful fetches are cached for 30 min (per session, up to 50 entries) so repeated `@web` for the same URL is instant and free; use `/web-cache clear` to reset. - **`@git `** - Inline git context: type `@git diff`, `@git diff --staged`, `@git HEAD`, `@git `, `@git main:src/x.ts`, or `@git diff a..b` to inject that diff / commit / file-at-ref into the message as a `[Git ref]` block. Capped at 64 KB per mention (truncated with a marker). Unknown refs surface a friendly failure note. Added files (via `/add`) are automatically attached to every message (both chat and agent mode) until dropped. `@mentions` are per-message — handy for one-off references without polluting the persistent context. ``` > /add src/utils/api.ts src/types/index.ts Added 2 file(s) to context (2 total) > refactor the API client to use async/await # AI sees both files attached to your message > review @src/auth/login.ts for security issues Loaded 1 file(s) from @mentions # AI sees login.ts attached for this message only > /drop Dropped all 2 file(s) from context ``` ### Multi-line Input Write multi-line messages using backslash continuation or `/multiline` mode: - **Backslash continuation** — end a line with `\` and press Enter to continue on the next line - **`/multiline`** — toggle multi-line mode where Enter adds a new line and Esc sends the message ``` > Write a function that\ takes two arguments and\ returns their sum # Sent as a single 3-line message > /multiline Multi-line mode ON — Enter adds line, Esc sends M> (type freely, Enter = newline, Esc = send) ``` ### Autonomous Agent Mode Codeep works as a **full AI coding agent** that autonomously: - Creates, edits, and deletes files - Executes shell commands (npm, git, build, test, etc.) - Reads and analyzes your codebase - Loops until the task is complete - Reports all actions taken - **Live code display** - Shows syntax-highlighted code in chat as it writes/edits files **Auto mode (default)**: Just describe what you want - no special commands needed: ``` > add error handling to src/api/index.ts > run tests and fix any failures > create a new React component for user settings ``` **Manual mode**: Use `/agent ` when you want explicit control. > **Note for Ollama users:** Agent mode requires a capable model — at least **7B parameters** (e.g. `qwen2.5-coder:7b`, `llama3.1:8b`). Smaller models (1–3B) lack the instruction-following capacity for reliable tool use and may produce incorrect output. For small models, set Agent Mode to **Manual** or **Off** in `/settings`. **Agent Tools:** | Tool | Description | |------|-------------| | `read_file` | Read file contents | | `write_file` | Create or overwrite files | | `edit_file` | Edit specific text in files | | `delete_file` | Delete files or directories | | `create_directory` | Create folders | | `list_files` | List directory contents | | `execute_command` | Run shell commands | | `search_code` | Search for patterns in code | | `fetch_url` | Fetch content from URLs | ### Undo & History - **Undo actions** - Revert any file change the agent made - **Session history** - View and restore from previous agent sessions - **Action tracking** - All file operations are logged for review ### Context Persistence - **Save conversations** - Continue where you left off - **Per-project context** - Each project maintains its own history - **Automatic summarization** - When prior history overflows the agent's context budget, the dropped (oldest) messages are condensed into a short recap (decisions, constraints, unfinished threads) instead of being silently truncated — so long sessions don't forget how they started. One cheap LLM call, made only on overflow and cached per session; opt out with `autoSummarizeHistory: false` (`/settings`) ### Web & MCP Tools - Agent can fetch documentation and web content - Automatic HTML-to-text conversion - **MCP-powered tools** (for Z.AI and Z.AI China providers): - `web_search` — Search the web for current information - `web_reader` — Fetch and read any web page - `zai_analyze_image` — Analyze images via Z.AI Vision (GLM-4V) - `minimax_understand_image` — Analyze images via MiniMax vision - **Image paste** — Ctrl+V an image directly into the terminal to send it to a vision model - MCP tools run as secure sub-processes with structured I/O ### Smart Context Agent automatically gathers relevant files before making changes: - Analyzes imports and dependencies - Reads related type definitions - Understands project structure - Prevents duplicate code and inconsistencies ### Code Review Mode AI-powered review of your git diff with `/review`: - **Bugs** — logic errors, off-by-one, null/undefined issues - **Security** — injection, auth issues, exposed secrets - **Performance** — unnecessary loops, memory leaks - **Edge cases** — unhandled inputs, missing error handling - References file names and line numbers from the diff ``` > /review # AI review of unstaged changes > /review --staged # AI review of staged changes > /review --static # Static regex analysis with score (0-100) ``` If there are no git changes, falls back to static analysis automatically. #### Custom rules (`.codeep/review.yml` or `.codeep/review.json`) The static reviewer (`codeep review` / `/review --static`) ships a set of built-in rules, but a project can tailor them — check a `.codeep/review.yml` (or `.codeep/review.json`) into the repo and the CLI **and** the [Codeep GitHub Action](https://github.com/VladoIvankovic/codeep-action) both pick it up automatically (zero LLM cost). YAML is preferred when present and is nicer for regexes — single-quoted YAML keeps backslashes literal (`pattern: '\bfoo\('`) so you avoid JSON's double-escaping: ```yaml # .codeep/review.yml rules: - id: no-internal-import pattern: "from ['\"]@acme/internal" category: best-practice severity: error message: Don't import from @acme/internal outside the platform team suggestion: Use the public @acme/sdk package extensions: [.ts, .tsx] disable: [todo-comment, anonymous-function] include: ['src/**'] exclude: ['**/*.test.ts', 'vendor/**'] ``` The same config as JSON: ```json { "rules": [ { "id": "no-internal-import", "pattern": "from ['\"]@acme/internal", "category": "best-practice", "severity": "error", "message": "Don't import from @acme/internal outside the platform team", "suggestion": "Use the public @acme/sdk package", "extensions": [".ts", ".tsx"] } ], "disable": ["todo-comment", "anonymous-function"], "include": ["src/**"], "exclude": ["**/*.test.ts", "vendor/**"] } ``` - **`rules`** — your own checks. `id`, `pattern` (a regex string), and `message` are required; `flags` (default `g`), `category`, `severity` (`error|warning|info|suggestion`), `suggestion`, and `extensions` are optional. - **`disable`** — turn off built-in rules by id. Run `codeep review --rules` for the live list; the built-in ids are: `eval-usage`, `inner-html`, `dangerously-set-inner-html`, `hardcoded-password`, `hardcoded-api-key`, `foreach-await`, `await-in-loop`, `select-star`, `loose-null-check`, `empty-catch`, `console-statement`, `todo-comment`, `any-type`, `ts-ignore`, `as-any`, `var-usage`, `anonymous-function`, `missing-jsdoc`, `long-file`, `long-function`. - **`include` / `exclude`** — glob scoping (`**`, `*`, `?`); `include` empty = all files. A missing, malformed, or partially-invalid config never breaks a review — bad entries are skipped and the run proceeds with whatever is valid. **More review commands:** - `codeep review --rules` — list the built-in rule ids (above) and exit. - `codeep review --ai` — after the offline pass, get an advisory AI second opinion on the working-tree diff from your configured provider (needs an API key; never changes the exit code, so CI stays deterministic). - `codeep hook install` — install a git pre-commit hook that reviews the working-tree content of your staged files and blocks the commit on failures (`--pre-push` for pre-push, `--fail-on ` to set the threshold, `codeep hook uninstall` to remove). Stage changes fully before committing. ### Interactive Mode Agent asks clarifying questions when tasks are ambiguous: ``` You: "add authentication" Agent: "What type of authentication do you want? a) JWT tokens b) Session-based c) OAuth (Google/GitHub)" ``` ### Diff Preview See exactly what will change before applying: ```diff - const user = getUser(); + const user = await getUser(); ``` ### Learning Mode Agent learns your coding preferences: - Indentation style (tabs/spaces) - Quote style (single/double) - Naming conventions - Preferred libraries - Custom rules you define ### User Profile (`/me`) A durable, human-readable description of **you** that Codeep injects into the agent's context on every run — so it adapts to how you work (reply language, response style, default stack, "always / never" rules). It flows to every surface (terminal, VS Code, Zed) since they share the same files. Two layers: - **`~/.codeep/profile.md`** — global: who you are across all projects - **`.codeep/profile.md`** — project: your role, goals, and constraints for this repo Commands: - `/me` — view your profile + status - `/me init [project]` — scaffold a template to fill in - `/me on` / `/me off` — toggle injection - `/me learn [on|off]` — opt-in auto-learn: Codeep extracts durable preferences from sessions and merges them into `profile.learned.md` (kept separate from your hand-written file). Off by default. - `/me learn project` — one-off learn scoped to this repo - `/me forget` — clear the auto-learned profile(s) Sync your global profile across machines (and edit it on the web) from the [dashboard](https://codeep.dev/dashboard): `/me sync` (or `codeep account sync`, which now carries the profile too). In VS Code: **Codeep: Edit Profile**, **Codeep: Toggle Profile Auto-Learn**, **Codeep: Sync Profile to Dashboard**. ### Sub-agents (delegation) The agent can delegate a self-contained sub-task to a specialist **sub-agent** that runs in its own fresh context window and returns only a summary — keeping the main context small and letting each sub-task run with a tuned persona and scoped tools. Built-ins: - **`planner`** — read-only; investigates, then returns a step-by-step implementation plan - **`researcher`** — read-only; explores the codebase/web and returns a tight, cited summary - **`reviewer`** — read-only; senior review for correctness, security, and design - **`tester`** — writes and runs tests, iterates to green Run `/agents` to list them. The agent invokes them itself via the `delegate` tool (you'll see `⤷ : …` lines). Add your own with a frontmatter `.md` in `.codeep/agents/.md` (project) or `~/.codeep/agents/.md` (global): ```markdown --- name: migrator description: Writes and runs database migrations tools: [read_file, write_file, edit_file, execute_command] # allowlist; omit = all model: glm-5.2 # optional override personality: senior-reviewer # optional preset maxIterations: 12 # optional budget --- You write safe, reversible DB migrations… ``` `tools` is an allowlist enforced at dispatch (a `researcher` literally can't write files). Sub-agents inherit your profile + project rules, and their changes are covered by `/undo`. **Guaranteed review:** enable **Agent Auto-Review** in `/settings` (`agentAutoReview`) and after any run that changes files, Codeep automatically delegates to the `reviewer` and appends its findings — a review stage that always happens. Off by default. ### Project Rules Define project-specific instructions that the AI always follows. Create a rules file in your project root (first non-empty file wins): - **`.codeep/rules.md`** - Primary location (inside `.codeep/` folder) - **`CODEEP.md`** - Alternative location (project root, similar to `CLAUDE.md` or `.cursorrules`) - **`AGENTS.md`** - Cross-tool standard (works with Claude Code, Cursor, Kilo Code — no duplication needed) The rules file content is automatically included in every system prompt — both chat and agent mode. Use it to define: - Coding standards and conventions - Preferred libraries and frameworks - Architecture guidelines - Language-specific instructions - Any custom rules for AI behavior in your project **Example `.codeep/rules.md`:** ```markdown ## Code Style - Use 2 spaces for indentation - Prefer arrow functions - Always use TypeScript strict mode ## Architecture - Follow MVC pattern - Keep controllers thin, logic in services - All API responses use the ApiResponse wrapper ## Libraries - Use Zod for validation - Use date-fns instead of moment.js ``` Rules are loaded automatically when Codeep starts — no commands needed. ### Skills System Predefined workflows for common development tasks. Execute with a single command: ``` /commit - Generate commit message and commit /test - Generate tests for current code /docs - Add documentation to code /refactor - Improve code quality /fix - Debug and fix issues /component - Generate React/Vue component /docker - Generate Dockerfile ``` **50+ Built-in Skills:** | Category | Skills | |----------|--------| | **Git** | `/commit` (`/c`), `/amend`, `/push` (`/p`), `/pull`, `/pr`, `/changelog`, `/branch`, `/stash`, `/unstash` | | **Testing** | `/test` (`/t`), `/test-fix`, `/coverage`, `/e2e`, `/mock` | | **Documentation** | `/docs` (`/d`), `/readme`, `/explain` (`/e`), `/api-docs`, `/translate` | | **Refactoring** | `/refactor` (`/r`), `/types`, `/optimize` (`/o`), `/cleanup`, `/modernize`, `/migrate`, `/split`, `/rename` | | **Debugging** | `/debug` (`/b`), `/fix` (`/f`), `/security`, `/profile`, `/log` | | **Deployment** | `/build`, `/deploy`, `/release`, `/publish` | | **Code Generation** | `/component`, `/api`, `/model`, `/hook`, `/service`, `/page`, `/form`, `/crud` | | **DevOps** | `/docker`, `/ci`, `/env`, `/k8s`, `/terraform`, `/nginx`, `/monitor` | **Shortcuts:** Many skills have single-letter shortcuts (shown in parentheses). **Skill Parameters:** Many skills accept parameters: ``` /component UserCard # Generate component named UserCard /api users method=POST # Generate POST endpoint for users /migrate "React 18" # Migrate to React 18 /model User fields=name,email # Generate User model with fields ``` **Skill Chaining:** Run multiple skills in sequence with `+`: ``` /commit+push # Commit then push /test+commit+push # Test, commit if pass, then push /build+deploy # Build then deploy ``` **Search Skills:** ``` /skills docker # Find skills related to docker /skills testing # Find testing-related skills ``` **Custom Skills:** Create your own skills: ``` /skill create my-workflow # Creates template in ~/.codeep/skills/ /skill delete my-workflow # Delete custom skill /skill help commit # Show skill details ``` Custom skill example (`~/.codeep/skills/my-workflow.json`): ```json { "name": "my-workflow", "description": "My custom workflow", "shortcut": "m", "parameters": [ { "name": "target", "description": "Target environment", "required": true } ], "steps": [ { "type": "command", "content": "npm run build" }, { "type": "confirm", "content": "Deploy to ${target}?" }, { "type": "agent", "content": "Deploy the application to ${target}" }, { "type": "notify", "content": "Deployed to ${target}!" } ] } ``` ### MCP (Model Context Protocol) Full spec coverage in 2.0.0 — stdio and Streamable HTTP transports, tools / resources / prompts / sampling, capability negotiation with `roots`, auto-restart on crash, mid-run catalog refresh. **Four ways to wire MCP servers** (all merge; project > `.mcp.json` > global > ACP wins last): 1. **Project config** — `.codeep/mcp_servers.json` (committed with the repo) 2. **`.mcp.json`** — cross-tool standard at the workspace root (works with Claude Code, Cursor, Kilo Code — point everyone at the same file) 3. **Global config** — `~/.codeep/mcp_servers.json` (per machine) 4. **ACP client config** — Zed / Claude Desktop pass `mcpServers` on `session/new` Two transports per entry, mutually exclusive: ```json { "mcpServers": { "fs": { "command": "npx", "args": ["@modelcontextprotocol/server-filesystem", "/path"] }, "remote": { "url": "https://mcp.example.com/", "headers": { "Authorization": "Bearer …" } } } } ``` Manage interactively from any Codeep client: ```bash /mcp # list connected servers + tools + spawn errors /mcp browse # 12 curated servers (filesystem, github, postgres, …) /mcp browse # details + env-var hints for one entry /mcp install [extra args] # wires it into project config + spawns /mcp add [args] /mcp remove /mcp reload # re-read config after a manual edit /mcp resources # list resources servers expose /mcp read # fetch one resource's contents /mcp prompts # list prompt templates /mcp prompt key=val ``` Resources and prompts also surface as **virtual tools** the agent can call natively — `__resource_list`, `__resource_read`, `__prompt_list`, `__prompt_get`. No need to type `/mcp read` yourself; the model decides when to fetch. If a server opts into the `sampling` capability, Codeep hosts LLM completions on its behalf — routes through your active provider. If it opts into `roots/list`, we expose the current workspace folder. In the VS Code extension, the same operations are available from the command palette (no JSON editing required): - **Codeep: Add MCP Server…** — wizard that writes to project or global config - **Codeep: Remove MCP Server…** — quick-pick from both scopes - **Codeep: Open MCP Servers Config** — opens the JSON file directly Each server is spawned as a child process; its tools are surfaced under `__`. MCP tool definitions are automatically injected into the agent's tool catalog on each iteration, so the model picks them alongside built-ins without you having to mention them by name. Lifecycle is per-session: servers are torn down when the session is deleted or the CLI exits (SIGTERM/SIGINT). The VS Code extension and the direct `codeep` CLI both read the same config files, so a server you configure once is available everywhere. A server that crashes is auto-restarted (up to 3 times in a 60 s window, with exponential backoff). Persistent failures are reported in `/mcp` so you don't have to hunt through stderr. The `roots` capability is advertised in the MCP handshake, so filesystem-shaped servers can scope their reads to the current workspace. Hooks apply to MCP tools too: `pre_tool_call` can block a `__` call, and `on_error` fires when it fails. See **Lifecycle Hooks** below. ### Lifecycle Hooks Drop executable shell scripts in `.codeep/hooks/.sh` and Codeep runs them at the relevant moment during a session. Generalises what `agentAutoCommit` and `agentAutoVerify` do — anything those can do, a `post_edit` hook can do too. | Event | When | Blocking? | |---|---|---| | `pre_tool_call` | Before every agent tool call (including MCP `__`) | **Yes** — non-zero exit blocks the call | | `post_edit` | After `write_file` / `edit_file` succeeds (built-in only) | No (advisory: auto-format / auto-lint) | | `on_error` | When any tool call fails (built-in or MCP) | No (logging / alerting) | | `pre_commit` | Before the `/commit` skill stages anything | **Yes** — non-zero exit blocks the commit | `pre_tool_call` and `on_error` apply uniformly to built-in tools (`read_file`, `execute_command`, …) and MCP tools (`fs__read_file`, `gh__create_issue`, …). A policy script can therefore allow-list or deny MCP calls just like any other agent action. Each hook receives `CODEEP_HOOK_EVENT`, `CODEEP_WORKSPACE`, `CODEEP_SESSION_ID`, plus event-specific extras (`CODEEP_HOOK_TOOL`, `CODEEP_HOOK_PARAMS`, `CODEEP_HOOK_FILE`). Example — auto-format on edit (`.codeep/hooks/post_edit.sh`): ```bash #!/bin/bash prettier --write "$CODEEP_HOOK_FILE" 2>/dev/null ``` Run `/hooks` to see which hooks are installed in the current workspace. **Trust required (security).** Because hooks run arbitrary shell, a freshly cloned repo's hooks are **not** run until you approve the workspace. Run `/hooks trust` to enable them for the current project (revoke with `/hooks untrust`); `/hooks` and the welcome banner show the trust state. Your own projects just need a one-time `/hooks trust`. Global `~/.codeep/hooks/` are never run for the same reason. #### Windows notes Lifecycle hooks are POSIX shell (`.sh`) scripts: - **macOS / Linux** — run directly (via the script's shebang). No setup. - **Windows** — a `.sh` needs a POSIX `sh`. Install [Git for Windows](https://git-scm.com/download/win) (it ships `sh.exe`) and Codeep runs `.sh` hooks through it automatically — no PATH tweaking needed if Git is installed to its default location. **Without a POSIX shell**, `/hooks` and the welcome banner report an explicit *"cannot run on this system"* state and hooks are skipped — they never block a tool call or commit, and the rest of Codeep is unaffected. (`.ps1`/`.cmd` hooks are not executed; keep hook logic in `.sh`.) Everything else is **Node-native and shell-independent on Windows**: project rules (`AGENTS.md` / `CODEEP.md` / `.codeep/rules.md`), custom slash commands (`.codeep/commands/*.md`), and skill bundles (`.codeep/skills/`) are Markdown; MCP config (`.mcp.json` / `.codeep/mcp_servers.json`) is JSON. MCP servers spawn via their configured `command` — `npx` resolves through `npx.cmd`, and a custom `command` like `python` just needs to be on your PATH. ### Skill Bundles (new in 2.0) Beyond the built-in skills and custom slash commands, Codeep now supports **structured skill bundles** — directory-based capability packs the agent discovers and invokes on its own. A bundle is a directory `.codeep/skills//SKILL.md` (project-scoped) or `~/.codeep/skills//SKILL.md` (global). The file is Markdown with a YAML frontmatter header — the format is a **superset of Claude Code skills**, so existing skills drop in unchanged: ```markdown --- name: deploy-staging description: Deploy the current branch to staging via npm scripts. triggers: [deploy, ship, release] # Optional Codeep-specific extensions: codeep-min-version: 2.0.0 codeep-requires-mcp: [postgres] allowed-tools: [read_file, write_file, execute_command] version: 0.1.0 --- # deploy-staging Run the test suite, build, then `npm run deploy:staging`. If the build fails, surface the error and stop — don't deploy a broken build. ``` The agent gets the bundle catalog injected into its system prompt on every iteration and can invoke any bundle via the `invoke_skill` tool: - `/skills bundles` — list installed bundles - `/skills create-bundle ` — scaffold a new project skill - `/skills show ` — print the SKILL.md - `/skills browse [query]` — search the public marketplace - `/skills install /` — pull from marketplace - `/skills publish [--public]` — share to codeep.dev - `/skills unpublish /` — remove your published skill **Web marketplace:** publish skills to [codeep.dev/skills](https://codeep.dev/skills) as public (browseable by anyone) or private (only you). Manage your published skills at `/dashboard/skills`. From the VS Code extension, use the **Codeep: Browse Skill Bundles…** / **Codeep: Create Skill Bundle…** / **Codeep: Open Skills Folder** commands. ### Custom Slash Commands Drop a Markdown file in `.codeep/commands/.md` (project-scoped) or `~/.codeep/commands/.md` (global, all projects) and Codeep exposes it as `/` — in the TUI, Zed, and the VS Code extension. The body becomes the user prompt; the agent handles it normally. Example — `.codeep/commands/sec-review.md`: ```markdown --- description: Security review of a file aliases: [sec, secrev] --- Please perform a thorough security review of {{args}}. Look for: - AuthN/AuthZ bypasses, SQL/NoSQL injection, XSS, CSRF - Path traversal, insecure deserialization - Hardcoded secrets, race conditions Report findings ordered by severity. ``` Then call it as `/sec-review src/api/login.ts` (or `/sec` via the alias). **Placeholders** (Claude Code-compatible): - `{{args}}` and `$ARGUMENTS` — full args string - `{{arg1}}`, `{{arg2}}` … — positional args **Discovery:** `/commands` lists all available templates. Project files shadow global files with the same name. Aliases also work for autocomplete. ### Personalities and custom bots (`/personality`) Built-in personalities change tone and priorities. A structured custom bot can also pin a model, restrict runtime tools, and limit where it is available: ``` /personality # list available /personality concise # short answers, no preamble /personality security # treat every input as hostile /personality senior-reviewer # push back on shortcuts, name things well /personality ship-it # pick first reasonable approach /personality off # back to default tone ``` Six built-in presets: `concise`, `verbose`, `security`, `senior-reviewer`, `junior-mentor`, `ship-it`. The active one persists across sessions (stored in `~/.codeep/config.json` as `activePersonality`). **Custom bots** — build one in **Dashboard → Agent Studio**, or drop a Markdown file in `.codeep/personalities/.md` (project) or `~/.codeep/personalities/.md` (global): ```markdown --- codeep: custom-bot/v1 description: Reviews changes without modifying the project. model: automatic tools: [files, git] scope: selected projects: [Codeep] --- # PR Reviewer ## Responsibility Review the requested change and cite concrete evidence. ## Always - Call out untested behavior. ## Never - Modify files or publish changes. ## Advanced instructions Keep the tone collaborative and end with the highest-risk finding. ``` Portable tool groups are `files`, `terminal`, `tests`, `git`, `web`, and `mcp`; unselected groups are removed from the model's runtime and checked again before execution. Missing, empty, or malformed `tools` metadata in a v1 file creates a conversation-only bot. Use `scope: all`, `selected`, or `personal`; selected scope matches the project directory basename against `projects` (with optional `*` and `?` wildcards). An exact `provider/model` applies only to that run, while `automatic` inherits the current selection. Portable v1 fails closed for unclassified capabilities: Skills, delegation, and vision are not exposed to structured bots yet. MCP is available only when the active ACP session has registered those exact tools. Legacy prompt-only Markdown remains supported and unrestricted. The older section-only Agent Studio format is recognized when it contains `Responsibility` plus another standard section; without a Tools section it also stays unrestricted until explicitly converted. Invalid structured model or scope metadata makes the bot unavailable rather than silently widening its runtime. An explicit unsupported `codeep` schema marker is also unavailable; it is never reinterpreted as legacy. Project files shadow global files, which shadow built-ins with the same name. ### Activity Insights (`/insights`, new in 2.0.3) Summarise what the agent has actually done for you over a window — runs, tool actions, projects touched, most-edited files — sourced from `~/.codeep/history/.json` (one file per agent run, automatic). ``` /insights # last 7 days (default) /insights --days 30 # last month /insights --days 1 # today only ``` Surfaces (markdown rendered in chat): - Headline tally: runs · actions · active time · active-days density · avg actions/run - **By project** sorted by active time - **Top tools** (read_file × 340, write_file × 80, …) - **Most-touched files** (with `~` prefix for readability) - **Recent runs** — 10 most recent with project, duration, and the user prompt that started them Cost / token usage isn't in `/insights` (it lives in `/cost` per-session since the token tracker is in-memory). Insights is history-only. ### Project Intelligence (`/init`, `/scan`) Initialize a project and scan it once to cache deep analysis for faster AI responses: ``` /init # Initialize project — creates .codeep/ folder /scan # Full project scan - analyzes structure, dependencies, patterns /scan status # Show last scan info (age, file count, project type) /scan clear # Clear cached intelligence /memory # Add a custom note to project intelligence /memory list # Show all notes with indices /memory remove # Remove note by index /memory clear # Clear all notes ``` **What gets analyzed and cached:** | Category | Information | |----------|-------------| | **Structure** | File count, directory tree, language distribution (respects `.gitignore`) | | **Dependencies** | Runtime & dev dependencies, detected frameworks | | **Architecture** | Patterns (MVC, Component-based), main modules, entry points | | **Scripts** | Available npm/composer/make scripts | | **Conventions** | Indentation style, quotes, semicolons, naming conventions | | **Testing** | Test framework, test directory location | | **DevOps** | CI/CD system (GitHub Actions, GitLab CI, CircleCI, Azure, Travis, Jenkins, Drone), containerization (Docker, docker-compose, Kubernetes, Helm), monorepo tooling (Turborepo, Nx, Lerna, pnpm/Yarn workspaces, Rush) | **Benefits:** - AI understands your project deeply without re-analyzing each time - Faster responses - no need to scan files repeatedly - Consistent context across sessions - Framework-aware suggestions (React, Vue, Express, Django, etc.) You can also add your own notes to the project intelligence with `/memory`: ``` /memory Always use pnpm, never npm /memory Main entry point is src/renderer/main.ts /memory Database migrations are in db/migrations/ ``` Notes are included in every AI and agent conversation for this project. **Storage:** `.codeep/intelligence.json` (project-local) **Example output:** ``` # Project: my-app Type: TypeScript/Node.js ## Structure - 156 files, 24 directories - Languages: TypeScript React (89), TypeScript (45), JSON (12) - Main directories: src, components, utils, hooks ## Frameworks React, Next.js ## Architecture Patterns: Component-based, File-based routing Main modules: src, components, hooks, utils ## Available Scripts - dev: next dev - build: next build - test: vitest ## Code Conventions - Indentation: spaces - Quotes: single - Semicolons: no - Naming: camelCase ## DevOps - CI/CD: GitHub Actions - Containerization: Docker, docker-compose - Monorepo: Turborepo ``` ### Self-Verification (Optional) When enabled in Settings, the agent can automatically verify its changes by running build, tests, or type checking after completing a task. Disabled by default — the agent works freely and you decide when to verify. Configure in **Settings → Agent Auto-Verify**: - **Off** (default) — no automatic verification - **Build only** — checks compilation after changes - **Typecheck only** — runs TypeScript/PHP type checking - **Test only** — runs test suite after changes - **Build + Typecheck + Test** — full verification If errors are found, the agent tries to fix them automatically (up to 3 attempts, configurable). **Supported project types:** | Language | Build | Test | Type Check | |----------|-------|------|------------| | **Node.js/TypeScript** | npm/yarn/pnpm/bun run build | npm test, vitest, jest | tsc --noEmit | | **Python** | - | pytest | - | | **Go** | go build | go test | - | | **Rust** | cargo build | cargo test | - | | **PHP/Laravel** | composer run build | phpunit, artisan test | php -l (syntax) | ### Security Features - API keys stored securely (macOS Keychain / Linux Secret Service) - Per-project permissions (read-only or read-write) - Input validation and sanitization - Configurable rate limiting - Agent sandboxed to project directory - Dangerous commands blocked (rm -rf /, sudo, etc.) - Configurable confirmation per tool — choose which agent actions require approval via `/settings` ## Codeep Dashboard Link your CLI to [codeep.dev](https://codeep.dev/dashboard) for a personal web dashboard with session stats, project tracking, task management, and API key sync. ```bash codeep account # Opens browser → sign in with GitHub → CLI is linked ``` ### Dashboard features - **Usage stats** — total sessions, active this week, model/provider breakdown, token usage, estimated cost per model, 30-day trend - **Projects** — all projects Codeep was used in, with language tag and git indicator - **Project archiving** — hide projects from the list with one click - **Tasks** — create/complete bug, feature, and task items from the web or directly from the CLI with `/tasks add` and `/tasks done` - **API key sync** — store provider keys securely on codeep.dev, sync to any machine in one command - **Personal config sync** — personalities and custom slash commands sync across machines; view and prune them on the dashboard - **Connected devices** — see all machines linked to your account (hostname, last seen), revoke access per device ### API key sync Add keys once on the dashboard, then sync them to any machine: ```bash codeep account sync # Pull keys + config from codeep.dev → local codeep account push # Push local keys + config → codeep.dev ``` Keys are encrypted at rest using AES-256-GCM. ### Personal config sync `account sync` / `account push` also carry your **personalities** and **custom slash commands** between machines — the Markdown files in `~/.codeep/personalities/` and `~/.codeep/commands/`: ```bash codeep account push # Upload local personalities + commands to codeep.dev codeep account sync # Download them onto a new machine ``` A manual `sync` treats the dashboard personality as current. When a changed cloud personality replaces a local file, Codeep first saves the local version under `~/.codeep/backups/personalities/` and then swaps the new file in atomically. Custom commands keep the older **additive** merge and are never overwritten by a pull. View and edit custom bots in **Agent Studio**, and prune commands under **Custom commands**, on the [dashboard](https://codeep.dev/dashboard). Hooks and MCP server configs are deliberately **not** synced: hooks run arbitrary shell, and MCP configs often embed tokens, so both stay local to each machine. ### Privacy & telemetry Once your CLI is linked, Codeep automatically uploads usage stats (model, provider, token counts, estimated cost), session transcripts, `progress.md`, and project memory notes to power your dashboard. To opt out of **all** of these automatic uploads: ```bash export CODEEP_NO_TELEMETRY=1 # also honors the cross-tool DO_NOT_TRACK=1 ``` …or set it permanently in `~/.codeep/config.json`: ```json { "telemetry": false } ``` With telemetry off, nothing is uploaded automatically — the agent still runs fully and talks to your LLM provider directly. Explicit `codeep account push` / `account sync` commands are always under your control and are never gated by this flag. ### Tasks Create, view, and complete tasks directly from the CLI — or manage them on the codeep.dev dashboard: ``` > /tasks # List pending tasks for current project (numbered) > /tasks add Fix login bug # Create a new task on the dashboard > /tasks done 2 # Mark task #2 as done > /tasks delete 2 # Delete task #2 permanently ``` Tasks are loaded into the agent context so the AI sees them automatically on the next message. ## Commands ### General | Command | Description | |---------|-------------| | `/help` | Show help and available commands | | `/status` | Show current configuration status | | `/version` | Show version and current provider/model | | `/update` | Check for updates | | `/clear` | Clear chat history and start new session | | `/exit` or `/quit` | Quit application | ### AI Configuration | Command | Description | |---------|-------------| | `/provider` | Switch AI provider | | `/model` | Switch AI model | | `/model ` | Load a saved profile shortcut (e.g. `/model fast`) | | `/protocol` | Switch API protocol (OpenAI/Anthropic) | | `/lang` | Set response language (12 languages supported) | | `/settings` | Adjust temperature, max tokens, timeout, rate limits | | `/profile save ` | Save current provider+model as a named profile | | `/profile load ` | Load a saved profile | | `/profile ` | Shorthand for `/profile load ` | | `/profile list` | List all saved profiles | | `/profile delete ` | Delete a saved profile | | `/cost` `/stats` | Show session token usage and estimated API cost per model | **Model favorites** — save provider+model combos and switch instantly: ``` > /provider # switch to z.ai > /model glm-5.2 > /profile save fast > /provider # switch to openai > /model gpt-5.6-sol > /profile save work > /model fast # instantly switch to z.ai / glm-5.2 > /model work # instantly switch to openai / gpt-5.6-sol ``` ### Session Management | Command | Description | |---------|-------------| | `/sessions` | List and load saved sessions | | `/sessions delete ` | Delete a specific session | | `/cloud` | List and resume sessions synced from other devices | | `/rename ` | Rename current session | | `/search ` | Search through chat history | | `/export` | Export chat to MD/JSON/TXT format | ### Code & Files | Command | Description | |---------|-------------| | `/apply` | Apply file changes from AI response (shows hunk counts; `--only file.ts:0,1` for selective apply, `--interactive`/`-i` for per-hunk review) | | `/web-cache` | Show `@web` fetch cache stats (alias `/web-cache clear` to reset) | | `/copy [n]` | Copy code block to clipboard (n = block number, -1 = last) | | `/paste` | Paste content from clipboard into chat | | `/add ` | Add file(s) to conversation context | | `/drop [path]` | Remove file (or all) from context | | `/multiline` | Toggle multi-line input mode | ### Agent Mode | Command | Description | |---------|-------------| | `/grant` | Grant write permission for agent (opens permission dialog) | | `/agent ` | Run agent for a specific task (manual mode) | | `/agent-dry ` | Preview what agent would do without executing | | `/agent-stop` | Stop a running agent | | `/undo` | Undo the last agent action | | `/undo-all` | Undo all actions from current session | | `/history` | Show recent agent sessions | | `/changes` | Show all file changes from current session | | `/settings` | Configure confirmation mode and which tools require approval | **Confirmation mode** (set via `/settings → Agent Confirmation`): | Mode | Behavior | |------|----------| | `dangerous` (default) | Ask before configurable dangerous tools | | `always` | Ask before every action | | `never` | Execute without asking | In `dangerous` mode, configure which tools require confirmation via `/settings`: - **Confirm: delete_file** — ON by default - **Confirm: execute_command** — ON by default - **Confirm: write_file / edit_file** — OFF by default ### Git Integration | Command | Description | |---------|-------------| | `/diff` | Review unstaged git changes | | `/diff --staged` | Review staged git changes | | `/commit` | Generate commit message for staged changes | | `/git-commit [msg]` | Commit current changes with message | | `/push` | Push to remote repository | | `/pull` | Pull from remote repository | ### Context Persistence | Command | Description | |---------|-------------| | `/context-save` | Save current conversation for later | | `/context-load` | Load previously saved conversation | | `/context-clear` | Clear saved context for this project | ### Code Review & Learning | Command | Description | |---------|-------------| | `/review` | AI code review of unstaged git diff | | `/review --staged` | AI code review of staged changes | | `/review --static` | Static regex analysis with score (0-100) | | `/learn` | Learn preferences from project files | | `/learn status` | Show learned preferences | | `/learn rule ` | Add a custom coding rule | ### Project Intelligence | Command | Description | |---------|-------------| | `/init` | Initialize project (creates `.codeep/` folder) | | `/scan` | Scan project and cache intelligence for AI | | `/scan status` | Show last scan info | | `/scan clear` | Clear cached intelligence | | `/memory ` | Add a custom note to project intelligence | | `/memory list` | Show all notes with indices | | `/memory remove ` | Remove note by index | | `/memory clear` | Clear all notes | | `/model pull ` | Pull an Ollama model (local Ollama only) | | `/model browse` | Browse a curated catalog of local coding models and pull one (Ollama) | | `/model rm ` | Remove a locally-installed Ollama model (local only) | ### Skills | Command | Description | |---------|-------------| | `/skills` | List all available skills | | `/skills ` | Search skills by keyword | | `/skills stats` | Show skill usage statistics | | `/skill ` | Execute a skill (e.g., `/skill commit`) | | `/skill ` | Execute skill with parameters | | `/skill help ` | Show skill details and steps | | `/skill create ` | Create a new custom skill | | `/skill delete ` | Delete a custom skill | | `/c`, `/t`, `/d`, etc. | Skill shortcuts | | `/commit+push` | Skill chaining (run multiple skills) | ### Cloud Dashboard | Command | Description | |---------|-------------| | `/tasks` | List pending tasks for current project (numbered) | | `/tasks add ` | Create a new task on the dashboard | | `/tasks done <n>` | Mark task #n as done | | `/tasks delete <n>` | Delete task #n permanently | **CLI commands (outside chat):** | Command | Description | |---------|-------------| | `codeep account` | Link CLI to codeep.dev (GitHub OAuth) | | `codeep account sync` | Pull API keys + personalities + commands from codeep.dev → local | | `codeep account push` | Push local API keys + personalities + commands → codeep.dev | | `codeep review [files…]` | Offline, deterministic code review for CI — markdown or `--json`, `--fail-on <error\|warning\|info\|none>` sets the exit code. No API key needed. | ### Authentication | Command | Description | |---------|-------------| | `/login` | Login with API key | | `/logout` | Logout (choose which provider) | ## Keyboard Shortcuts | Key | Action | |-----|--------| | `Enter` | Submit message | | `↑` / `↓` | Navigate input history (or scroll chat when input is empty) | | `Ctrl+L` | Clear chat (same as `/clear`) | | `Ctrl+V` | Paste from clipboard with preview | | `Ctrl+A` | Move cursor to beginning of line | | `Ctrl+E` | Move cursor to end of line | | `Ctrl+U` | Clear input line | | `Ctrl+W` | Delete word backward | | `Ctrl+K` | Delete to end of line | | `Alt+F` / `Opt+F` | Move cursor forward one word | | `Alt+B` / `Opt+B` | Move cursor backward one word | | `Alt+D` / `Opt+D` | Delete word forward | | `PageUp` / `PageDown` | Scroll chat history (10 lines) | | `Mouse Scroll` | Scroll chat history | | `Escape` | Cancel current request / Stop agent | ## Supported Languages Codeep can respond in 12 languages: | Code | Language | |------|----------| | `auto` | Auto-detect (matches user's language) | | `en` | English | | `zh` | Chinese (中文) | | `es` | Spanish (Español) | | `hi` | Hindi (हिन्दी) | | `ar` | Arabic (العربية) | | `pt` | Portuguese (Português) | | `fr` | French (Français) | | `de` | German (Deutsch) | | `ja` | Japanese (日本語) | | `ru` | Russian (Русский) | | `hr` | Croatian (Hrvatski) | ## Syntax Highlighting Code blocks are automatically highlighted for: - Python - JavaScript / TypeScript - Java - Go - Rust - Bash / Shell - PHP - HTML / CSS - SQL ## Project Permissions When you run Codeep in a project directory for the first time: 1. Codeep asks for permission to access the project 2. You can grant: - **Read-only** - AI can see and analyze your code - **Read + Write** - AI can also suggest file modifications 3. Permissions are saved in `.codeep/config.json` With write access enabled: - AI can suggest file changes using special code blocks - You'll be prompted to approve changes with `Y/n` - Use `/apply` to manually apply changes from the last response ## Configuration ### Config Locations | Type | Location | |------|----------| | Global config | `~/.config/codeep/config.json` | | Project config | `.codeep/config.json` | | Global sessions | `~/.codeep/sessions/` | | Project sessions | `.codeep/sessions/` | | Global logs | `~/.codeep/logs/` | | Project logs | `.codeep/logs/` | ### Environment Variables | Variable | Description | |----------|-------------| | `ZAI_API_KEY` | Z.AI (international) API key | | `ZAI_CN_API_KEY` | Z.AI China API key | | `OPENAI_API_KEY` | OpenAI API key | | `ANTHROPIC_API_KEY` | Anthropic Claude API key | | `DEEPSEEK_API_KEY` | DeepSeek API key | | `GOOGLE_API_KEY` | Google AI (Gemini) API key | | `MINIMAX_API_KEY` | MiniMax (international) API key | | `MINIMAX_CN_API_KEY` | MiniMax China API key | | `KIMI_CODE_API_KEY` | Kimi Code subscription key | | `MOONSHOT_API_KEY` | Kimi international pay-per-use key | | `MOONSHOT_CN_API_KEY` | Kimi China pay-per-use key | | `XAI_API_KEY` | Grok (xAI) API key | | `BAILIAN_CODING_PLAN_API_KEY` | Qwen international Coding Plan key | | `BAILIAN_TOKEN_PLAN_API_KEY` | Qwen international Token Plan key | | `DASHSCOPE_API_KEY` | Qwen international pay-per-use key | | `BAILIAN_CODING_PLAN_CN_API_KEY` | Qwen China Coding Plan key | | `DASHSCOPE_CN_API_KEY` | Qwen China pay-per-use key | | `MODELSCOPE_API_KEY` | ModelScope token for its live model catalog | | `OPENROUTER_API_KEY` | OpenRouter API key | ### Settings (`/settings`) | Setting | Default | Description | |---------|---------|-------------| | Temperature | 0.7 | Response creativity (0.0 - 2.0) | | Max Tokens | 8192 | Maximum response length | | API Timeout | 60000ms | Request timeout | | API Rate Limit | 30/min | Max API calls per minute | | Command Rate Limit | 100/min | Max commands per minute | | Agent Mode | ON | `ON` = agent runs automatically (requires write permission via `/grant`), `Manual` = use /agent | | Agent API Timeout | 180000ms | Timeout per agent API call (auto-adjusted for complexity) | | Agent Max Duration | 20 min | Maximum time for agent to run (5-60 min) | | Agent Max Iterations | 50 | Maximum agent iterations (10-500). Modern models finish typical tasks in 3–8 iterations — raise for large autonomous refactors. | | Agent Confirmation | Dangerous | `Never`, `Dangerous` (default), or `Always` | | Agent Auto-Commit | Off | Automatically commit after agent completes | | Agent Branch | Off | Create new branch for agent commits | | Agent Auto-Verify | Off | `Off`, `Build only`, `Typecheck only`, `Test only`, or `Build + Typecheck + Test` | | Agent Max Fix Attempts | 1 | Max attempts to auto-fix errors when Auto-Verify is enabled. More than 1 usually means the agent is stuck — bail and let the user decide. | ## Usage Examples ### Autonomous Coding (Agent Mode ON) First, grant write permission (required for Agent Mode ON to work): ``` > /grant # Opens permission dialog - select "Read + Write" for full agent access ``` With write access enabled, just describe what you want: ``` > add input validation to the login form # Agent reads the file, adds validation, writes changes > the tests are failing, fix them # Agent runs tests, analyzes errors, fixes code, re-runs tests > refactor src/utils to use async/await instead of callbacks # Agent reads files, refactors each one, verifies changes > create a new API endpoint for user preferences # Agent creates route file, adds types, updates index ``` ### Code Review ``` > /diff --staged # AI reviews your staged changes and provides feedback ``` ### Manual Agent Mode ``` > /agent add a dark mode toggle to settings # Explicitly runs agent for this task > /agent-dry reorganize the folder structure # Shows what agent would do without making changes ``` ### Basic Chat (when agent mode is manual or read-only) ``` > Explain what a closure is in JavaScript > Look at src/utils/api.ts and explain what it does ``` ### Session Management ``` > /rename feature-auth-implementation Session renamed to: feature-auth-implementation > /search authentication # Find all messages mentioning "authentication" > /export # Export chat to markdown file ``` ## Architecture Codeep is built with: - **Custom ANSI Renderer** - Hand-built terminal UI with virtual screen buffer, diff-based rendering, and syntax highlighting (no React/Ink dependency) - **TypeScript** - Type-safe codebase - **Conf** - Configuration management - **Node.js Keychain** - Secure credential storage ## License Apache 2.0 ## Contributing Contributions are welcome! Before opening a PR, please read the [**Contributing guide**](./CONTRIBUTING.md) — it covers the development setup (npm is the canonical package manager), the test/build loop, code style, and how to propose a change. For provider integrations specifically, the guide walks through the files you need to touch. The active-product scope, model source index, replacement rules, telemetry contract, and recurring review checklist live in the [**model maintenance policy**](./docs/MODEL_MAINTENANCE.md). Quick version: `npm install` → `npm test` → `npx tsc --noEmit` clean → open a PR against `main`. To report a security issue, see [**Security policy**](./SECURITY.md). ## Support - **Issues**: [GitHub Issues](https://github.com/VladoIvankovic/Codeep/issues) ## Zed Editor Integration (ACP) Codeep supports the [Agent Client Protocol (ACP)](https://agentclientprotocol.com), letting you use it as an AI coding agent directly inside [Zed](https://zed.dev). ### Setup 1. Install Codeep globally: ```bash npm install -g codeep ``` 2. Add to your Zed `settings.json`: ```json "agent_servers": { "Codeep": { "type": "custom", "command": "codeep", "args": ["acp"] } } ``` 3. Make sure your API key is set in the environment Zed uses: ```bash export DEEPSEEK_API_KEY=your_key # or whichever provider ``` 4. Open Zed's AI panel and select **Codeep** as the agent. ### Configurable permissions (Zed & VS Code extension) Via the agent settings panel you can toggle which tools ask for approval before running — same controls available in the TUI via `/settings`: - **Confirm: delete_file** — ON by default - **Confirm: execute_command** — ON by default - **Confirm: write_file / edit_file** — OFF by default These apply in `Dangerous` confirmation mode (the default). Choose `Always` to confirm every action, or `Never` to skip all prompts. ### ACP capabilities Codeep advertises the following [ACP](https://agentclientprotocol.com) capabilities so Zed (and other ACP clients) can use them: - **`promptCapabilities.image`** — paste/drag images into chat for vision analysis. - **`promptCapabilities.embeddedContext`** — drag a file or pin a code selection into the chat and the actual file content is injected into the prompt (resource & resource_link blocks, 200 KB cap per file). - **`sessionCapabilities.list`** — exposes saved CLI sessions to ACP clients. - **`sessionCapabilities.resume`** — instant reconnect on panel reload without replaying history. - **`loadSession`** — restore a previous session by id. Codeep also reads `clientCapabilities.terminal` from the client and routes shell commands through the editor's terminal when supported (so you see them in Zed's terminal panel), falling back to local execution otherwise. ### Loading CLI sessions in Zed Zed's left sidebar shows only sessions Zed itself created (one per "New Thread") — it does **not** auto-list sessions you saved from the CLI or from a previous Zed window. Two ways to access those: **Inside the chat (recommended):** ``` /sessions # show all saved sessions for this workspace /session load <name> # restore one ``` When you open a fresh chat in Zed, Codeep also shows you the most recent CLI sessions for that project right in the welcome message, so you can switch with one command. **Via Zed's import modal:** Open Zed's command palette (`Cmd+Shift+P`) and search for **"Import Threads"**. Codeep's saved sessions appear there as an importable list — once imported they show up in Zed's regular sidebar. ## VS Code Extension Install **Codeep** from the VS Code marketplace. The extension is a thin UI around the CLI — all credentials and sessions live in the CLI's config (`~/.config/codeep/config.json`), so keys set anywhere are visible everywhere. ### Set API keys without leaving VS Code Open the Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`) and run: - **`Codeep: Set API Key`** — pick a provider, paste the key, done. Writes into the CLI config, so running `codeep` in a terminal immediately sees the new key. - **`Codeep: Open Chat`** — open the Codeep sidebar. - **`Codeep: Review Current File`** — run `/review <file>` on the active editor. - **`Codeep: New Session`** — start a fresh session in the chat. If you already set up keys in the CLI (or via the [codeep.dev](https://codeep.dev/dashboard) dashboard + `codeep account sync`), the extension picks them up automatically on first launch — no welcome prompt. ### Live plan & reasoning stream The chat sidebar now surfaces two extra ACP signals that previously only the TUI saw: - **Live plan** — for multi-step tasks the agent's plan appears as a small green card with status icons (`○` pending, `◐` in progress, `●` done) that update in place as work progresses. - **Reasoning stream** — when the model exposes a thinking trace (e.g. Claude extended thinking, GPT-5 reasoning), it shows up in a collapsible "Thinking" card above the answer. Closed by default; click to expand. - **Diff preview on permission prompts** — manual-mode permission cards now show a `-` / `+` diff for `edit_file`, a content preview for `write_file`, and the full `$ command` + `cwd` for `execute_command`, so users can verify before clicking *Allow*. Payload is truncated (~4 KB per field, 200 lines per file) with a visible marker. Other ACP clients (Zed, etc.) ignore the extra fields silently. - **`@file` mentions** — type `@` in the chat input to open a workspace-wide file picker. Pick with arrow keys + Enter; the file's content is inlined into the prompt as an `[Attached files]` preamble. Files over 200 KB are skipped with a marker. Multiple mentions in one message are deduplicated. - **Auto-reconnect** — if the CLI process exits unexpectedly (crash, OOM kill, parent restart), the extension reconnects on its own with exponential backoff (1s → 2s → 4s → 8s → 16s → 30s, capped at 6 attempts). The status bar shows the countdown. Configurable idle-watchdog timeout (`codeep.requestTimeoutMinutes`, default 5 min) replaces the old fixed cap so slow reasoning models don't get killed mid-thought. ### Editor-native actions (new in 2.2) - **Code Actions (lightbulb)** — select code and press `Ctrl+.` for **Explain**, **Improve / refactor**, **Add tests**, and **Add doc comment**. On a line with an error/warning, a **Fix this problem** quick-fix sends the diagnostic plus the code to Codeep. Everything routes through the chat, so the full agent (file edits via the diff preview, MCP tools) is available. - **Model picker in the status bar** — click `Codeep · <model>` (or run **Codeep: Select Provider & Model**) to switch provider + model from a quick-pick. Providers with open-ended catalogs (OpenRouter, ModelScope, Ollama, custom endpoints) let you type a model id. - **Self-hosted endpoints from settings** — point the extension at vLLM / LiteLLM / LM Studio / text-generation-webui with `codeep.baseUrl` (e.g. `http://localhost:8000/v1`), plus `codeep.provider` (`custom` or `openai`) and `codeep.model`. The `codeep.provider` / `codeep.model` settings are applied on every connect, so they stay authoritative. - **Get Started walkthrough** — a native VS Code walkthrough (Help → Get Started) covering CLI install, opening the chat, editor actions, and choosing a model. > The 2.2 model picker and `custom`-provider settings need CLI **2.1.2+**; they degrade gracefully on older CLIs (free-text model input, and `codeep.baseUrl` still works for the `openai` provider via `OPENAI_BASE_URL`). ### Native chat & agent integration (new in 2.3) - **`@codeep` chat participant** — invoke Codeep from VS Code's built-in Chat view: type `@codeep` and ask, or `@codeep /explain` / `@codeep /review` with a selection. Answers come from your configured Codeep provider/model via the CLI (not VS Code's model picker), on an independent session. - **`#codeepSkills` language-model tool** — exposes your workspace's Codeep skill bundles (`.codeep/skills/*/SKILL.md`) to VS Code agent mode and `#`-references, so the native agent can follow your project's own workflows. - Requires VS Code **1.95+** (for the stable Chat Participant + Language Model Tools APIs). ### Source control & sidebar (new in 2.3) - **Generate Commit Message** — a sparkle button in the Source Control panel (and `Codeep: Generate Commit Message` in the palette) reads your staged diff and writes a Conventional Commits message into the commit box. Falls back to the working-tree diff if nothing is staged; asks before replacing a message you've already typed. - **Sessions tree view** — a native **Sessions** view in the Codeep sidebar lists saved conversations (title + age). Click to load into the chat, inline-delete, or start a New Session from the title bar. - **MCP config validation** — `.codeep/mcp_servers.json` (project and global) gets JSON schema validation + autocomplete, so a mistyped `command` / `args` / `env` is caught before a session starts. - **Workspace Trust** — declares limited support for untrusted workspaces, with a reminder to review permission prompts carefully (Codeep runs a local agent that can edit files and run commands).