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

Agent modes

Mode	Description
`on (default)`	Agent runs automatically for every prompt
`manual`	Agent only runs when you explicitly use /agent <task>

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.

$ /plan refactor src/auth.ts to use OAuth instead of basic auth
 
## Plan: switch src/auth.ts from basic auth to OAuth
 
1. Read src/auth.ts — understand current handlers and callers.
2. Add src/auth/oauth.ts — verifyToken() + getAuthUrl().
3. Replace handlers in src/auth.ts.
4. Update 4 callers (api/login.ts, middleware/protect.ts, …).
5. Add tests src/auth.test.ts covering verifyToken.
 
Risk: medium · Files: src/auth.ts, src/auth/oauth.ts (new), api/login.ts, …
Commands run: npm install oauth-2-0, npm test
 
$ /go
Executing approved plan…

★

Plan mode reuses your existing MCP tools, lifecycle hooks, permission settings, and skill bundles during execution — the planner just gives you a chance to spot something wrong before any code runs. Works in the TUI, Zed, and the VS Code extension.

Personalities (`/personality`)

Personalities swap how the agent talks and what it prioritises — without switching models or rewriting prompts. Internally they're an addendum appended to the agent's system prompt for every run until you change or clear them. The same model, the same tools, a different lens.

Six built-in presets

Preset	When to use	What it changes
`concise`	Quick fixes; pair with ship-it for max velocity	Short answers, no preamble, bullet-heavy output, no emojis
`verbose`	Learning a new framework, post-mortems, documentation	What / why / alternatives considered / caveats on every change; line-number citations; explicit verification checklists
`security`	Auth flows, payments, file uploads, public APIs	Treats every input as hostile, enumerates attack surface in comments, prefers allowlists, lists 2-3 attack scenarios after implementing
`senior-reviewer`	Refactoring legacy, architectural decisions, PR self-review	Strong opinions on naming + abstraction, push-back on shortcuts, flags missing tests, suggests alternatives even if user pushed the messier one
`junior-mentor`	You're learning, teaching colleagues, writing tutorials	Adds 'why this exists' context, uses grounded analogies, links to canonical docs (MDN / language ref), suggests one follow-up exercise
`ship-it`	Hot fixes, demo prep, prototype for tomorrow's meeting	Picks first reasonable approach, inline TODO comments fine, tests happy path only, suggests minimum-viable not robust-for-all-cases

Basic flow

$ /personality
Active: (none — agent uses default tone)
Available: concise, junior-mentor, security, senior-reviewer, ship-it, verbose
 
$ /personality security
Active personality: Security-paranoid (security, builtin)
 
$ /agent add a login endpoint that accepts email + password
[agent thinks through SQLi, timing attacks, password hashing, rate-limiting]
[adds parameterized queries, bcrypt with per-user salt, returns generic error]
[ends with: 'Considered scenarios: timing oracle (mitigated), credential stuffing (rate-limit added), …']
 
$ /personality off
Personality cleared — agent uses default tone.

★

The active personality lives in ~/.codeep/config.json as activePersonality. It survives terminal restarts and is shared across every project on this machine. Aliases for clearing: /personality off, /personality none, /personality clear.

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.

$ /personality security
$ /plan add OAuth2 callback for Google login
 
## Plan: add OAuth2 callback for Google login
**Assumes:** state parameter verified server-side; PKCE flow.
1. Validate redirect URI allowlist — reject anything not in OAUTH_ALLOWED_REDIRECTS.
   _Why:_ open redirect → phishing vector.
2. Verify state parameter — must match /authorize, single-use.
   _Why:_ CSRF protection on the OAuth flow.
3. Exchange code → token via POST with PKCE verifier.
4. Validate id_token JWT (sig, aud, iss, exp) against Google JWKS.
...
**Risk:** high — auth boundary. Recommend manual security review before merge.
 
$ /go
Executing approved plan…

Custom personalities

Drop a Markdown file in one of two locations to add your own:

Location	Scope	Use case
`.codeep/personalities/<name>.md`	project	Team conventions — commit to repo so collaborators get the same tone
`~/.codeep/personalities/<name>.md`	global	Personal preferences across every project on this machine

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 verbatim when the personality is active. Capped at 64 KB per file.

# Personality: Acme Corp PR Reviewer

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

Where it works

Client	How
`CLI TUI`	/personality typed directly in the prompt
`Zed (ACP)`	Same /personality command in chat — Zed sees the same `availableCommands`
`VS Code extension`	Chip in Settings → Commands, or type /personality directly in the chat input

⚠

Personalities only affect agent runs. Plain chat (chat() path used by /agent with agentMode: off, and inline completions) doesn't inject the personality — that's by design since chat replies don't go through the system prompt the same way.

User profile (`/me`)

A durable, human-readable description of youthat 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

File	Scope	What goes here
`~/.codeep/profile.md`	global	Who you are across all projects: reply language, style, stack, universal preferences
`.codeep/profile.md`	project	What this repo is to you: your role, goals, constraints, 'don't touch' areas

