MatterAI
MATTERAI / ORBCODE CLIv0.5.1MIT

AGENTIC CODING
IN YOUR
TERMINAL.

A standalone terminal port of the Orbital extension — the same Axon models, the same native tool schemas, the same MatterAI auth — rebuilt from scratch as an interactive TUI with streaming chat, live thinking, tool activity, edit approvals, and project memory.

$ npm install -g @matterailab/orbcode
VIEW DOCSGITHUB

Requires Node.js ≥ 20 · No Bun needed

orbcode — zsh
OrbCode CLI showing a streaming TUI session with live thinking, tool activity, and edit approval
QUICK START

THREE COMMANDS.
YOU'RE IN.

Install globally, sign in once via your browser, then start an interactive agent session from any project directory. The directory you launch from becomes the workspace — the default target for file operations and the file listing the model sees.

  • →Read, edit, run commands, fix bugs — ask in plain English.
  • →Source-of-truth builds: git clone + npm link.
quick start
# install
$ npm install -g @matterailab/orbcode
# sign in once via your browser
$ orbcode login
# start an interactive session
$ cd your-project && orbcode
▸ ready
0K
Largest context window
0
Max tool steps per turn
0
Built-in Axon models
0
Slash commands
THE TUI

BUILT FOR
THE TERMINAL.

OpenTUI native retained renderer with OrbCode-owned dark and light palettes, full-screen rendering, mouse input, and truly opaque panels. The terminal theme can't override it.

Streaming TUI

Live Markdown

Streaming responses rendered as markdown with a native OpenTUI surface. Headers, lists, code fences, inline code, and links — all painted by OrbCode, so terminal theme can't override it.

Reasoning

Live Thinking

Reasoning streams under a collapsible ✦ Thinking block and collapses to ✦ Thought for Ns when done. Ctrl+O toggles thinking for the whole transcript.

Tool Rows

Transparent Actions

Each tool call shows a formatted name, a one-line summary, live running state, then ✓/✗ with a short result preview.

Edit Diffs

Real 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.

Approvals

Safe by Default

Read-only tools run freely. File edits and commands prompt first. Dangerous commands can never be auto-approved — no `--yolo` override.

Headless Mode

Scriptable

Pipe a single prompt with -p for scripts and CI. Prints only the final content to stdout; errors go to stderr. Add --yolo to auto-approve edits.

Hooks

Claude-Code Compatible

Block, auto-approve, rewrite, or inject context at fixed points in the agent loop. Scripts written for Claude Code work here unchanged.

MCP Servers

Any Tool

Connect stdio, HTTP, or SSE MCP servers in three scopes (user / project / local). Full OAuth 2.0, M2M grants, and a runtime /mcp manager.

Plugins

Marketplace

Browse Anthropic's official plugin marketplace from /plugins. Skills, commands, and bundled MCP servers install as a pinned bundle.

Skills

Reusable Prompts

Drop a SKILL.md into ~/.orbcode/skills/ or .orb/skills/. OrbCode injects the catalog into every system prompt and loads the body on demand via use_skill.

AGENTS.md

Project Memory

Project, user, and local AGENTS.md files auto-load into every system prompt. @include directives compose multi-file guides with cycle detection.

Sessions

Resume Anywhere

Every session is persisted to ~/.orbcode/sessions/. /resume and --resume <id> continue exactly where you left off, with thinking blocks intact.

MODEL FAMILY

THREE AXON MODELS,
BUILT IN.

The same Axon models that power Orbital, available in your terminal. axon-eido-3-code-mini is the default. Switch with /model or pick directly: /model pro, /model mini, /model flash.

Add Anthropic or any OpenAI-compatible provider via customModels in settings.json — the Vercel AI SDK powers them through the same agent loop, tools, and approvals.

$3 /M in · $9 /M out

axon-eido-3-code-pro

Frontier model for the hardest agentic tasks.

  • →400k context · 64k output
  • →Maximum reasoning depth
  • →Best for complex, long-running tasks
$1.5 /M in · $4.5 /M out

axon-eido-3-code-mini

Default. The everyday workhorse for professional development.

  • →400k context · 64k output
  • →Fast and cost-efficient
  • →Best for day-to-day coding & agents
FREE

axon-eido-3-flash

Free tier for quick tasks, experiments, and budget-friendly runs.

  • →200k context · 64k output
  • →No-cost inference
  • →Best for short tasks & exploration
SLASH COMMANDS

EVERYTHING IN
A SLASH.

Type / to open the autocomplete menu. Every menu — 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.

