Usage

The directory you launch OrbCode from becomes the workspace directory: the default target for file operations and commands, and the file listing the model sees in its environment details.

Configuration

settings.json, env vars, custom models, sessions

MCP servers

Connect external tools through the Model Context Protocol

Skills & memory

Reusable instruction sets and AGENTS.md project memory

Hooks

Block, auto-approve, rewrite, or inject context

CLI reference (entry point)

orbcode                       start an interactive session in the current directory
orbcode "<prompt>"            start an interactive session with an initial prompt
orbcode login                 sign in to MatterAI (browser device flow)
orbcode logout                remove the saved token (alias: `/logout`)
orbcode -p "<prompt>"         run a single prompt non-interactively
orbcode -p "…" --yolo         non-interactive with edits/commands auto-approved
orbcode --model <id>          use a specific model for this run (also -m)
orbcode --resume <id>         resume a previous session by id (also -r)
orbcode --version             print version
orbcode --help                show help

Flags

flag	effect
`-p "<prompt>"`	run a single prompt non-interactively, print only the final response
`--yolo`	non-interactive with edits/commands auto-approved (dangerous ones still prompt)
`--model <id>` / `-m`	use a specific model for this run
`--resume <id>` / `-r`	resume a previous session by id
`--version`	print version
`--help`	show help

The TUI always takes over the full terminal screen on launch (prior shell output stays in scrollback). OrbCode needs a real TTY (raw mode) and won’t accept piped stdin in interactive mode — use -p for non-interactive runs.

Slash commands

Slash commands are entered at the input prompt (start with /). Most have aliases or fuzzy matching: typing /mod + enter runs the highlighted match.

command	action
`/help`	list commands
`/model`	scrollable model picker (`/model pro` / `/model mini` / full id selects directly)
`/clear`	clear the screen only, like the terminal’s `clear` — the conversation and context continue
`/new`	start a fresh conversation/session with a clean slate
`/resume`	pick a previous session for this directory and continue it (screen is cleared, conversation replayed)
`/analytics`	open the MatterAI analytics dashboard (`app.matterai.so/orbital`) in the browser
`/compact`	summarize the conversation and replace history with the summary
`/tasks`	print the current task list
`/status`	version, model, account, gateway, context usage, cost, approval modes
`/usage`	fetch plan usage from `/axoncode/profile` (plan, tiered windows, reset date)
`/init`	analyze the codebase and write a concise `.orb/AGENTS.md` for cold-start
`/link`	manage linked repositories (other repos checked for impact on this one)
`/migrate`	import MCP server configs from Claude Code / Claude Desktop
`/mcp`	manage MCP servers — enable, disable, reconnect, view status & tool counts
`/plugins`	browse the plugin marketplace and manage installed plugins (alias: `/plugin`, `/skills`)
`/create-skill`	create a repo-local skill under `.orb/skills/` from a plain-language description
`/weekly-reset`	reset your weekly usage tier (Pro+, once per monthly billing cycle)
`/commit`	check pending changes and create detailed commits
`/code-review`	expert review of pending changes: performance, security, bugs, tests
`/login`	start the browser sign-in flow
`/logout`	remove the saved token
`/version`	print the CLI version
`/exit`	quit (alias: `Ctrl+C`)

Every menu in the CLI (slash commands, @-files, model picker, session picker, followups) is navigable with ↑/↓ and selectable with enter.

Keyboard shortcuts

key	action
`Esc`	interrupt the running turn (or cancel login polling / close a menu)
`Ctrl+C`	quit
`Ctrl+O`	toggle thinking display for the whole transcript (past turns included)
`Shift+Tab`	cycle approval mode: ask → accept edits → auto-approve
`↑` / `↓`	input history, or navigate any open menu
`←` / `→`	move the cursor in the input
`Ctrl+A` / `Ctrl+E`	start / end of line
`Ctrl+U`	clear the input line
`@`	open the file-fuzzy-search menu
`enter`	submit the prompt / select a menu item
`tab`	insert the highlighted `@`-match into the prompt

A trailing newline in a paste submits; multi-line pastes are sent as one input.

Input affordances

@-references — type @ in the input to fuzzy-search workspace files. ↑/↓ to choose, enter/tab inserts the top/selected match into the prompt.
Multi-char paste — pasting multiple lines puts them all in the input; a trailing newline submits.
Slash autocomplete — a menu appears whenever the line starts with /, narrowable by typing more characters.
History — ↑/↓ walks the per-session history (across sessions, persisted in the session file).

Approvals & safety

Read-only tools (read_file / list_files / search_files / web_* / update_todo_list) run without prompting. Mutating tools prompt first:

