Architecture

Design principles

RaptorCode is built as a systems tool, not a wrapper. Three principles drive the architecture:

• Autonomy with a human gate. Agents work end to end, but nothing is committed or merged without you.
• Isolation by default. Every agent is sandboxed to its own git worktree, so parallel work never collides.
• Depth over speed. Sessions run at full reasoning depth ("ultrathink") unless you choose otherwise.

The swarm model

You hand RaptorCode a mission in one line. It then dispatches four specialists — frontend, backend, test, and security — each running as a live agent on its own thread, inside its own git worktree.

raptor swarm run "add stripe checkout"

  mission
     │
     ├─▶ frontend  ─▶ worktree/frontend   (tool loop)
     ├─▶ backend   ─▶ worktree/backend    (tool loop)
     ├─▶ test      ─▶ worktree/test       (tool loop)
     └─▶ security  ─▶ worktree/security   (tool loop)
                          │
                          ▼
                  reviewable diffs  ──▶  you review · test · merge

Each specialist runs a headless, tool-executing loop: it reads files, writes files, runs commands, and repeats toward the mission. You can watch all four at once in a 2×2 terminal dashboard that shows each agent's current phase, the file it is touching, a live activity feed, elapsed time, and token usage.

The agent loop

At the core of both interactive and swarm modes is a tool-execution loop:

1. Your message (or the mission) is sent to the configured model.
2. The model responds with reasoning and tool calls.
3. RaptorCode executes the tools locally — read, write, list, create, change directory, run command.
4. Results are fed back, and the loop continues until the work is done or a step limit is reached.

Shell commands run with a timeout so a stuck process can never stall a session. Long-running sessions are protected by automatic context-budget compaction against the model's context window, keeping the system prompt and recent context without hitting context-length errors.

Isolation & worktrees

Git worktrees are the unit of isolation. Each swarm agent operates in a dedicated worktree, so concurrent edits never interfere. When a run finishes, all changes are left uncommitted in their worktrees — you review the diffs, run your tests, and merge only what you want.

Ultrathink defaults

Interactive sessions start in ultrathink mode: thinking enabled and reasoning effort at maximum, in both chat and agentic modes. You can dial this down per session when you want speed over depth.

Distribution

RaptorCode is written in Rust and ships as a single, self-contained binary for Linux, macOS, and Windows. It brings its own toolchain — no runtime to install, no daemon to manage. You bring a model API key, which is stored locally and reused across sessions.