Code.ae docs

Install#

Two surfaces, one agent. Pick whichever fits where you work.

• Extension for Cursor / VSCodium / VS Code / Windsurf — download code-ae-agent.vsix from /desktop/download and install via the editor's Extensions → ⋯ → Install from VSIX… menu. Sign in via the command palette → code.ae: Sign In.
• CLI — install once via code.ae: Install CLI to PATH (command palette), then run code-ae from any terminal in any workspace. The CLI uses the same auth, the same agent core.

Slash commands#

Type / at the start of the chat input (or REPL line) to open the slash menu. Built-ins ship with every install; user-defined commands let your team script their own.

Built-ins

User-defined commands

Drop a markdown file in ~/.code-ae/commands/ (user-global) or <workspace>/.code-ae/commands/ (project). The filename becomes the slash name; the body is the template.

# ~/.code-ae/commands/explain.md
Explain $ARGUMENTS in three sentences for a junior dev.

Then in chat: /explain this React component. The string after the command name substitutes into $ARGUMENTS; $ARG1…$ARG9 grab positional words. Workspace commands beat user-global commands on a name collision.

Cmd-K inline edit (extension)#

Select code in any editor and press ⌘K (macOS) or Ctrl-K (Win/Linux). An input box appears — describe the edit ("convert to async/await", "add JSDoc"), the agent streams a replacement, and the change applies in place. A toast offers Undo and Show diff in case you want to review.

Selection-as-context#

Highlight code in any editor and the chat composer shows a chip: 📄 src/auth.ts:42-58 (17 lines). The next message you send auto-prepends the selection as an <editor-selection> block so the model sees the file path, line range, and exact content. Click the × to opt out; otherwise the chip survives until you re-select.

Skills (conditional context)#

A skill is a markdown file with frontmatter declaring when it activates. When your prompt mentions any when: trigger (case-insensitive substring), the skill body auto-loads into the system prompt for that turn.

Drop files in ~/.code-ae/skills/ (user-global, every workspace) or <workspace>/.code-ae/skills/ (project-specific).

# .code-ae/skills/react.md
---
name: react-conventions
description: React component conventions for this project
when: ["component", "react", "jsx", "tsx"]
---

Use functional components with hooks. State lives in Zustand
stores under src/stores/. Tailwind classes only.

Workspace skills override user-global skills on slug collision. Skills with no when: trigger are always active (essentially small, focused CLAUDE.md replacements).

Persistent memory#

The agent has dedicated remember and forget tools to save durable facts across sessions. Saved memory auto-loads into the system prompt at the start of every future session.

Files live in ~/.code-ae/memory/<slug>.md (user-global, every workspace) or <workspace>/.code-ae/memory/<slug>.md (project-specific). You can hand-edit these files; the next session picks them up.

Lifecycle hooks#

User-defined shell commands fire on three agent events. Each hook receives the event payload as JSON on stdin and signals via exit code: non-zero aborts the operation that triggered it.

Configure in ~/.code-ae/settings.json:

{
  "hooks": {
    "PreToolUse": [
      { "command": "./scripts/audit-write.sh", "matchTool": "write_*" }
    ],
    "UserPromptSubmit": [
      { "command": "echo 'Reminder: run tests before committing.'" }
    ]
  }
}

matchTool supports the trailing-star glob: read_* matches every read tool, while * matches every tool (the default when omitted). Default per-hook timeout is 5s; hooks that exceed it are killed and the operation continues as if the hook returned non-zero.

MCP servers (extensibility)#

Configure Model Context Protocol servers in settings.json and the agent spawns them at session boot, lists their tools, and merges them into its own tool surface with names prefixed mcp__<server>__<tool>.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..." }
    },
    "fs": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-filesystem", "/tmp"]
    }
  }
}

Servers boot in parallel with a per-server 10s timeout, so one wedged server doesn't block the rest. A failed server logs a warning and the agent boots without its tools — your local toolset still works. Servers close cleanly on exit.

Subagents (the task tool)#

The agent has a task tool that delegates a focused subtask to a sub-agent. The sub-agent runs in a fresh context (no parent history), executes the task with the same tool surface, and returns its final text only. Use it when:

• The subtask is self-contained (audit a module, search across files)
• You want the parent context to stay clean
• You're running multiple independent analyses

task({
  prompt: "Audit src/auth/ for any unhandled async errors.
           Return a list of file:line refs with descriptions.",
  readOnly: true
})

readOnly: true filters the sub-agent's tools to the read-only subset. Sub-agents cannot nest — they can't spawn further sub-agents.

Live agent todo list#

The agent has an update_todos tool to surface its plan as a live checklist the user can watch. Status glyphs change in place as steps land — pending ○, in-progress ⚙, completed ✓. The agent decides when to use it; if you've asked for a multi-step change, you'll usually see the breakdown pop in early.

Web fetch#

The agent's web_fetch tool reads HTTP(S) URLs and returns the content as text. HTML is stripped to readable text (anchors preserved as text (url)); JSON / markdown / plain text pass through unchanged; binary content (images, PDFs, video) is rejected with a clear error.

Default 30s timeout (capped at 2 min), 2 MB body cap with a truncation marker. The fetch is unauthenticated — no private GitHub repos, no API behind a login wall. For those, paste the relevant text into chat.

Clickable file references#

Anywhere the agent writes a backticked path-with-line in its reply — src/foo.ts:42, packages/local-agent/src/run-loop.ts:146-160 — the chat panel renders it as clickable. Click → opens the file at the referenced line. The conservative regex requires an extension so prose like "1.5x faster" doesn't falsely match.

Tool reference#

Every code.ae agent — extension or CLI — has the same tool surface. Beyond these, any MCP server you configure adds tools prefixed mcp__<server>__<tool>.

• write_file— Create or overwrite a file. Workspace-relative paths only.
• read_file— Read a UTF-8 file.
• list_files— List a workspace directory (root if omitted).
• edit— Find-and-replace within an existing file. oldString must be unique unless replaceAll.
• delete_file— Remove a single file.
• move_file— Rename or move a file within the workspace.
• exec— Run a shell command. bash -lc on POSIX, cmd /c on Windows. 5min default timeout. Not sandboxed.
• web_fetch— HTTP(S) GET with HTML-to-text. 30s timeout, 2MB cap, unauthenticated.
• task— Spawn a focused sub-agent in a fresh context. readOnly filters to read-only tools.
• update_todos— Surface a live checklist of multi-step work the user can watch.
• remember— Save a durable fact to persistent memory. Auto-loads in future sessions.
• forget— Remove a memory entry that turned out wrong.

Settings file shape#

All non-prompt configuration lives in two optional JSON files, merged at session boot (workspace wins on conflict):

• ~/.code-ae/settings.json — applies everywhere
• <workspace>/.code-ae/settings.json — this project only

{
  "hooks": {
    "PreToolUse": [
      { "command": "./scripts/audit.sh", "matchTool": "write_*" }
    ],
    "UserPromptSubmit": [
      { "command": "echo 'Reminder: run tests.'" }
    ]
  },
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-github"],
      "env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_..." }
    }
  },
  "defaultModel": "claude-opus-4-7"
}

Parse / schema errors don't break the agent — they're logged as warnings, the bad file gets skipped, and the session continues with whatever loaded cleanly.