Documentation
Documentation
44 pages covering the CLI, the runtime and the SDK. Start by installing it; the rest is reference.
Start hereGetting startedInstall Arcturn and run your first agent session.Model providersEvery model backend Arcturn can drive, and how to authenticate with each.ConfigurationEvery config key, default, and env var — file locations, scope, and precedence.PermissionsThe rule-based permission engine — modes, scopes, resolution order, and the rule cookbook.
Core concepts
26 pages
- ToolsThe built-in tool set — read, write, edit, bash, grep, glob, ls, fetch, websearch — parameters, output, and limits.
- Code searchsearch_code — an offline BM25 + structural index that returns file:line addresses instead of file bodies, with no embeddings and no network.
- @-mentions & imagesFuzzy file completion in the prompt editor, plus inline file content and image attachments.
- LSP diagnosticsLanguage-server diagnostics appended to write and edit results, for the languages you already have tooling for.
- Verify loopRun a build/test/lint command after every edit and feed a failure straight back to the model.
- PermissionsThe rule-based permission engine — modes, scopes, resolution order, and the rule cookbook.
- Dry run & sandboxThe --dry-run shadow-tree overlay, /diff /apply /discard, and the opt-in OS filesystem sandbox.
- Speculative approvalWhile a permission prompt sits in front of you, the agent keeps working in a shadow overlay instead of sitting idle.
- Injection defenseTaint tracking for prompt injection, and canary tokens for exfiltration detection.
- Lifecycle hooksRun shell commands at tool and session boundaries, with veto power over tool calls before they run.
- MCPConnect stdio and streamable-HTTP Model Context Protocol servers.
- Deferred toolsProgressive tool disclosure — withhold most tool schemas until the model asks for them via tool_search.
- Markdown skillsAdd a slash command by dropping a markdown file on disk — no code, no build step.
- Model-invoked skillsThe skill tool exposes the same skill library markdown skills use to the model itself, so it can reach for a skill mid-task without the user typing a slash command.
- Sub-agents, plan mode & todosDelegate scoped work to child agents, and the structured plan/todo state tools.
- Sessions, branching & compactionThe tree-structured session store, resuming, forking a branch, and token-aware compaction.
- Context managementTool-output offloading, tool-result context editing, and how both compose with compaction as a backstop.
- Checkpoints & /rewindAutomatic pre-edit file snapshots, and a non-destructive way back to any earlier turn.
- Provenance & arcturn blameReasoning-level attribution — which turn and evidence wrote each line of a file.
- Replay & bisectRe-run a session's prompts against a live model or a recorded cassette, and binary-search for where behaviour diverged.
- Audit trail & cost accountingThe append-only permission/tool trail, live spend tracking, cost ceilings, and pre-run estimates.
- Project memoryDurable notes the agent writes for itself, read back into every later session's prompt.
- ScoutsTime-boxed parallel exploration of an approach in throwaway git worktrees, before you commit to writing it for real.
- Agent teams & background agentsThree ways to spend a second agent — a synchronous sub-agent, a durable /bg task, and a coordinated /team.
- WorkflowsDeterministic, file-defined multi-step runs — a markdown numbered list is the control flow, with the model filling in only the content.
- Agent organizationsTurn a workflow into a software org — named roles with their own models and tools, three dispatch lanes that decide what each can touch, and a human gate for the questions a model should not answer alone.
Extend
11 pages
- Embedding with the SDKUse @arcturn/core to embed the same runtime that powers the arcturn CLI in your own product.
- Agent options referenceEvery AgentOptions field — llm, model, tools, permissions, hooks, limits — with defaults and behavior.
- Events referenceEvery AgentEvent variant, when it fires, subscribe vs on<T>, and the runs-never-reject semantics.
- Custom toolsThe Tool interface in full — schema, execute contract, ToolResult, abort signals — with a complete worked example.
- Permissions from the SDKPermissionEngine, rules, modes, the PermissionRequester callback, and the plan-mode exit gate — wired from code.
- Sessions & persistence from the SDKJsonlSessionStore and MemorySessionStore, resuming a branch, forking, and forcing compaction from code.
- Models & providers from the SDKcreateClient, the model catalog, provider presets, failover chains, consensus panels, and custom endpoints.
- Advanced: sub-agents, MCP, VCR, hooksDelegating to child agents, bridging MCP tools, recording/replaying deterministic sessions, and cost accounting.
- Server modeExpose Arcturn sessions to remote clients over a typed WebSocket protocol.
- Editor integration (ACP)Run Arcturn as an in-editor agent over the Agent Client Protocol.
- Arcturn as an MCP serverLet another agent drive Arcturn over the Model Context Protocol, read-only by default.
Reference
4 pages
- CLI referenceEvery command-line flag and every slash command in one place, with what each is actually for.
- ArchitectureThe package map — how types, ai, core, tools, mcp, tui, protocol, server, and cli fit together — plus one turn traced end to end.
- Model routingReference for per-role model overrides (route config) and failover chains, and how they resolve.
- TelemetryTurn the AgentEvent stream into an OTel-shaped span tree and a metrics union, with zero required dependencies.
Prefer to read the source first? Architecture traces one turn end to end through the package map.
Every turn counts.
Start a session, watch every tool call ask first, then go back and read exactly what happened.
npm install -g arcturn