Agent Mode

Agent Mode is Codeep's autonomous execution engine. Instead of just answering questions, the agent plans a sequence of steps and executes them — writing files, running commands, checking output, and fixing errors automatically.

How it works

When you give Codeep a task in Agent Mode, it follows this loop:

1. 1
   Plan — Reads project context and breaks task into steps
2. 2
   Execute — Runs each step: edits files, executes commands, fetches URLs
3. 3
   Verify — Checks output — if a build fails or tests error, it attempts to fix them
4. 4
   Report — Shows a summary of what was done

Agent modes

Plan mode (/plan + /go)

Before letting the agent touch your files, preview the full plan it would execute. /plan <task> generates a numbered, reviewable plan — files it would touch, commands it would run, risk level it self-assesses — and surfaces it as a chat message. Run /go to execute as-is, or /plan <revised task> to refine before approval.

Personalities (/personality)

Built-in personalities swap how the agent talks and what it prioritises. Custom agents created in Agent Studio go further: the same portable Markdown file can pin an exact provider/model, restrict tool groups, limit project scope, and add tested behavior rules. Older prompt-only personality files remain fully compatible.

Six built-in presets

Basic flow

Combo with plan mode

The high-leverage pattern for sensitive work: set a personality, then run plan mode. The plan you review carries the personality's priorities, so you catch issues before any code touches disk.

Custom personalities

Create one visually in Dashboard → Agent Studio, or drop a Markdown file in one of two locations:

Name on disk becomes the slug (filename without .md, lowercased, dashes ok). First line is parsed as the display name; the rest is the prompt addendum the agent receives when active. A custom-bot/v1 frontmatter block turns model, tools, and scope into runtime controls. Prompt-only files without that block keep legacy behavior; the complete section layout written by the earlier Agent Studio is also recognized for compatibility. Files are capped at 64 KB each.

---
codeep: custom-bot/v1
description: Reviews a change against Acme engineering rules
model: openai/gpt-5.6-sol
tools: [files, tests, git, mcp]
scope: selected
projects: [acme-api, acme-web]
---
# Acme Corp PR Reviewer

> Reviews a change against Acme engineering rules.

You are reviewing a PR following Acme Corp engineering conventions:

## Naming
- All async functions end in "Async" (legacy convention)
- React components are PascalCase, hooks start with "use"
- Database tables are snake_case

## Tests
- Every public function needs a unit test
- Integration tests live in /test/integration/
- Avoid mocks for things we own — use real test fixtures

## Comments
- JSDoc on every exported function with @param + @returns
- No inline comments unless explaining "why" (never "what")
- TODO must include ticket: // TODO(ACME-1234): ...

## Anti-patterns to flag
- Throwing from constructors
- Magic numbers (everything except 0, 1, -1)

End every review with: "What I'd test that you didn't" — 2-3 specific cases.

Scope and override rules

When two personalities share the same name, the more specific scope wins. So a project file .codeep/personalities/concise.md overrides the built-in concise — but only inside that workspace.

Project  (.codeep/personalities/)   →  wins
Global   (~/.codeep/personalities/)  →  next
Built-in                              →  fallback

Runtime controls

What each capability grants

Unselected groups are removed from the runtime tool registry — the model is never offered them, so it cannot call one and be refused. What a selected group covers is wider than its name suggests in one case:

Where it works

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 without you repeating yourself. Reply language, response style, default stack, hard “always / never” rules. It flows to every surface (terminal, VS Code, Zed) because they all share the same files.

Two layers, two scopes

Run /me to view everything, /me init (or /me init project) to scaffold a template, and /me off / /me on to toggle injection. Edit the Markdown files in any editor — there's no schema, just write what matters. Project rules in .codeep/rules.md still take precedence on any conflict.

Let Codeep learn (opt-in)

Turn on auto-learn and Codeep quietly extracts your durable preferences from sessions and merges them into a separate profile.learned.md (global and project), kept apart from your hand-written file so it's never clobbered. One cheap LLM pass at session save, throttled, off by default.

Sub-agents (delegate · /agents)

The agent can hand a self-contained sub-task to a specialist sub-agent that runs in its own fresh context window and returns only a summary. The win is twofold: your main context stays small (the sub-agent burns tokens exploring; you get the gist), and each sub-task runs with a tuned persona and a scoped toolset.

Built-in agents

Run /agents to list what's available. The agent calls them itself via the delegate tool — you don't invoke them directly:

Your own agents

Drop a Markdown file with frontmatter in .codeep/agents/<name>.md (project) or ~/.codeep/agents/<name>.md (global):

---
name: migrator
description: Writes and runs database migrations
tools: [read_file, write_file, edit_file, execute_command]
model: glm-5.2            # optional model override
personality: senior-reviewer   # optional preset to layer on
maxIterations: 12        # optional budget
---
You write safe, reversible DB migrations. Always include a down migration…

Guaranteed review pass

Turn on Agent Auto-Review in /settings (or set agentAutoReview) and after any agent run that changed files, Codeep automatically delegates to the reviewer and appends its findings — so a review stage always happens, even if the model wouldn't have asked for one. Off by default; one extra read-only pass when on.

Activity insights (/insights)

A retrospective view of what the agent has done for you — runs, tool actions, projects touched, most-edited files — over a configurable window (default 7 days, max 365).

Where the data comes from

Every agent run writes a JSON record to ~/.codeep/history/<id>.json:

{
  "id": "1777454909089-19z7tln",
  "startTime": 1777454909089,
  "endTime":   1777455195496,
  "prompt": "Napravi mi listu glavnih stranica…",
  "projectRoot": "/Users/vladoivankovic/dev/BuboBall",
  "actions": [
    { "id": "…", "timestamp": …, "type": "write", "path": "/path/to/file" },
    { "id": "…", "timestamp": …, "type": "read",  "path": "/path/to/other" },
    { "id": "…", "timestamp": …, "type": "execute", "command": "npm test" }
  ]
}

/insights reads every file in that directory whose startTime falls inside the window. No SQL, no telemetry, no upload — pure local.

What you see

Flags

Confirmation settings

Set Agent Confirmation in /settings to control when the agent asks for approval:

When using dangerous mode, you can choose exactly which tools require confirmation via /settings:

Auto-verification

Set agentAutoVerify to automatically run checks after the agent makes changes:

Example session