OrbCode CLI

Agentic coding in your terminal — powered by Axon models by MatterAI.

📖 Full documentation: https://docs.matterai.so/orbcode-cli/overview

OrbCode CLI is a standalone terminal port of the Orbital extension: the same Axon models, the same native tool schemas, the same MatterAI auth backend — rebuilt from scratch as an interactive TUI with streaming chat, live thinking display, tool activity rows, edit/command approvals, and todo tracking.

Table of contents

• Quick start
• Install
• Updating / relinking
• Usage
• Authentication
• Models
• The TUI
• Slash commands
• Keyboard shortcuts
• Approvals & safety
• Headless mode
• Configuration
• Hooks
• MCP servers
• Skills
• AGENTS.md memory
• Architecture
• Tools
• Agent loop
• Development
• Tests
• Troubleshooting
• Documentation
• Contributing
• License

Quick start

npm install -g @matterailab/orbcode   # install the CLI (needs Node.js >= 20)
orbcode login                          # sign in once via your browser
cd your-project && orbcode             # start coding

That's it — you're in an interactive agent session. Ask it to read, edit, run commands, or fix bugs. New here? Skim the docs or jump to Usage.

Prefer not to install globally? Run it on the fly:

npx @matterailab/orbcode

Install

Requires Node.js >= 20.

npm install -g @matterailab/orbcode

Then, from any project directory:

orbcode

To update later: npm update -g @matterailab/orbcode (or re-run the install command).

From source (development)

git clone https://github.com/MatterAIOrg/OrbCode.git
cd OrbCode
npm install
npm run build
npm link        # exposes the global `orbcode` command

Updating / relinking

npm link creates a symlink to this repo, so after pulling changes you only need to rebuild — no relink required:

npm run build   # the linked `orbcode` command picks this up immediately

Relink only when the package name or bin entry changes (e.g. the package was renamed orbitalcode → orbcode):

npm unlink -g orbitalcode   # remove a stale link under the old name (once)
npm link

The version reported by orbcode --version is read from package.json at runtime — bumping the version there is all that's needed.

Usage

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 -p "<prompt>"   run a single prompt non-interactively, print only the final response
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

The TUI always takes over the full terminal screen on launch (prior shell output stays in scrollback).

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

Authentication

Browser-based device flow with polling (no copy/paste needed):