File edits (file_edit, multi_file_edit, file_write) — prompt shows the target and a diff; y allow once, n deny, a allow for the rest of the session.
Commands (execute_command) — prompt shows the exact command line. The model classifies commands with an isDangerous flag; dangerous commands (deletes, force-pushes, system changes) can never be auto-approved — no a option, and --yolo / session-approval don’t apply.

A denial is reported back to the model as “The user denied this operation.” so it can adjust course rather than fail.

Use Shift+Tab at runtime to cycle the approval mode: ask → accept edits on → auto-approve. The session defaults can also be set in settings.json via autoApproveEdits and autoApproveSafeCommands (dangerous commands still always prompt).

Hooks can override any of this — see Hooks: PreToolUse for permissionDecision: allow | deny | ask and updatedInput.

Headless mode

orbcode -p "explain the build pipeline in this repo"
orbcode -p "fix the lint errors" --yolo

Prints only the final content to stdout (the completion result, or the last assistant message) — no tool activity, no intermediate text.
Errors go to stderr.
Without --yolo, edit/command approvals are auto-denied (read-only analysis).
Followup questions are auto-answered with “proceed with best judgment”.
Project hooks still run, but untrusted project hooks are skipped (set MATTERAI_TRUST_PROJECT_HOOKS=1 to auto-trust them).

The TUI

Streaming responses rendered as markdown (headers, lists, code fences, inline code, links) via a lightweight ANSI renderer.
Thinking — reasoning streams live under ✦ Thinking… and collapses to ✦ Thought for Ns when done. Ctrl+O toggles expanded thinking.
Tool rows — each tool call shows a formatted name, a one-line summary, live “running” state, then ✓/✗ with a short result preview.
Edit diffs — file-modifying tools render a real diff with a stats header and red/green backgrounds, both in the approval prompt and the finished tool row.
Tasks — the model maintains a checklist via update_todo_list, rendered as a compact Tasks panel.
@-references — type @ in the input to fuzzy-search workspace files.
Status bar — approval mode, busy state, model name, context token usage, and session cost.
Spinner tips — after an operation runs for 2s, a random slash-command tip appears under the Thinking / Working spinner.
Figma auto-fetch — paste a figma.com URL into a prompt and the agent pre-fetches the design’s node tree, components, styles, and rendered images before the first completion, so it has visual + structural context from step 0.
Completion card — attempt_completion renders a bordered ”✔ Task completed” card with the result.

MCP servers

OrbCode connects to external tools via the Model Context Protocol (MCP). MCP servers expose tools that appear alongside the native tools as mcp__<server>__<tool> and can be called by the model like any other tool. The /mcp command opens an interactive manager at any time: ↑/↓ to select a server, enter or 2 to toggle enable/disable, r or 3 to reconnect, a or 1 to authenticate a needs-auth OAuth server, esc to close. Each server shows a live status icon (✓ connected, △ needs-auth, ✗ failed, ○ disabled, ⋯ connecting) plus a tool count when connected. You can also manage servers from the command line with orbcode mcp add/remove/list. See the MCP servers page for the three configuration scopes, server types, and OAuth options.

Skills

Skills are reusable instruction sets the model can load on demand. A skill is a directory containing a SKILL.md file with optional YAML frontmatter and a markdown body of specialized instructions. Place a directory under ~/.orbcode/skills/ (user, applies everywhere) or .orbcode/skills/ (project, checked into the repo). The skill catalog (names + descriptions + when-to-use) is injected into the system prompt; when a task matches a skill’s when_to_use condition, the model calls the use_skill tool to load the full instructions into context. Project skills override user skills on name collisions. See the Skills & memory page for the full reference.

AGENTS.md memory

AGENTS.md files provide project- and user-level instructions that are injected into every system prompt — build commands, code style, architecture notes, conventions. This is OrbCode’s equivalent of Claude Code’s CLAUDE.md, using the open AGENTS.md filename so it works across tools. Files are loaded in this order (lowest precedence first): user memory (~/.orbcode/AGENTS.md), project memory (AGENTS.md and .orb/AGENTS.md in the cwd and parents), and local memory (AGENTS.local.md, private per-machine). Use /init to have OrbCode generate or refine a starter AGENTS.md by analyzing the codebase. See the Skills & memory page for the discovery order and @include directives.

`/init` — generate `.orb/AGENTS.md`

/init investigates the project (layout, key config files, a few representative sources) and writes a concise .orb/AGENTS.md at the repo root, capped at ~150 lines so it stays cheap to include in every future prompt. The generated file covers:

What the project does (1-2 lines) and its main tech stack.
Project structure — the key directories/files and what each is responsible for.
Architecture — how the main pieces fit together (entry points, data/control flow).
Business-logic mapping — the rules and invariants the model needs to honor.
Code patterns and conventions — the idioms the codebase already uses.

