Modes and Tools

Operaide Code runs in one of three modes. The mode controls which tools the agent can call without asking. Underneath, every tool is sandboxed to the working directory and the agent must search the handbook before touching framework code.

Three modes

The mode is shown in the status line, in colour. You switch with /plan, /normal, /auto, or by pressing Shift+Tab to cycle Plan -> Auto -> Normal -> Plan.

Plan mode

Plan mode is read-only investigation. The policy:

• Hard-denies write_file and edit_file. They are also hidden from the model's tool list, so the model does not even consider them.
• Asks for approval before every bash call.
• Allows reads (read_file, ls, glob, grep, search_handbook) freely.
• Requires every change-requesting turn to end with a present_plan call. The plan opens a modal with three options: Apply Auto, Apply Normal, Reject.

Use plan mode when you want to scope a change before letting the agent run. The model is told explicitly that approval history does not carry across mode switches: a plan approved in a previous turn does not authorise writes in the current turn.

Normal mode

Normal mode prompts before every modifying call (write_file, edit_file, bash). The approval modal shows a unified diff for file edits before you decide.

You can pick "Allow always" for a tool inside one session. The verdict resets when you /clear or quit.

Auto mode

Auto mode runs every tool silently. There are no approval prompts. The sandbox and tool allowlists still apply; you trade interactivity, not safety.

Use auto mode for short, well-scoped tasks where you trust the plan and want to watch the agent work uninterrupted. Switch back to normal or plan when the scope grows.

Tools the agent has

Tool	What it does	Approval (Plan / Normal / Auto)
read_file	Reads a file under the working directory or the embedded handbook. 256 KB cap.	Allow / Allow / Allow
ls	Lists a directory's contents.	Allow / Allow / Allow
glob	Doublestar match (e.g. **/*.ts). Returns up to 200 paths.	Allow / Allow / Allow
grep	Regex search over a path. Skips binaries, .git, node_modules, dist, build, .next. Returns up to 200 hits.	Allow / Allow / Allow
write_file	Creates or overwrites a file. Shows a unified diff in the approval modal.	Deny / Ask / Allow
edit_file	Replaces a single occurrence of a string. Fails if the old text appears zero or many times.	Deny / Ask / Allow
bash	Runs an allowlisted command (npm, node, npx, tsc, eslint, prettier, plus read-only git status/diff/log/show). Refuses shell metacharacters.	Ask / Ask / Allow
run_check	Runs the project's package.json#check script and parses eslint, prettier, and tsc output into structured diagnostics.	Allow / Allow / Allow
search_handbook	Regex search over the embedded handbook. Returns up to 20 hits.	Allow / Allow / Allow
present_plan	Hands a markdown plan back to you for approval. Required final tool in plan mode.	Allow / Allow / Allow

Bash details

bash is deliberately narrow:

• Allowlist: npm, node, npx, tsc, eslint, prettier, git. For git, only status, diff, log, show.
• Refuses shell metacharacters (;, &, |, >, <, $, `). No piping, redirection, or chaining.
• Scrubbed environment: only PATH and HOME are forwarded. Provider keys cannot leak through subprocess env.
• Default timeout 120 seconds. Output capped at 256 KB on each of stdout and stderr.

File reads

Everywhere a tool takes a path, the path is resolved against the working directory and rejected if the result is outside that directory after symlink resolution. Paths under /handbook/ are a virtual filesystem rooted in the embedded handbook; read_file and ls can read them, writes always fail.

How it stays Operaide-aware

The system prompt opens with this rule:

You have NO built-in knowledge of Aktor APIs. Whenever a turn touches a framework concept (any aktorXxx call, any registerXxxReaktorDefinition, aktorSetting, AI/database/mail integration, deploy semantics, error handling), your first action MUST be one of: the skill tool (if a listed skill matches the task; the skill body says what to do next), or search_handbook (if no listed skill matches). Never write framework code from memory. The framework changes; your training data is stale.

The handbook content is mirrored from the published handbook into the binary at build time. The version of the handbook the agent searches matches the version of operaide-code you are running. When the framework changes, you upgrade the binary; the handbook follows.

The prompt also describes the layout of an Operaide app (backend Reaktors under src/, App UI under public/) and lists working rules: run run_check after any code change, prefer edit_file over creating new files, every .reaktor.ts must be reachable from package.json#main.

On startup, the agent reads package.json, detects @operaide/* dependencies, scans up to 50 .reaktor.ts files, and probes for a public/ directory. The result becomes a "Current app context" block in the system prompt, so the first turn already knows what kind of app it is in.

Sessions

Every turn is appended to ~/.operaide-code/sessions/<id>/transcript.json. The session also remembers the provider, model, working directory, and token usage.

You manage sessions with these commands:

• --resume [id] on the command line. Without an id, it reopens the most recent session.
• /resume from inside a session. Opens a picker showing recent sessions with their first message and turn count.
• /clear rotates to a new session. The current one is closed, a fresh id is minted.
• /compact rewrites the full conversation into a single memory summary using the active provider/model. Use it when you want to continue the same task with a much smaller context window while preserving goals, changes, and pending work.
• /truncate [keep] drops old turns and keeps the last keep user turns. Default is 4. A memory summary written by /compact is always kept, so the two commands combine: compact once, then truncate freely.

Sessions are full snapshots, written atomically every turn. If you kill the agent mid-tool-call, the next --resume repairs the trailing assistant turn so the conversation continues cleanly.

Common mistakes

• Trying to write files in plan mode. The policy denies write_file and edit_file outright; the model also does not see them in its tool list. The fix is /normal or /auto, or call present_plan and approve.
• Expecting bash to do shell things. No pipes, no redirection, no cd. Use run_check for the standard quality gate, or specific commands like npm run deploy.
• Skipping search_handbook for "obvious" code. The system prompt is firm because models pattern-match against stale training data. If the agent suggests a deprecated API, it usually skipped the handbook search; ask it to retry with one.
• Letting a session grow without /compact or /truncate. Past about 30-40 turns the model slows down and starts confusing earlier and later context. /compact preserves the whole task as a summary; /truncate 4 keeps only the last four user turns.
• Editing .operaide-code/config.toml mid-session. The agent reads it on startup. Restart operaide-code after config changes.