1. orbcode login (or /login in the TUI) calls POST /orbcode/auth/start on the MatterAI backend, which issues a one-time 48-hex device code (10-minute lifetime, stored in redis).
2. The CLI opens https://app.matterai.so/orbital?loginType=orbcode&devicecode=<code> in your browser:
3. Already signed in → the webapp shows the Authorize OrbCode CLI dialog immediately.
4. Not signed in → you're redirected to sign-in first. The devicecode query param is preserved through the OAuth state (Google/Microsoft) and the email/password path, so the authorize dialog appears right after sign-in.
5. Clicking Authorize binds your session token to the device code (POST /orbcode/auth/authorize).
6. Meanwhile the CLI polls GET /orbcode/auth/poll?devicecode=… (every 3s by default, bounded by the code's lifetime). The token is handed out exactly once — the redis key is deleted on first successful poll.
7. The CLI verifies the token against the profile endpoint and saves it.

Fallbacks & overrides:

• settings.json key: set apiKey in ~/.orbcode/settings.json (or a project's .orbcode/settings.json) to skip login. The login screen itself is browser-redirect only.
• Env token: set MATTERAI_TOKEN to skip login entirely (takes precedence over everything).
• Dev endpoints: MATTERAI_BACKEND_URL (default https://api.matterai.so) and MATTERAI_APP_URL (default https://app.matterai.so) override where the device flow points — useful against a local backend/webapp.
• Tokens are MatterAI JWTs. A token whose payload has env: "development" automatically routes API calls to http://localhost:3000, matching the extension's behavior.

Sign out with /logout (removes the saved token).

Models

The built-in Axon models are listed below; /model opens a scroll-and-select picker (/model <id> still selects directly). Additional models can be declared via customModels in settings.json. The choice persists across sessions.

axon-eido-3-code-mini is the default. All three support native JSON tool calls and image input. Cost comes from the API's usage chunks (is_byok-aware) and is shown in the status bar.

Other providers (Anthropic, OpenAI-compatible)

The Axon models go through the MatterAI gateway as before. A customModels entry that sets a provider is instead served through the Vercel AI SDK, reusing the same agent loop, tools, and approvals — auth is the provider's own key (env var or apiKey), not the MatterAI login.

{
  "model": "claude-opus-4-8",
  "customModels": [
    {
      "id": "claude-opus-4-8",
      "name": "Claude Opus 4.8",
      "provider": "anthropic",
      "contextWindow": 1000000,
      "maxOutputTokens": 64000,
      "inputPrice": 0.000005,
      "outputPrice": 0.000025,
      "effort": "high"
    },
    {
      "id": "some-model",
      "provider": "openai-compatible",
      "baseUrl": "https://api.other-host.com/v1"
    }
  ]
}

• provider: "anthropic" → native /v1/messages (@ai-sdk/anthropic). Key from ANTHROPIC_API_KEY (or apiKey on the entry). Adaptive thinking + reasoning streaming are on by default; effort (low…max) tunes depth; prompt caching breakpoints are set on the system prompt and conversation prefix automatically. Thinking blocks are preserved across turns (stored with the session and replayed with their signatures), so interleaved thinking with tool use round-trips correctly. Set "reasoning": false to disable thinking (e.g. for models that don't support effort).
• provider: "openai-compatible" → any OpenAI-compatible endpoint; requires baseUrl. Key from apiKey on the entry.

Note: Third-party models are not shown in the TUI's /model picker. They're still available headlessly via orbcode -p "..." --model <id> (or MATTERAI_MODEL=<id>); in an interactive session, /model claude-opus-4-8 prints the exact command to run.

Anything without a provider (or provider: "matterai") keeps using the MatterAI gateway untouched.

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… (last few lines, dimmed) and collapses to ✦ Thought for Ns when done. ctrl+o toggles expanded thinking for subsequent turns. Reasoning arrives from the API as reasoning/reasoning_content deltas or inline <think>…</think> blocks — all are routed to the thinking display.
• Tool rows: each tool call shows a formatted name ("Read File", "Execute Command"…), one-line summary (file path, command, query…), live "running" state, then ✓/✗ with a short result preview.
• Edit diffs: file-modifying tools render a real diff — stats header ("Added 2 lines, removed 1 line"), line-number gutter, red/green backgrounds — both in the approval prompt (before anything is written) and in the finished tool row.
• Tasks: the model maintains a checklist via update_todo_list; it renders as a compact Tasks panel (□ pending / ◧ in progress / ■ done).
• @-references: type @ in the input to fuzzy-search workspace files; ↑/↓ to choose, enter/tab inserts the top/selected match into the prompt.
• Followup questions: ask_followup_question renders a selectable menu (arrow keys, number quick-pick, or free-text answer).
• Completion: attempt_completion renders a bordered "✔ Task completed" card with the result.
• Status bar: approval mode (⏵⏵ accept edits on, shift+tab to cycle), busy state, model name, context token usage, and session cost.
• Input box: top/bottom rule borders with a ❯ prompt, history (↑/↓), cursor movement (←/→, ctrl+a/e), kill line (ctrl+u), multi-char paste (a trailing newline submits), and a slash-command autocomplete menu when the line starts with /. Every menu in the CLI (slash commands, @-files, model picker, session picker, followups) is navigable with ↑/↓ and selectable with enter; a partial command like /mod + enter runs the highlighted match.

Slash commands

Keyboard shortcuts

| key | action