@matterailab/orbcode 0.2.1 → 0.2.2

package/README.md

@@ -1,7 +1,17 @@
 # OrbCode CLI
 
+[![npm version](https://img.shields.io/npm/v/@matterailab/orbcode?color=blue&logo=npm)](https://www.npmjs.com/package/@matterailab/orbcode)
+[![npm downloads](https://img.shields.io/npm/dm/@matterailab/orbcode?logo=npm)](https://www.npmjs.com/package/@matterailab/orbcode)
+[![license](https://img.shields.io/npm/l/@matterailab/orbcode?color=green)](./LICENSE)
+[![node](https://img.shields.io/node/v/@matterailab/orbcode?color=green&logo=node.js)](https://nodejs.org)
+[![github stars](https://img.shields.io/github/stars/MatterAIOrg/OrbCode?style=social&logo=github)](https://github.com/MatterAIOrg/OrbCode)
+[![github issues](https://img.shields.io/github/issues/MatterAIOrg/OrbCode?logo=github)](https://github.com/MatterAIOrg/OrbCode/issues)
+[![docs](https://img.shields.io/badge/docs-docs.matterai.so-purple)](https://docs.matterai.so/orbcode-cli/overview)
+
 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
@@ -13,6 +23,7 @@ activity rows, edit/command approvals, and todo tracking.
 
 ## Table of contents
 
+- [Quick start](#quick-start)
 - [Install](#install)
 - [Updating / relinking](#updating--relinking)
 - [Usage](#usage)
@@ -31,11 +42,30 @@ activity rows, edit/command approvals, and todo tracking.
 - [Development](#development)
 - [Tests](#tests)
 - [Troubleshooting](#troubleshooting)
+- [Documentation](#documentation)
 - [Contributing](#contributing)
 - [License](#license)
 
 ---
 
+## Quick start
+
+```bash
+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](https://docs.matterai.so/orbcode-cli/overview)
+or jump to [Usage](#usage).
+
+Prefer not to install globally? Run it on the fly:
+
+```bash
+npx @matterailab/orbcode
+```
+
 ## Install
 
 Requires **Node.js >= 20**.
@@ -143,18 +173,20 @@ Sign out with `/logout` (removes the saved token).
 
 ## Models
 
-The two Axon models are built in; `/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.
+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.
 
-| id                     | context | max output | pricing            |
-| ---------------------- | ------- | ---------- | ------------------ |
-| `axon-eido-3-code-pro` | 400k    | 64k        | $3/M in · $9/M out |
-| `axon-code-2-5-pro`    | 400k    | 64k        | $2/M in · $6/M out |
-| `axon-code-2-5-mini`   | 400k    | 64k        | free               |
+| id                        | context | max output | pricing                |
+| ------------------------- | ------- | ---------- | ---------------------- |
+| `axon-eido-3-code-pro`    | 400k    | 64k        | $3/M in · $9/M out     |
+| `axon-eido-3-code-mini`   | 400k    | 64k        | $1.5/M in · $4.5/M out |
+| `axon-code-2-5-pro`       | 400k    | 64k        | $2/M in · $6/M out     |
+| `axon-code-2-5-mini`      | 400k    | 64k        | free                   |
 
-`axon-code-2-5-pro` 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
+`axon-eido-3-code-mini` is the default. All four 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)
@@ -199,6 +231,11 @@ MatterAI login.
 - `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.
 
@@ -601,6 +638,13 @@ node test-device-auth.mjs  # device-auth polling flow against a local mock
   iTerm) keep working. A normal global install (`npm install -g @matterailab/orbcode`) is
   unaffected because it lives outside protected folders.
 
+## Documentation
+
+The README covers the essentials. For the complete, kept-up-to-date reference
+(guides, configuration, hooks cookbook, troubleshooting), visit the docs site:
+
+**👉 <https://docs.matterai.so/orbcode-cli/overview>**
+
 ## Contributing
 
 Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for how to

package/dist/api/models.js

@@ -87,8 +87,14 @@ export const ANTHROPIC_MODELS = {
         provider: "anthropic",
     },
 };
-export const AXON_MODELS = {
-    ...ANTHROPIC_MODELS,
+/**
+ * Axon's own models (MatterAI gateway). These are the only models shown in
+ * the TUI's `/model` picker and are the supported defaults. Third-party
+ * providers (Anthropic, OpenAI-compatible) are registered under
+ * `AXON_MODELS` for `-p --model` runs but are intentionally hidden from the
+ * interactive picker for now.
+ */
+export const BUILTIN_AXON_MODELS = {
     "axon-code-2-5-mini": {
         id: "axon-code-2-5-mini",
         name: "Axon Code 2.5 Mini (free)",
@@ -134,7 +140,17 @@ export const AXON_MODELS = {
         free: false,
     },
 };
-export const DEFAULT_MODEL_ID = "axon-code-2-5-pro";
+/**
+ * Full model registry, including third-party providers. The TUI picker uses
+ * `BUILTIN_AXON_MODELS`; non-interactive `-p --model` runs resolve through
+ * this map, so a custom 3P entry (e.g. `claude-opus-4-8` from settings.json)
+ * still works headlessly.
+ */
+export const AXON_MODELS = {
+    ...BUILTIN_AXON_MODELS,
+    ...ANTHROPIC_MODELS,
+};
+export const DEFAULT_MODEL_ID = "axon-eido-3-code-mini";
 /** Add user-defined models (from settings.json) to the registry. */
 export function registerCustomModels(models) {
     for (const model of models) {

package/dist/ui/App.js

@@ -3,7 +3,7 @@ import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { Box, Static, Text, useApp, useInput } from "ink";
 import open from "open";
 import { COLORS, VERSION } from "../branding.js";
-import { AXON_MODELS, getModel, isValidAxonModel } from "../api/models.js";
+import { BUILTIN_AXON_MODELS, getModel, isValidAxonModel } from "../api/models.js";
 import { LoginView } from "./LoginView.js";
 import { APP_URL, fetchBalance, fetchProfile, fetchTaskTitle } from "../auth/auth.js";
 import { getAuthToken, getPendingProjectHooks, loadSettings, saveSettings, trustProjectHooks, } from "../config/settings.js";
@@ -444,15 +444,26 @@ export function App({ initialView, initialPrompt, initialSession, updateCheck, }
                 });
                 break;
             case "/model": {
-                const ids = Object.keys(AXON_MODELS);
-                if (arg && isValidAxonModel(arg)) {
+                // The interactive picker is restricted to Axon's own models for now.
+                // Third-party providers (Anthropic, OpenAI-compatible) are still
+                // usable headlessly via `orbcode -p "..." --model <id>` — see
+                // the README "Other providers" section.
+                const pickerIds = Object.keys(BUILTIN_AXON_MODELS);
+                if (arg && pickerIds.includes(arg)) {
                     switchModel(arg);
                 }
+                else if (arg && isValidAxonModel(arg)) {
+                    // Recognized id, but it's a third-party model: not selectable in the TUI.
+                    pushRow({
+                        kind: "info",
+                        text: `Model "${arg}" is only available in non-interactive mode. Run: orbcode -p "..." --model ${arg}`,
+                    });
+                }
                 else if (arg) {
                     // Allow short suffixes like "pro" or "mini" to resolve to the
                     // latest matching registered id, so /model pro keeps working
                     // as new model generations are added.
-                    const matches = ids
+                    const matches = pickerIds
                         .filter((id) => id.endsWith(`-${arg}`))
                         .sort()
                         .reverse();
@@ -460,7 +471,7 @@ export function App({ initialView, initialPrompt, initialSession, updateCheck, }
                         switchModel(matches[0]);
                     }
                     else {
-                        pushRow({ kind: "error", text: `Unknown model "${arg}". Available: ${ids.join(", ")}` });
+                        pushRow({ kind: "error", text: `Unknown model "${arg}". Available: ${pickerIds.join(", ")}` });
                     }
                 }
                 else {

package/dist/ui/components/ModelPicker.js

@@ -2,7 +2,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { useState } from "react";
 import { Box, Text, useInput } from "ink";
 import { COLORS } from "../../branding.js";
-import { AXON_MODELS } from "../../api/models.js";
+import { BUILTIN_AXON_MODELS } from "../../api/models.js";
 const VISIBLE_ROWS = 6;
 function formatPrice(model) {
     if (model.free)
@@ -11,7 +11,7 @@ function formatPrice(model) {
     return `${perMillion(model.inputPrice)} in / ${perMillion(model.outputPrice)} out per 1M tokens`;
 }
 export function ModelPicker({ currentId, onSelect, onCancel }) {
-    const models = Object.values(AXON_MODELS);
+    const models = Object.values(BUILTIN_AXON_MODELS);
     const [selected, setSelected] = useState(() => {
         const index = models.findIndex((m) => m.id === currentId);
         return index === -1 ? 0 : index;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matterailab/orbcode",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "OrbCode CLI — agentic coding in your terminal, powered by Axon models by MatterAI",
   "type": "module",
   "bin": {