/help
List commands
/new
Start a fresh session
/resume
Pick a previous session for this directory
/model
Switch model (pro / mini / flash or any id)
/theme
Dark or light palette (persists)
/attach
Add files via the native file picker
/init
Analyze the repo and bootstrap AGENTS.md
/compact
Summarize the conversation, replace history
/mcp
Manage MCP servers (enable, auth, reconnect)
/plugins
Browse and install the plugin marketplace
/skills
Alias for /plugins
/tasks
Print the current task list
/status
Version, model, account, gateway, cost
/usage
Fetch plan usage
/link
Link another repo so changes are checked against it
/task
Reference a previous session as context
/analytics
Open the MatterAI analytics dashboard
/login · /logout
Browser device-flow sign-in
/clear · /version · /exit
Clear screen, print version, quit
KEYBOARD SHORTCUTS
Interrupt the running turn (or close a menu)Esc
QuitCtrl+C
Toggle thinking display for the whole transcriptCtrl+O
Cycle approval mode: ask → accept edits → auto-approveShift+Tab
Input history, or navigate any open menu↑ / ↓
Start / end of lineCtrl+A / Ctrl+E
Clear the input lineCtrl+U
Open the native file picker to add attachmentsCtrl+F
AUTHENTICATION

BROWSER
DEVICE FLOW.

No copy/paste. orbcode login opens your browser, you click Authorize, and you're in. The token is handed out exactly once from redis.

  1. CLI calls POST /orbcode/auth/start and gets a 10-minute device code.
  2. Browser opens to app.matterai.so/orbital?loginType=orbcode&devicecode=….
  3. Already signed in → the Authorize dialog shows immediately. Otherwise, you sign in first; the device code is preserved through OAuth and email/password.
  4. CLI polls GET /orbcode/auth/poll every 3s until success.
  5. Token is saved to ~/.orbcode/config.json (mode 0600). Use /logout to clear it.
