@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 +405 -18
- package/dist/api/models.js +19 -3
- package/dist/commands/mcp.js +266 -0
- package/dist/config/settings.js +27 -0
- package/dist/core/agent.js +28 -7
- package/dist/headless.js +18 -0
- package/dist/index.js +9 -0
- package/dist/mcp/auth.js +289 -0
- package/dist/mcp/client.js +132 -0
- package/dist/mcp/config.js +270 -0
- package/dist/mcp/manager.js +277 -0
- package/dist/mcp/types.js +8 -0
- package/dist/memory/loader.js +167 -0
- package/dist/memory/types.js +1 -0
- package/dist/prompts/system.js +26 -7
- package/dist/skills/loader.js +132 -0
- package/dist/skills/types.js +1 -0
- package/dist/tools/executors/skills.js +28 -0
- package/dist/tools/index.js +22 -3
- package/dist/tools/schemas/index.js +6 -3
- package/dist/tools/schemas/use_skill.js +1 -1
- package/dist/ui/App.js +219 -53
- package/dist/ui/components/McpApprovalPrompt.js +61 -0
- package/dist/ui/components/McpAuthScreen.js +55 -0
- package/dist/ui/components/McpPicker.js +262 -0
- package/dist/ui/components/ModelPicker.js +2 -2
- package/dist/ui/components/StatusBar.js +28 -9
- package/dist/utils/clipboard.js +45 -0
- package/package.json +2 -1
package/README.md
CHANGED
|
@@ -1,7 +1,17 @@
|
|
|
1
1
|
# OrbCode CLI
|
|
2
2
|
|
|
3
|
+
[](https://www.npmjs.com/package/@matterailab/orbcode)
|
|
4
|
+
[](https://www.npmjs.com/package/@matterailab/orbcode)
|
|
5
|
+
[](./LICENSE)
|
|
6
|
+
[](https://nodejs.org)
|
|
7
|
+
[](https://github.com/MatterAIOrg/OrbCode)
|
|
8
|
+
[](https://github.com/MatterAIOrg/OrbCode/issues)
|
|
9
|
+
[](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
|
|
147
|
-
(`/model <id>` still selects directly). Additional models can be
|
|
148
|
-
`customModels` in settings.json. The choice persists across
|
|
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
|
|
151
|
-
|
|
|
152
|
-
| `axon-eido-3-code-pro`
|
|
153
|
-
| `axon-
|
|
154
|
-
| `axon-code-2-5-
|
|
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-
|
|
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
|
-
| `/
|
|
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
|
-
|
|
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 `/
|
|
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`, `
|
|
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
|
package/dist/api/models.js
CHANGED
|
@@ -87,8 +87,14 @@ export const ANTHROPIC_MODELS = {
|
|
|
87
87
|
provider: "anthropic",
|
|
88
88
|
},
|
|
89
89
|
};
|
|
90
|
-
|
|
91
|
-
|
|
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
|
-
|
|
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) {
|