Run /me to view everything, /me init (or /me init project) to scaffold a template, and /me off / /me onto 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.

$ /me init
Created global profile: ~/.codeep/profile.md
edit it: 'Reply language: Croatian', 'Response style: concise', stack…
 
$ /me
Injection: on  ·  Auto-learn: off
Global   ~/.codeep/profile.md            present
Project  .codeep/profile.md               not created

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.

Command	What it does
`/me learn on`	Enable automatic learning (global + project)
`/me learn`	Learn from the current session right now (one-off)
`/me learn project`	One-off, scoped to this repo
`/me forget`	Clear the auto-learned profile(s)

★

Everything is local-first and opt-in. Sync your global profile across machines (and edit it on the web) from the dashboard with /me sync (or codeep account sync) — pull is additive, so a web edit never overwrites a local profile. In VS Code, use Codeep: Edit Profile, Codeep: Toggle Profile Auto-Learn, and Codeep: Sync Profile to Dashboard.

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

Agent	Tools	What it's for
`planner`	read-only	Investigates, then returns a concrete step-by-step implementation plan — no code
`researcher`	read-only	Explores the codebase / web and returns a tight, cited summary — great for 'how does X work?' without flooding your context
`reviewer`	read-only	Senior review of a change: correctness, security, design — cites file:line, suggests fixes
`tester`	read + write + run	Writes focused tests for a target, runs them, iterates to green

Run /agentsto list what's available. The agent calls them itself via the delegatetool — you don't invoke them directly:

$ /agent add rate-limiting to the login endpoint
⤷ delegating to researcher…
⤷ researcher: login is in src/auth/login.ts; no limiter; redis client already in src/lib/redis.ts
[implements the limiter using the existing redis client]
⤷ delegating to reviewer…
⤷ reviewer: looks correct; one edge case — fail-open if redis is down. Suggest fail-closed.
[adjusts to fail-closed, done]

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…

★

tools is an allowlist — omit it and the sub-agent inherits all tools; include it and anything outside the list is rejected at dispatch (so a researcher literally cannot write files). Sub-agents inherit your profile and project rules, and their file changes are covered by /undojust like the main agent's.

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 reviewerand 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

Section	What it shows
`Headline tally`	Total runs · total tool actions · total active time · how many days had any activity (out of N) · avg actions per run
`By project`	Each repo (basename of projectRoot) with runs / actions / active time, sorted by time. Top 8.
`Top tools`	Action types ranked by count (write × 78, read × 64, execute × 32, …). Top 8.
`Most-touched files`	Absolute file paths with edit count, ~ prefix for readability. Top 8.
`Recent runs`	10 most recent: relative date (today / 2d ago / 2026-04-29), project, duration, prompt

Flags

Flag	Effect
`(no flag)`	Last 7 days
`--days N`	Last N days (clamped to 1–365)
`--days=N`	Same, equals-form

$ /insights
 
## Activity — last 7 days
**18** runs · **94** tool actions · **4h 12m** active · **5**/7 active days · avg **5.2** actions/run
### By project
| codeep-web   | 12 | 67 | 2h 51m |
| codeep       |  4 | 22 |   58m  |
| sharepoint-spfx | 2 | 5 |   23m  |
### Top tools
- write × 42 · read × 28 · execute × 14 · edit × 10
### Most-touched files
- ~/dev/codeep-web/src/app/docs/agent/page.tsx × 8
- ~/dev/codeep-web/src/components/Navbar.tsx     × 5
 
Per-session cost lives in /cost — insights is history-only.

★

Cost / token usage aren't in /insights because the token tracker is in-memory and would lose data across restarts. The current session's cost (including prompt-caching savings) is in /cost. For historical cost, use the codeep.dev dashboardif you're logged in.

Confirmation settings

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

Setting	Behavior
`always`	Ask before every file write and command
`dangerous (default)`	Ask before tools marked as dangerous
`never`	Execute everything without asking

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

Setting	Default	Description
`Confirm: delete_file`	ON	Ask before deleting files
`Confirm: execute_command`	ON	Ask before running shell commands
`Confirm: write_file / edit_file`	OFF	Ask before writing or editing files

Auto-verification

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

Value	What it runs
`off`	No automatic verification
`build`	npm run build (or equivalent for your stack)
`typecheck`	tsc --noEmit
`test`	npm test
`all`	build + typecheck + test

Example session

> Refactor the auth module to use JWT tokens instead of sessions
 
  Analyzing project... found src/auth/
  Planning: 4 steps
 
  [1/4] Reading src/auth/session.ts...
  [2/4] Creating src/auth/jwt.ts
  [3/4] Updating src/middleware/auth.ts
  [4/4] Running: npm run typecheck
  ✓ No type errors found
 
  Done. 2 files created, 1 file modified.

ℹ

Use /undo to reverse the last agent action, or /undo all to revert the entire session.

Commands Skills