FALLBACKS & OVERRIDES
Set apiKey in ~/.orbcode/settings.json (or .orbcode/settings.json) to skip login.apiKey
Env var that takes precedence over everything — perfect for CI.MATTERAI_TOKEN
Same as apiKey in settings.json.MATTERAI_API_KEY
Same as baseUrl in settings.json.MATTERAI_BASE_URL
Model override — what --model sets internally.MATTERAI_MODEL
Config directory (default ~/.orbcode).MATTERAI_CONFIG_DIR
Device-auth backend (default https://api.matterai.so).MATTERAI_BACKEND_URL
Webapp for the authorize page (default https://app.matterai.so).MATTERAI_APP_URL

Tokens are MatterAI JWTs. A token whose payload has env: "development" routes API calls to localhost:3000, matching the extension.

MCP SERVERS

ANY TOOL,
ANY TRANSPORT.

Connect external tools via the Model Context Protocol. Server tools appear alongside native tools as mcp__<server>__<tool> and the model calls them like any other. Manage everything at runtime with /mcp.

THREE SCOPES, MERGED
User~/.orbcode/settings.json

Applies to every project on this machine.

Project.mcp.json

Check-into-git, shared with the team. Closer-to-cwd wins. Compatible with Claude Code's .mcp.json.

Local.orbcode/settings.json

Per-project, per-machine overrides (not checked in).

CLI MANAGEMENT
# stdio (default): name + command + args $ orbcode mcp add filesystem \ npx -y @modelcontextprotocol/server-filesystem ~/projects # http transport $ orbcode mcp add --transport http linear-server \ https://mcp.linear.app/mcp # sse with a header $ orbcode mcp add -t sse \ --header "Authorization=Bearer ${TOKEN}" \ my-sse https://example.com/sse # OAuth servers $ orbcode mcp add --transport http --oauth notion \ https://mcp.notion.com/mcp # list & remove $ orbcode mcp list $ orbcode mcp remove filesystem
Static headers

API keys / PATs in headers with ${ENV_VAR} expansion. Tokens read from the environment, never written to disk.

OAuth 2.0 (user)

Full authorization-code flow: RFC 9728 discovery, RFC 8414 metadata, PKCE, dynamic client registration, token refresh. Tokens persist per-server under ~/.orbcode/mcp-auth/.

OAuth (M2M)

client_credentials and private_key_jwt grants for service-to-service auth — direct token exchange, no browser.

PLUGINS & SKILLS

EXTEND WITHOUT
FORKING.

PLUGIN MARKETPLACE

/plugins

Browse Anthropic's official Claude plugin marketplace, or install directly from the shell. OrbCode installs the complete pinned bundle under .orb/plugins/<name>/, loads skills with a <plugin>:<skill> namespace, and brings bundled MCP servers in as project-scoped servers.

$ orbcode plugin install clickhouse@claude-plugins-official $ orbcode plugin list $ orbcode plugin uninstall clickhouse
SKILLS

Reusable instructions

Drop a directory containing SKILL.md into ~/.orbcode/skills/ (user) or .orb/skills/ (project). The catalog — names, descriptions, when-to-use hints — is injected into every system prompt. When a task matches, the model calls use_skill and the body loads on demand.

--- description: Write concise, idiomatic Go code when_to_use: the task involves writing or reviewing Go code --- # Go style skill - Use errors.Join for multi-error aggregation - Prefer table-driven tests
MEMORY

THE MODEL READS
YOUR NOTES.

AGENTS.md files provide project- and user-level instructions injected into every system prompt — build commands, code style, architecture notes, conventions. Use the open AGENTS.md filename so it works across tools.

USER MEMORY
~/.orbcode/AGENTS.md

Personal global instructions. Lowest precedence.

PROJECT MEMORY
AGENTS.md · .orbcode/AGENTS.md

Walked from cwd up through parents (closer-to-cwd wins). Checked into the repo, shared with the team.

LOCAL MEMORY
AGENTS.local.md

Private per-machine overrides. Gitignore this.

@INCLUDE DIRECTIVES

An AGENTS.md file can include other files with @path references. Includes resolve recursively up to 5 levels with cycle detection.

# Project guide See the detailed style guide: @./docs/style.md And the global one: @~/orbcode-global.md
/init

Run /init to have OrbCode analyze the codebase and create or improve the AGENTS.md in the repo's .orb/ directory.

Higher-precedence files (closer to cwd, then local) appear later in the system prompt and get more weight from the model.

SAFETY

APPROVALS &
CONTROL.

Read-only tools run without prompting. File edits and commands prompt first, with the exact target or command line shown before anything runs. Dangerous commands — deletes, force-pushes, system changes — can never be auto-approved.

Ask

Prompt for every edit and command. The default.

Accept Edits

Auto-approve file edits; commands still prompt.

Auto-Approve

Auto-approve safe commands too. Dangerous ones still prompt.

Deny Feedback

Denials are reported back so the model adjusts course.

Cycle modes at runtime with Shift+Tab. Set session defaults via autoApproveEdits and autoApproveSafeCommands in settings.json.

approval prompt
▸ Execute Command
git push --force origin main
⚠ dangerous: force-push
Allow this command?
[y] allow once[n] deny[a] allow session
dangerous commands have no auto-approve option
HOOKS

LIFECYCLE
EXTENSION.

Shell commands OrbCode runs at fixed points in the agent loop. Same contract as Claude Code's hooks — scripts written for it work here. Use them to block dangerous actions, auto-approve trusted ones, rewrite tool inputs, inject context, or keep the agent working until a condition is met.

TWO-MINUTE EXAMPLE

Make OrbCode block rm -rf and append the git branch to every prompt.

# ~/.orbcode/hooks/guard.sh (chmod +x) #!/usr/bin/env bash input=$(cat) cmd=$(printf '%s' "$input" | jq -r '.tool_input.command // empty') if printf '%s' "$cmd" | grep -Eq 'rm -rf (/|~|\*)'; then echo "Refusing destructive command: $cmd" >&2 exit 2 # exit 2 = block the tool fi exit 0
~/.orbcode/settings.json
{ "hooks": { "PreToolUse": [ { "matcher": "execute_command", "hooks": [ { "type": "command", "command": "~/.orbcode/hooks/guard.sh", "timeout": 30 } ] } ], "UserPromptSubmit": [ { "hooks": [ { "type": "command", "command": "echo Branch: $(git branch --show-current)" } ] } ] } }
EVENTS AT A GLANCE
SessionStartFirst turn of a session (or after --resume)matcher: source
UserPromptSubmitBefore each prompt is sent to the modelmatcher: —
PreToolUseBefore a tool runs (and before its approval)matcher: tool name
PostToolUseAfter a tool returnsmatcher: tool name
NotificationWhen OrbCode needs permission or a follow-upmatcher: —
StopWhen the model is about to finish the turnmatcher: —
PreCompactBefore /compact summarizes the conversationmatcher: trigger
SessionEndOn quit, /logout, or end of a -p runmatcher: reason

A hook receives JSON on stdin and influences OrbCode via its exit code: 0 success, 2 block, or a JSON object on stdout for fine control. Hooks run with a redacted environment (your API token and other credential-like vars are stripped). Most-restrictive permission wins: deny > ask > allow.

SCRIPTABLE

HEADLESS MODE
& TOOLS.

Run OrbCode non-interactively with -p. Prints only the final content to stdout, errors to stderr. Without --yolo, edit and command approvals are auto-denied (read-only analysis). Followup questions are auto-answered with "proceed with best judgment."

USAGE
orbcode start an interactive session orbcode "<prompt>" start with an initial prompt orbcode login sign in via browser device flow orbcode -p "<prompt>" single prompt, print only the final response orbcode -p "…" --yolo non-interactive with edits auto-approved orbcode --model <id> use a specific model (also -m) orbcode --resume <id> resume a previous session (also -r) orbcode --version print version orbcode --help show help orbcode mcp add … add an MCP server orbcode plugin install … install from the marketplace orbcode mcp list list configured servers
NATIVE TOOLS

Schemas are byte-identical to the Orbital extension's native-tools set, so behavior is consistent across both.

read_file

Line-numbered output (LINE|content, 6-char pad), 1000-line cap, offset/limit.

file_edit · multi_file_edit

Unique-match enforcement, replace_all, batched per-file results.

file_write

Creates parent dirs, full-content writes.

list_files · search_files

Optional recursive, ignores node_modules/.git/build, glob file_pattern.

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 standalone or namespaced plugin skill instructions.

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.

ATTACHMENTS

DRAG FILES IN.
READ THE DOC.

Use /attach or Ctrl+F to open the native file picker, or drag files onto the input box. Documents are extracted to bounded text before the model call; attached filenames stay visible in the composer, queue, transcript, and resumed history.

Supported: CSV, XLSX, DOCX, PDF, plain-text, JSON, Markdown, PNG, JPEG, WebP.

SESSIONS

RESUME
WHERE YOU LEFT.

Every session is persisted to ~/.orbcode/sessions/<id>.json. Use /resume to pick a previous session and continue it (screen cleared, conversation replayed) or orbcode --resume <id> from the shell.

Thinking blocks (including Claude's signed blocks) are preserved across turns and round-trip correctly.

CONFIGURATION

TWO FILES.
NO MAGIC.

Under ~/.orbcode/: a state file OrbCode writes itself, and a user-managed settings file. A project-level .orbcode/settings.json layers on top.

config.json (state)

Login token, chosen model, theme, approval defaults. Mode 0600, created on first save.

settings.json (you manage)

Created as an empty {} on first run.

{ "apiKey": "<token used instead of logging in>", "baseUrl": "https://my-gateway.example.com/v1", "model": "my-custom-model", "autoApproveEdits": false, "autoApproveSafeCommands": false, "customModels": [ { "id": "my-custom-model", "name": "My Custom Model", "contextWindow": 128000, "maxOutputTokens": 32000, "inputPrice": 0.000001, "outputPrice": 0.000002 } ], "env": { "MY_VAR": "value" } }
PRECEDENCE
env vars

MATTERAI_TOKEN, MATTERAI_API_KEY, MATTERAI_BASE_URL, MATTERAI_MODEL, MATTERAI_CONFIG_DIR, …

project settings.json

./.orbcode/settings.json (closer-to-cwd wins for AGENTS.md; this is layered)

user settings.json

~/.orbcode/settings.json

config.json

App-written state, lowest precedence

All keys in settings.json are optional. customModels entries appear in the /model picker alongside built-in Axon models; baseUrl points the chat client at any OpenAI-compatible gateway.

OTHER PROVIDERS

BRING YOUR OWN
MODEL.

Anything with a provider is served through the Vercel AI SDK, reusing the same agent loop, tools, and approvals. Auth is the provider's own key — 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 via @ai-sdk/anthropic. Adaptive thinking and reasoning streaming on by default. effort (low…max) tunes depth. Thinking blocks are preserved across turns and round-trip with their signatures.

provider: "openai-compatible"

Any OpenAI-compatible endpoint; requires baseUrl. Key from apiKey on the entry. Third-party models aren't shown in the TUI picker — they're available headlessly via orbcode -p "…" --model <id>.

START CODING
IN THE TERMINAL.

Install globally with npm, sign in once, and run orbcode from any project directory. Open source under the MIT license.

$ npm install -g @matterailab/orbcode
VIEW ON GITHUB
Docs

Full reference: install, usage, configuration, hooks.

GitHub

Source code, issues, and releases.

npm

Install the latest release globally.