@matterailab/orbcode 0.2.1 โ†’ 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,7 +1,17 @@
1
1
  # OrbCode CLI
2
2
 
3
+ [![npm version](https://img.shields.io/npm/v/@matterailab/orbcode?color=blue&logo=npm)](https://www.npmjs.com/package/@matterailab/orbcode)
4
+ [![npm downloads](https://img.shields.io/npm/dm/@matterailab/orbcode?logo=npm)](https://www.npmjs.com/package/@matterailab/orbcode)
5
+ [![license](https://img.shields.io/npm/l/@matterailab/orbcode?color=green)](./LICENSE)
6
+ [![node](https://img.shields.io/node/v/@matterailab/orbcode?color=green&logo=node.js)](https://nodejs.org)
7
+ [![github stars](https://img.shields.io/github/stars/MatterAIOrg/OrbCode?style=social&logo=github)](https://github.com/MatterAIOrg/OrbCode)
8
+ [![github issues](https://img.shields.io/github/issues/MatterAIOrg/OrbCode?logo=github)](https://github.com/MatterAIOrg/OrbCode/issues)
9
+ [![docs](https://img.shields.io/badge/docs-docs.matterai.so-purple)](https://docs.matterai.so/orbcode-cli/overview)
10
+
3
11
  Agentic coding in your terminal โ€” powered by **Axon models by MatterAI**.
4
12
 
13
+ > ๐Ÿ“– **Full documentation: <https://docs.matterai.so/orbcode-cli/overview>**
14
+
5
15
  OrbCode CLI is a standalone terminal port of the Orbital extension: the same Axon
6
16
  models, the same native tool schemas, the same MatterAI auth backend โ€” rebuilt from
7
17
  scratch as an interactive TUI with streaming chat, live thinking display, tool
@@ -13,6 +23,7 @@ activity rows, edit/command approvals, and todo tracking.
13
23
 
14
24
  ## Table of contents
15
25
 
26
+ - [Quick start](#quick-start)
16
27
  - [Install](#install)
17
28
  - [Updating / relinking](#updating--relinking)
18
29
  - [Usage](#usage)
@@ -25,17 +36,39 @@ activity rows, edit/command approvals, and todo tracking.
25
36
  - [Headless mode](#headless-mode)
26
37
  - [Configuration](#configuration)
27
38
  - [Hooks](#hooks)
39
+ - [MCP servers](#mcp-servers)
40
+ - [Skills](#skills)
41
+ - [AGENTS.md memory](#agentsmd-memory)
28
42
  - [Architecture](#architecture)
29
43
  - [Tools](#tools)
30
44
  - [Agent loop](#agent-loop)
31
45
  - [Development](#development)
32
46
  - [Tests](#tests)
33
47
  - [Troubleshooting](#troubleshooting)
48
+ - [Documentation](#documentation)
34
49
  - [Contributing](#contributing)
35
50
  - [License](#license)
36
51
 
37
52
  ---
38
53
 
54
+ ## Quick start
55
+
56
+ ```bash
57
+ npm install -g @matterailab/orbcode # install the CLI (needs Node.js >= 20)
58
+ orbcode login # sign in once via your browser
59
+ cd your-project && orbcode # start coding
60
+ ```
61
+
62
+ That's it โ€” you're in an interactive agent session. Ask it to read, edit, run
63
+ commands, or fix bugs. New here? Skim the [docs](https://docs.matterai.so/orbcode-cli/overview)
64
+ or jump to [Usage](#usage).
65
+
66
+ Prefer not to install globally? Run it on the fly:
67
+
68
+ ```bash
69
+ npx @matterailab/orbcode
70
+ ```
71
+
39
72
  ## Install
40
73
 
41
74
  Requires **Node.js >= 20**.
@@ -143,18 +176,20 @@ Sign out with `/logout` (removes the saved token).
143
176
 
144
177
  ## Models
145
178
 
146
- The two Axon models are built in; `/model` opens a scroll-and-select picker
147
- (`/model <id>` still selects directly). Additional models can be declared via
148
- `customModels` in settings.json. The choice persists across sessions.
179
+ The built-in Axon models are listed below; `/model` opens a scroll-and-select
180
+ picker (`/model <id>` still selects directly). Additional models can be
181
+ declared via `customModels` in settings.json. The choice persists across
182
+ sessions.
149
183
 
150
- | id | context | max output | pricing |
151
- | ---------------------- | ------- | ---------- | ------------------ |
152
- | `axon-eido-3-code-pro` | 400k | 64k | $3/M in ยท $9/M out |
153
- | `axon-code-2-5-pro` | 400k | 64k | $2/M in ยท $6/M out |
154
- | `axon-code-2-5-mini` | 400k | 64k | free |
184
+ | id | context | max output | pricing |
185
+ | ------------------------- | ------- | ---------- | ---------------------- |
186
+ | `axon-eido-3-code-pro` | 400k | 64k | $3/M in ยท $9/M out |
187
+ | `axon-eido-3-code-mini` | 400k | 64k | $1.5/M in ยท $4.5/M out |
188
+ | `axon-code-2-5-pro` | 400k | 64k | $2/M in ยท $6/M out |
189
+ | `axon-code-2-5-mini` | 400k | 64k | free |
155
190
 
156
- `axon-code-2-5-pro` is the default. All three support native JSON tool calls and
157
- image input. Cost comes from the API's usage chunks (`is_byok`-aware) and is
191
+ `axon-eido-3-code-mini` is the default. All four support native JSON tool calls
192
+ and image input. Cost comes from the API's usage chunks (`is_byok`-aware) and is
158
193
  shown in the status bar.
159
194
 
160
195
  ### Other providers (Anthropic, OpenAI-compatible)
@@ -199,6 +234,11 @@ MatterAI login.
199
234
  - `provider: "openai-compatible"` โ†’ any OpenAI-compatible endpoint; requires
200
235
  `baseUrl`. Key from `apiKey` on the entry.
201
236
 
237
+ > **Note:** Third-party models are **not** shown in the TUI's `/model` picker.
238
+ > They're still available headlessly via `orbcode -p "..." --model <id>` (or
239
+ > `MATTERAI_MODEL=<id>`); in an interactive session, `/model claude-opus-4-8`
240
+ > prints the exact command to run.
241
+
202
242
  Anything without a `provider` (or `provider: "matterai"`) keeps using the
203
243
  MatterAI gateway untouched.
204
244
 
@@ -256,8 +296,9 @@ MatterAI gateway untouched.
256
296
  | `/compact` | summarize the conversation and replace history with the summary |
257
297
  | `/tasks` | print the current task list |
258
298
  | `/status` | version, model, account, gateway, context usage, cost, approval modes |
259
- | `/cost` | show session cost and fetch account balance |
299
+ | `/usage` | fetch plan usage |
260
300
  | `/init` | analyze the codebase and create/improve `AGENTS.md` |
301
+ | `/mcp` | manage MCP servers โ€” enable, disable, reconnect, view status & tool counts |
261
302
  | `/login` | start the browser sign-in flow |
262
303
  | `/logout` | remove the saved token |
263
304
  | `/version` | print the CLI version |
@@ -449,6 +490,316 @@ untrusted.
449
490
  **โ†’ Full reference with worked recipes for every event:
450
491
  [docs/HOOKS.md](https://github.com/MatterAIOrg/OrbCode/blob/main/docs/HOOKS.md).**
451
492
 
493
+ ## MCP servers
494
+
495
+ OrbCode connects to external tools via the **Model Context Protocol** (MCP). MCP
496
+ servers expose tools that appear alongside the native tools as
497
+ `mcp__<server>__<tool>` and can be called by the model like any other tool.
498
+
499
+ ### Configuration
500
+
501
+ MCP servers are configured in three scopes (highest precedence last):
502
+
503
+ 1. **User scope** โ€” `mcpServers` in `~/.orbcode/settings.json`. Applies to every
504
+ project on this machine.
505
+ 2. **Project scope** โ€” `.mcp.json` in the project root (and parent directories,
506
+ closer-to-cwd wins). This is the check-into-git, shared format, compatible
507
+ with Claude Code's `.mcp.json`.
508
+ 3. **Local scope** โ€” `mcpServers` in `.orbcode/settings.json`. Per-project,
509
+ per-machine overrides (not checked in).
510
+
511
+ ### Adding servers from the command line
512
+
513
+ The `orbcode mcp` subcommand manages servers without editing JSON by hand โ€”
514
+ like Claude Code's `claude mcp add/remove/list`:
515
+
516
+ ```bash
517
+ # stdio (default transport): name + command + args
518
+ orbcode mcp add filesystem npx -y @modelcontextprotocol/server-filesystem /Users/me/projects
519
+
520
+ # http transport
521
+ orbcode mcp add --transport http linear-server https://mcp.linear.app/mcp
522
+
523
+ # sse transport with a header
524
+ orbcode mcp add -t sse --header "Authorization=Bearer ${TOKEN}" my-sse https://example.com/sse
525
+
526
+ # http with OAuth (auth from /mcp after adding)
527
+ orbcode mcp add --transport http --oauth notion https://mcp.notion.com/mcp
528
+ orbcode mcp add -t http --oauth --oauth-scope "read:issues" linear https://mcp.linear.app/mcp
529
+
530
+ # stdio with env vars, written to user scope (~/.orbcode/settings.json)
531
+ orbcode mcp add -s user -e API_KEY=secret -e DEBUG=true my-server node server.js
532
+
533
+ # list all configured servers (name, scope, transport detail)
534
+ orbcode mcp list
535
+
536
+ # remove a server (finds it in whichever scope it lives)
537
+ orbcode mcp remove filesystem
538
+ ```
539
+
540
+ Flags go before the server name; everything after the name is the command +
541
+ args (so stdio servers can take their own flags like `-y`). Use `--` to force
542
+ the split if needed. `-s`/`--scope` selects `project` (default, writes
543
+ `.mcp.json`), `user` (writes `~/.orbcode/settings.json`), or `local` (writes
544
+ `.orbcode/settings.json`). Run `orbcode mcp help` for the full reference.
545
+
546
+ `add` and `remove` print the file they modified:
547
+
548
+ ```
549
+ $ orbcode mcp add --transport http linear-server https://mcp.linear.app/mcp
550
+ Added HTTP MCP server linear-server
551
+ URL: https://mcp.linear.app/mcp
552
+ Scope: project
553
+ File modified: /Users/me/my-project/.mcp.json
554
+ ```
555
+
556
+ OAuth servers show `needs-auth` after adding โ€” they don't auto-open a browser.
557
+ Open `/mcp` in the TUI, select the server, and press `a` (or `1`) to
558
+ authenticate. OrbCode shows an auth screen:
559
+
560
+ ```
561
+ Authenticating with linear-serverโ€ฆ
562
+
563
+ โœฝ A browser window will open for authentication
564
+
565
+ If your browser doesn't open automatically, copy this URL manually (c to copy)
566
+ https://mcp.linear.app/authorize?response_type=code&client_id=โ€ฆ
567
+
568
+ If the redirect page shows a connection error, paste the URL from your browser's address bar:
569
+ URL> โ–ˆ
570
+
571
+ Return here after authenticating in your browser. Press Esc to go back.
572
+ ```
573
+
574
+ The browser opens automatically to the server's OAuth authorize page (RFC 9728
575
+ discovery โ†’ PKCE โ†’ redirect to a loopback callback โ†’ token exchange). Press `c`
576
+ to copy the URL to the clipboard if the browser doesn't open. If the redirect
577
+ fails (e.g. wrong port), press enter and paste the redirect URL from the
578
+ browser's address bar โ€” OrbCode extracts the code from it. Either path
579
+ (callback or paste) completes the flow. Tokens persist under
580
+ `~/.orbcode/mcp-auth/<server>.json` (mode 0600) for future sessions; refresh
581
+ happens automatically when they expire. For M2M grants (`client_credentials`,
582
+ `private_key_jwt`), there's no browser โ€” the token exchange is direct.
583
+
584
+ `.mcp.json` format (project scope):
585
+
586
+ ```json
587
+ {
588
+ "mcpServers": {
589
+ "filesystem": {
590
+ "command": "npx",
591
+ "args": ["-y", "@modelcontextprotocol/server-filesystem", "/Users/me/projects"]
592
+ },
593
+ "github": {
594
+ "type": "http",
595
+ "url": "https://api.githubcopilot.com/mcp/",
596
+ "headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" }
597
+ }
598
+ }
599
+ }
600
+ ```
601
+
602
+ `settings.json` `mcpServers` (user/local scope) uses the same per-server shape.
603
+ Environment variables (`${VAR}`) are expanded from `process.env`.
604
+
605
+ Three server types are supported:
606
+
607
+ - **stdio** (default, omit `type`): OrbCode spawns `command` with `args` and
608
+ talks over stdin/stdout. Optional `env` and `cwd`.
609
+ - **http**: Streamable HTTP transport. `url` + optional `headers` + optional
610
+ `oauth` (see [Authentication](#mcp-authentication)).
611
+ - **sse**: Server-Sent Events (legacy remote). `url` + optional `headers` +
612
+ optional `oauth`.
613
+
614
+ ### MCP authentication
615
+
616
+ Remote servers (http/sse) often require auth. OrbCode supports three ways:
617
+
618
+ **1. Static headers** (API keys, personal access tokens). Use `headers` with
619
+ `${ENV_VAR}` expansion โ€” the token is read from the environment, never written
620
+ to disk:
621
+
622
+ ```json
623
+ {
624
+ "github": {
625
+ "type": "http",
626
+ "url": "https://api.githubcopilot.com/mcp/",
627
+ "headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" }
628
+ }
629
+ }
630
+ ```
631
+
632
+ **2. OAuth 2.0 flows** (for servers that require user login: GitHub, Google
633
+ Drive, Slack, Notion, โ€ฆ). Set `oauth: true` (or `{ "scope": "..." }`) on an
634
+ http/sse server. OrbCode runs the full authorization-code flow via the SDK:
635
+ RFC 9728 protected-resource discovery, RFC 8414 authorization-server metadata,
636
+ PKCE, dynamic client registration, and token refresh. A one-shot loopback HTTP
637
+ server receives the browser redirect. Tokens, client info, code verifiers, and
638
+ discovery state are persisted per-server under `~/.orbcode/mcp-auth/<server>.json`
639
+ (mode 0600) so re-auth is only needed when a token expires or is revoked.
640
+
641
+ ```json
642
+ {
643
+ "notion": {
644
+ "type": "http",
645
+ "url": "https://mcp.notion.com/mcp",
646
+ "oauth": true
647
+ },
648
+ "google-drive": {
649
+ "type": "http",
650
+ "url": "https://mcp.google.com/drive",
651
+ "oauth": { "scope": "https://www.googleapis.com/auth/drive.readonly" }
652
+ }
653
+ }
654
+ ```
655
+
656
+ **3. Machine-to-machine OAuth** (no browser). For service-to-service auth,
657
+ use `client_credentials` or `private_key_jwt` grants โ€” these use the SDK's
658
+ built-in `ClientCredentialsProvider` / `PrivateKeyJwtProvider`:
659
+
660
+ ```json
661
+ {
662
+ "internal-api": {
663
+ "type": "http",
664
+ "url": "https://internal.example.com/mcp",
665
+ "oauth": {
666
+ "grantType": "client_credentials",
667
+ "clientId": "orbcode-client",
668
+ "clientSecret": "${INTERNAL_CLIENT_SECRET}",
669
+ "scope": "mcp:tools"
670
+ }
671
+ },
672
+ "jwt-api": {
673
+ "type": "http",
674
+ "url": "https://jwt.example.com/mcp",
675
+ "oauth": {
676
+ "grantType": "private_key_jwt",
677
+ "clientId": "orbcode-client",
678
+ "privateKey": "${JWT_PRIVATE_KEY_PEM}",
679
+ "algorithm": "RS256"
680
+ }
681
+ }
682
+ }
683
+ ```
684
+
685
+ When a server needs auth, its status shows `needs-auth` in `/mcp`; press **a**
686
+ to re-authenticate (clears stored tokens and re-runs the flow). Secrets in
687
+ `oauth` blocks support `${ENV_VAR}` expansion like `headers`, so client
688
+ secrets and private keys can be sourced from the environment rather than
689
+ committed to `.mcp.json`.
690
+
691
+ ### Enabling & disabling servers
692
+
693
+ - **User/local-scope servers** connect automatically on startup (you wrote them,
694
+ so they're trusted).
695
+ - **Project-scope servers** (from `.mcp.json`) require a one-time approval: on
696
+ first launch in a project, OrbCode shows a checklist of detected servers.
697
+ Select the ones you trust; the decision is persisted to
698
+ `.orbcode/settings.json` (`enabledMcpServers` / `disabledMcpServers`) so they
699
+ auto-connect on future sessions.
700
+
701
+ The `/mcp` command opens an interactive manager at any time:
702
+
703
+ - โ†‘/โ†“ to select a server. The selected server shows a detail panel with
704
+ **Status**, **Auth** (authenticated / not authenticated / static headers),
705
+ **URL** (or stdio command), **Config location** (the file path), and a
706
+ numbered action list.
707
+ - **enter** or **2** toggles enable/disable. **r** or **3** reconnects. **a**
708
+ or **1** authenticates a `needs-auth` OAuth server (opens a browser for the
709
+ authorization-code flow; M2M grants exchange directly). **esc** closes.
710
+ - Each server shows a live status icon: `โœ“ connected`, `โ–ณ needs-auth`,
711
+ `โœ— failed`, `โ—‹ disabled`, `โ‹ฏ connecting`, plus a tool count when connected.
712
+ - Enable/disable choices are persisted per-project. OAuth tokens are persisted
713
+ per-server under `~/.orbcode/mcp-auth/`.
714
+
715
+ ### Headless mode
716
+
717
+ In `orbcode -p`, there's no interactive approval, so project-scope servers are
718
+ only connected if they were previously approved (via an interactive `/mcp`
719
+ session). Unapproved project servers are skipped with a stderr note. User/local
720
+ servers connect as usual.
721
+
722
+ ## Skills
723
+
724
+ Skills are reusable instruction sets the model can load on demand. A skill is a
725
+ directory containing a `SKILL.md` file with optional YAML frontmatter and a
726
+ markdown body of specialized instructions.
727
+
728
+ ### Creating a skill
729
+
730
+ Place a directory under `~/.orbcode/skills/` (user, applies everywhere) or
731
+ `.orbcode/skills/` (project, checked into the repo):
732
+
733
+ ```
734
+ ~/.orbcode/skills/
735
+ my-skill/
736
+ SKILL.md
737
+ ```
738
+
739
+ `SKILL.md` format:
740
+
741
+ ```markdown
742
+ ---
743
+ description: Write concise, idiomatic Go code following project conventions
744
+ when_to_use: the task involves writing or reviewing Go code
745
+ ---
746
+
747
+ # Go style skill
748
+
749
+ When writing Go in this project:
750
+ - Use `errors.Join` for multi-error aggregation
751
+ - Prefer table-driven tests
752
+ - ...
753
+ ```
754
+
755
+ - `description` (frontmatter or first paragraph): shown in the skill catalog.
756
+ - `when_to_use` (frontmatter): a hint telling the model when to invoke this skill.
757
+ - `${SKILL_DIR}` in the body is replaced with the skill's absolute directory
758
+ path, so you can reference bundled scripts.
759
+
760
+ ### How skills are used
761
+
762
+ The skill catalog (names + descriptions + when-to-use) is injected into the
763
+ system prompt. When a task matches a skill's `when_to_use` condition, the model
764
+ calls the `use_skill` tool with the skill's name, which loads the full
765
+ instructions into context. Project skills override user skills on name
766
+ collisions (closer-to-cwd wins).
767
+
768
+ ## AGENTS.md memory
769
+
770
+ AGENTS.md files provide project- and user-level instructions that are injected
771
+ into every system prompt โ€” build commands, code style, architecture notes,
772
+ conventions. This is OrbCode's equivalent of Claude Code's `CLAUDE.md`, using
773
+ the open `AGENTS.md` filename so it works across tools.
774
+
775
+ ### Discovery
776
+
777
+ Files are loaded in this order (lowest precedence first; higher-precedence files
778
+ appear later and get more weight):
779
+
780
+ 1. **User memory**: `~/.orbcode/AGENTS.md` โ€” personal global instructions.
781
+ 2. **Project memory**: `AGENTS.md` and `.orbcode/AGENTS.md` in the cwd and every
782
+ parent directory (closer-to-cwd wins). Checked into the repo, shared with the
783
+ team.
784
+ 3. **Local memory**: `AGENTS.local.md` in the cwd and parents โ€” private
785
+ per-machine overrides (gitignore this).
786
+
787
+ ### @include directives
788
+
789
+ An AGENTS.md file can include other files with `@path` references:
790
+
791
+ ```markdown
792
+ # Project guide
793
+
794
+ See the detailed style guide: @./docs/style.md
795
+ And the global one: @~/orbcode-global.md
796
+ ```
797
+
798
+ `@path` (relative to the including file), `@./path`, `@~/path`, and `@/abs/path`
799
+ are all supported. Includes are resolved recursively (up to 5 levels, with cycle
800
+ detection). Use `/init` to have OrbCode generate a starter `AGENTS.md` by
801
+ analyzing the codebase.
802
+
452
803
  ## Architecture
453
804
 
454
805
  ```
@@ -465,23 +816,50 @@ src/
465
816
  stream.ts chunk model: text / reasoning / native_tool_calls / usage
466
817
  headers.ts X-AxonCode-Version, X-AxonCode-TaskId, X-AXON-REPO, โ€ฆ
467
818
  prompts/system.ts system prompt: agent roleDefinition + tool guide (ported
468
- verbatim from the extension) + CLI system-info section
819
+ verbatim from the extension) + CLI system-info section +
820
+ AGENTS.md memory + skills catalog injection
469
821
  tools/
470
822
  schemas/ native-tools JSON schemas, copied verbatim from the extension
471
- executors/ CLI implementations (fs, child_process, search, web)
472
- index.ts dispatch, approval classification, call summaries
823
+ executors/ CLI implementations (fs, child_process, search, web, skills)
824
+ index.ts dispatch, approval classification, call summaries, MCP routing
473
825
  core/
474
- agent.ts the agent loop (see below)
826
+ agent.ts the agent loop (see below); owns the McpManager
475
827
  events.ts AgentEvent model consumed by the UI
476
828
  hooks.ts lifecycle hooks engine, Claude-Code compatible (see Hooks)
829
+ mcp/
830
+ types.ts MCP server config + connection state types
831
+ config.ts .mcp.json + settings.json mcpServers loader (3-scope merge)
832
+ client.ts SDK transport (stdio/http/sse) + tool enum + tool call
833
+ manager.ts McpManager: connection lifecycle, enable/disable, tool routing
834
+ skills/
835
+ types.ts Skill + frontmatter types
836
+ loader.ts ~/.orbcode/skills + .orbcode/skills discovery (SKILL.md format)
837
+ memory/
838
+ types.ts MemoryFile type
839
+ loader.ts AGENTS.md discovery (user/project/local) + @include resolution
477
840
  ui/
478
841
  App.tsx main Ink app: static finalized rows + dynamic streaming area
479
842
  LoginView.tsx device-flow login screen with paste fallback
480
843
  components/ Header, InputBox, rows, ApprovalPrompt, FollowupPrompt,
481
- Spinner, StatusBar
844
+ HookTrustPrompt, McpApprovalPrompt, McpPicker, ModelPicker,
845
+ SessionPicker, Spinner, StatusBar
482
846
  markdown.ts markdown โ†’ ANSI renderer
483
847
  ```
484
848
 
849
+ **MCP integration**: the `McpManager` (owned by the agent) loads the merged
850
+ config on `start()`, connects to approved servers in parallel, and exposes
851
+ their tools as `mcp__<server>__<tool>` definitions alongside the native tools.
852
+ The agent routes any `mcp__*` tool call to the manager, which dispatches it to
853
+ the right SDK client. Project-scope servers (from `.mcp.json`) require a
854
+ one-time approval; the TUI shows a checklist at startup and `/mcp` manages them
855
+ at runtime. Connections are torn down on session end.
856
+
857
+ **Skills & memory**: on agent construction, `loadMemoryFiles()` walks the
858
+ AGENTS.md discovery chain (user โ†’ project โ†’ local, with `@include` resolution)
859
+ and `loadSkills()` walks the skills directories. Both are injected into the
860
+ system prompt so the model sees project instructions and the skill catalog on
861
+ every turn. The `use_skill` tool loads a skill's full body on demand.
862
+
485
863
  **Streaming** faithfully ports the extension's handler quirks: cumulative
486
864
  content dedup (some backends re-send full content), `<think>` blocks routed to
487
865
  reasoning, both `reasoning` and `reasoning_content` delta fields, tool-call
@@ -498,7 +876,7 @@ extension). It shows in the status bar, is written into the session file (so
498
876
  `/resume` lists real titles), and becomes the terminal window title:
499
877
  `<title> (orbcode)`.
500
878
 
501
- **Usage data**: `/status` and `/cost` fetch `/axoncode/profile` and show the
879
+ **Usage data**: `/status` and `/usage` fetch `/axoncode/profile` and show the
502
880
  plan, usage percentage (used/remaining), remaining reviews, and the credits
503
881
  reset date โ€” the same data as the extension's profile view.
504
882
 
@@ -517,11 +895,13 @@ Active in the CLI (schemas byte-identical to the extension's `native-tools`):
517
895
  | `execute_command` | user's shell, 120s timeout, 30k output cap, optional cwd |
518
896
  | `web_search` / `web_fetch` | proxied through the MatterAI backend with your token |
519
897
  | `update_todo_list` | drives the TUI todo panel |
898
+ | `use_skill` | loads a skill's full instructions from ~/.orbcode/skills or .orbcode/skills |
520
899
  | `ask_followup_question` | interactive menu in the TUI |
521
900
  | `attempt_completion` | ends the turn with a completion card |
901
+ | `mcp__<server>__<tool>` | any tool exposed by a connected MCP server (see [MCP servers](#mcp-servers)) |
522
902
 
523
903
  Present in `tools/schemas/` but **inactive** (need IDE services): `codebase_search`,
524
- `lsp`, `list_code_definition_names`, `use_skill`, `check_past_chat_memories`,
904
+ `lsp`, `list_code_definition_names`, `check_past_chat_memories`,
525
905
  `browser_action`, `generate_image`, `new_task`, `switch_mode`,
526
906
  `fetch_instructions`, `run_slash_command`.
527
907
 
@@ -601,6 +981,13 @@ node test-device-auth.mjs # device-auth polling flow against a local mock
601
981
  iTerm) keep working. A normal global install (`npm install -g @matterailab/orbcode`) is
602
982
  unaffected because it lives outside protected folders.
603
983
 
984
+ ## Documentation
985
+
986
+ The README covers the essentials. For the complete, kept-up-to-date reference
987
+ (guides, configuration, hooks cookbook, troubleshooting), visit the docs site:
988
+
989
+ **๐Ÿ‘‰ <https://docs.matterai.so/orbcode-cli/overview>**
990
+
604
991
  ## Contributing
605
992
 
606
993
  Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for how to
@@ -87,8 +87,14 @@ export const ANTHROPIC_MODELS = {
87
87
  provider: "anthropic",
88
88
  },
89
89
  };
90
- export const AXON_MODELS = {
91
- ...ANTHROPIC_MODELS,
90
+ /**
91
+ * Axon's own models (MatterAI gateway). These are the only models shown in
92
+ * the TUI's `/model` picker and are the supported defaults. Third-party
93
+ * providers (Anthropic, OpenAI-compatible) are registered under
94
+ * `AXON_MODELS` for `-p --model` runs but are intentionally hidden from the
95
+ * interactive picker for now.
96
+ */
97
+ export const BUILTIN_AXON_MODELS = {
92
98
  "axon-code-2-5-mini": {
93
99
  id: "axon-code-2-5-mini",
94
100
  name: "Axon Code 2.5 Mini (free)",
@@ -134,7 +140,17 @@ export const AXON_MODELS = {
134
140
  free: false,
135
141
  },
136
142
  };
137
- export const DEFAULT_MODEL_ID = "axon-code-2-5-pro";
143
+ /**
144
+ * Full model registry, including third-party providers. The TUI picker uses
145
+ * `BUILTIN_AXON_MODELS`; non-interactive `-p --model` runs resolve through
146
+ * this map, so a custom 3P entry (e.g. `claude-opus-4-8` from settings.json)
147
+ * still works headlessly.
148
+ */
149
+ export const AXON_MODELS = {
150
+ ...BUILTIN_AXON_MODELS,
151
+ ...ANTHROPIC_MODELS,
152
+ };
153
+ export const DEFAULT_MODEL_ID = "axon-eido-3-code-mini";
138
154
  /** Add user-defined models (from settings.json) to the registry. */
139
155
  export function registerCustomModels(models) {
140
156
  for (const model of models) {