The prompt also tells the agent to refine an existing AGENTS.md rather than overwriting it, and to fold in any existing AI assistant rules (CLAUDE.md, .cursorrules, .github/copilot-instructions.md). The .orb/ folder is shared with the Orbital IDE extension — the same AGENTS.md is read by both, so a single source of truth covers your terminal and your editor.

`/link` — linked repositories

/link opens an interactive manager for linked repositories: other repos on your machine whose AGENTS.md should be considered when you’re working in this one, so a change here is checked for impact on (or propagated to) them. Each link is just a folder path — absolute, ~/path, or relative to the project. Links are persisted per-project in .orb/links.json in the current repo:

{
  "links": [
    { "path": "/Users/me/projects/shared-lib" },
    { "path": "~/projects/design-system" }
  ]
}

At session start, OrbCode walks the links, reads each linked repo’s AGENTS.md (from .orb/, .orbital/, or .orbcode/), and pulls them in ahead of time into the agent’s environment details — the model sees them as part of the workspace before it starts working. .orb/links.json is shared with the Orbital IDE extension — links written by the IDE are honored by the CLI and vice versa, so the two tools stay in sync without a manual merge. Use /link (or the IDE’s /link) to add or remove entries interactively.

Tools

Active in the CLI (schemas byte-identical to the extension’s native tools):

tool	executor notes
`read_file`	line-numbered output, 1000-line cap, offset/limit
`file_edit`	single replacement; unique-match enforcement; `replace_all`; empty `old_string` = whole file
`multi_file_edit`	batched edits grouped per file, per-edit OK/FAILED results
`file_write`	creates parent dirs, full-content writes
`list_files`	optional recursive, ignores `node_modules`/`.git`/`build` dirs, 800-entry cap
`search_files`	regex search with glob `file_pattern`, 300-match cap, binary skip
`execute_command`	user’s shell, 120s timeout, 30k output cap, optional cwd
`web_search` / `web_fetch`	proxied through the MatterAI backend with your token
`update_todo_list`	drives the TUI todo panel
`use_skill`	loads a skill’s full instructions by name or by an explicit skill directory / `SKILL.md` path
`figma_fetch`	fetches a Figma design’s node tree, components, styles, and rendered image URLs (authenticated through the MatterAI backend)
`ask_followup_question`	interactive menu in the TUI
`attempt_completion`	ends the turn with a completion card
`mcp__<server>__<tool>`	any tool exposed by a connected MCP server (see MCP servers)

For hook matchers, use these tool names verbatim (e.g. "execute_command", "file_edit|file_write|multi_file_edit").

Sessions

Stored in ~/.orbcode/sessions/<id>.json.
Power /resume (in-session picker) and --resume <id> / -r (from the CLI).
Record the conversation, tool results, task title, and cost.
The backend-generated task title is fetched once per task and shows in the status bar, the session file, and the terminal window title (<title> (orbcode)).

Troubleshooting

Problem	Fix
Keyboard input does nothing	OrbCode needs a real TTY (raw mode); use `-p` for non-interactive runs.
`Esc` doesn’t stop a turn	`Esc` interrupts the in-flight request via `AbortController`; one turn may still complete and surface a `<system_reminder>`.
Slash command doesn’t run	Make sure the line starts with `/`; partial matches (e.g. `/mod`) run the highlighted match — press `enter`.
`-p` returns empty	Without `--yolo`, approvals are auto-denied; with `--yolo`, the final response is whatever the last assistant turn produced.
Sessions list is empty	`/resume` only shows sessions whose working directory matches the current one.

Getting Started

AI Coding Agents

Axon Models

AI Code Reviews

Integrations

OrbCode CLI Usage

Usage

Configuration

MCP servers

Skills & memory

Hooks

CLI reference (entry point)

Flags

Slash commands

Keyboard shortcuts

Input affordances

Approvals & safety

Headless mode

The TUI

MCP servers

Skills

AGENTS.md memory

`/init` — generate `.orb/AGENTS.md`

`/link` — linked repositories

Tools

Sessions

Troubleshooting

​Usage

Configuration

MCP servers

Skills & memory

Hooks

​CLI reference (entry point)

​Flags

​Slash commands

​Keyboard shortcuts

​Input affordances

​Approvals & safety

​Headless mode

​The TUI

​MCP servers

​Skills

​AGENTS.md memory

​/init — generate .orb/AGENTS.md

​/link — linked repositories

​Tools

​Sessions

​Troubleshooting

Usage

CLI reference (entry point)

Flags

Slash commands

Keyboard shortcuts

Input affordances

Approvals & safety

Headless mode

The TUI

MCP servers

Skills

AGENTS.md memory

`/init` — generate `.orb/AGENTS.md`

`/link` — linked repositories

Tools

Sessions

Troubleshooting