archymedes-cli 3.5.1 → 3.7.0

package/README.md

@@ -1,336 +1,161 @@
 # archymedes
 
-A coding agent that runs in your terminal — against your working tree, or inside an isolated remote sandbox when the work shouldn't touch your machine.
+A coding agent for your terminal. It reads, searches, edits and runs commands in a real project,
+asks before it changes anything you have not allowed, keeps a checkpoint before every turn, and
+says what each request cost. It works with the model you choose: your own API key for any of ten
+providers, free models through OpenRouter, your Claude subscription through your own Claude Code, or
+your ChatGPT plan through your own Codex.
 
 ```bash
 npm install -g archymedes-cli
-archymedes "fix the failing test in src/parser.ts"
+archymedes                                   # the interface
+archymedes "fix the failing test in src/parser.ts"   # one request, then exit
 ```
 
-## What it does
-
-Archymedes reads, searches, edits and runs commands in a real project, then reports what actually happened. It guards effectful work according to the selected mode, snapshots the workspace so you can undo a turn, and tells you what each request cost.
-
-```
-archymedes                        Interactive session
-archymedes "add a health check"   One request, then exit
-archymedes --plan                 Read and reason only — the write tools aren't loaded
-archymedes --auto                 Auto-apply ordinary edits; sensitive actions still ask
-archymedes --defender             Security review — find and fix real issues; every change still asks
-archymedes --allow-sensitive      Approve a flagged task preflight; tool guards remain active
-archymedes --sandbox              Work in a remote sandbox; your files are never touched
-archymedes --resume               Continue the last session
-archymedes history                Browse past sessions without starting a model
-archymedes history search "text"  Search indexed snapshot and journal evidence
-archymedes history status         Show native-index or portable-fallback status
-archymedes --providers            Show which model providers are configured
-archymedes --location EG          Use the country's local currency (locale-detected by default)
-archymedes --currency EGP         Override with any supported ISO currency
-archymedes --budget 500           Approve and enforce a session spend cap in that currency
-archymedes --estimate "task"      Forecast input/output tokens and cost without calling a model
-archymedes settings               Configure keys, URLs, models, pricing, language and voice
-archymedes --language ar          Localize controls (also: en zh hi es fr bn pt ru ur)
-archymedes acp                    Speak the Agent Client Protocol on stdio, for an editor
-archymedes update                 Check and install the latest published CLI
-archymedes update --check         Check without changing the installed version
-```
-
-With a CircuitNotion key, Archymedes defaults to `circuit-2-turbo`. `/models refresh` asks configured
-providers for their current catalog; ordinary `/models` uses the cache so opening a menu does not
-wait on the network. Slash commands belong inside an interactive session. Passing one as a one-shot
-objective is rejected before model contact, preventing an invocation mistake from becoming a paid
-prompt.
-
-In a session: `/mode` shows the current permission posture, `/mode plan|build|auto|defender` switches it, and `/plan` `/build` `/auto` `/defender` remain quick shortcuts. Defender mode turns Archymedes into a security reviewer — the full tool set to actually run a scanner (including a built-in `scan_secrets` that matches likely credentials by pattern and always masks what it finds) and propose a fix, gated exactly like build so nothing is ever auto-approved. It works from a bundled, OWASP-2025-aligned set of playbooks: access control, security misconfiguration, software supply chain & CI/CD integrity, injection, client-side & browser security, auth/session handling, API security, SSRF, secrets, dependency risk, cryptography misuse, IaC/container hardening, exceptional-condition handling, business logic & race conditions, fuzzing and invariant-based testing, logging/monitoring/deterrence, and LLM/AI application security. `/undo` reverts the last turn, `/cost` shows the breakdown — totals, a table of every turn's tokens, tools, seconds and spend, and the shape of it as charts — `/pull` copies sandbox work back to disk, `/settings` opens configuration, `/voice` records a prompt, and `/keys` shows keyboard controls.
-
-## Setup
-
-Archymedes needs one model provider. It uses the one you last switched to, or the first one configured, unless `--provider` says otherwise.
-
-The easiest interactive setup is:
-
-```bash
-archymedes settings
-```
-
-The menu is navigable with the arrow keys — Up/Down, PageUp/PageDown, Home/End — and Enter opens the highlighted setting. Values with a knowable set of answers (location, language, display currency, default provider) are picked from a list rather than typed, so choosing Rwanda does not require knowing it is `RW`, and each country shows the currency it selects. Typing letters filters a long list. Every row is still numbered and a typed number still jumps to it, which is the path that works with a screen reader; piped and scripted runs keep the plain numbered menu.
-
-Settings use the native per-user config directory on Windows, macOS, and Linux. Secret values are masked in the menu and the file is written with user-only permissions where the operating system supports POSIX modes. Environment variables always override saved settings, which keeps CI and one-off shell configuration predictable.
-
-```bash
-export ANTHROPIC_API_KEY=...        # or OPENAI_API_KEY, or CIRCUITNOTION_API_KEY
-archymedes --providers                    # shows exactly what's set and what's missing
-```
-
-Anthropic models are priced in this build, so costs are reported without further setup. For any other model, set its published rate — otherwise Archymedes reports `cost unknown` rather than inventing a number:
-
-```bash
-export MODEL_INPUT_PER_MILLION=1.5      # per million tokens, in MODEL_PRICE_CURRENCY (default USD)
-export MODEL_OUTPUT_PER_MILLION=6
-export ARCHYMEDES_COUNTRY=RW                  # optional; otherwise LANG/LC_MONETARY is used
-export ARCHYMEDES_CURRENCY=RWF                # optional manual override; any supported ISO currency
-# Both are also in `archymedes settings`, where changing your location takes effect immediately
-export ARCHYMEDES_FX_RWF_PER_USD=1320         # required to show USD-priced models in RWF
-# Generic offline/manual pair: ARCHYMEDES_FX_FROM=USD ARCHYMEDES_FX_TO=EGP ARCHYMEDES_FX_RATE=48.5
-```
-
-Remote sandboxes additionally need `E2B_API_KEY`.
-
-Optional web search uses Exa. Add `EXA_API_KEY` through `archymedes settings` or your environment; `/providers` then reports `Exa search · web_search enabled`, and the agent receives a bounded highlights-only `web_search` tool. `EXA_BASE_URL` supports an Exa-compatible gateway without changing the tool contract.
-
-## Updating Archymedes
-
-Archymedes updates its global installation automatically by default in an interactive terminal. Once a day at startup it checks the public registry, pins the exact version it found, and installs it through npm, pnpm, Yarn, or Bun without another acceptance prompt. The running session remains on its starting version until restart. Piped/headless runs and CI never check or install. Use `/update check` for notification-only behavior or `/update off` to disable checks:
-
-```bash
-archymedes update
-archymedes --update
-archymedes update --check
-archymedes update --yes
-archymedes update --package-manager pnpm
-archymedes --version
-```
-
-Manual `archymedes update` still asks before installing; use `--yes` for an explicitly unattended manual update. Set `ARCHYMEDES_UPDATE_PACKAGE_MANAGER` to choose a persistent package-manager override.
-
-## How it behaves
-
-**Plan mode cannot write.** The write and command tools are not offered to the model at all — it's a capability boundary, not an instruction.
-
-**Approvals start with a consequence-based safety preflight.** Before estimation or model contact, build and auto modes detect credential disclosure or high-impact credential lifecycle changes, destructive data operations, production releases, financial transactions, private-data export, external publication, or weakened access controls. Interactive runs ask whether to continue; unattended runs fail closed unless the operator explicitly passes `--allow-sensitive`. Merely reading a project-local `.env`, inspecting a project-owned environment variable, or configuring a local token the user intentionally supplied is ordinary development work and does not trip this task-level gate.
-
-**Auto approval is guarded.** Auto mode skips prompts only for ordinary workspace-local edits and commands. It inspects the exact proposed command, file path, and new content first. Local secret reads such as `cat .env` may run, but credential-file writes, secret-like new content, likely credential transmission, production configuration, destructive or privileged commands, deploys, package publication, pushes, and network mutations still require a separate tool approval. Archymedes may use a pasted secret for the task the user named, but is instructed not to repeat it in prose, logs, summaries, examples, commits, or unrelated files, and never to send it to an unnamed external destination. `--allow-sensitive` acknowledges the task preflight; it never bypasses these operation-level gates. Build mode continues to ask for every effectful call. Decisions use `[y]es / [n]o / [a]lways / [d]eny always` and are remembered only for the exact action.
-
-**Locally, an approved command runs as you.** This is the part worth being plain about: on your own machine there is no sandbox around `run_command`. Once you approve it, it has exactly the authority your shell has — it can read and write files outside the project and reach the network. Archymedes narrows *what gets proposed* (plan mode cannot run commands at all, a small set are refused outright, and auto mode still stops for anything sensitive), and Archymedes contains the process *tree* on Linux so a cancelled or timed-out command cannot leave background processes behind. Neither of those is a security boundary. The approval prompt is the boundary, which is why it shows the exact command and why a tool that did not ship with Archymedes always says where it came from. When you need a real one, `--sandbox` and `--sandbox docker` put the work inside a container.
-
-**Spending is bounded before work starts.** `--budget N` is expressed in the selected local currency. In an interactive session Archymedes confirms that cap before starting a sandbox or calling a model; in a one-shot command the explicit flag is the approval. If the required FX rate is unavailable, Archymedes refuses to pretend it can enforce a converted cap.
-
-**Switching models is a menu, not a lookup.** `/model` opens a picker: arrow to a model and press Enter, with each one's price beside it and the cursor starting on the one in use. Press `t` and the same models become a table — input and output price in columns of their own, `←`/`→` to aim at a column and `s` to order by it, so "which of these is cheapest" is a keystroke rather than a read-through. Each row keeps the number `/model <n>` takes, so sorting never renumbers anything; `Esc` returns to the menu, and Enter switches from either view. Providers you have no key for are rows you can select, and selecting one opens settings — so a missing key is something you fix from where you noticed it. Typed forms skip the menu entirely: `/model opus` matches on any part of a model id and says which candidates it meant if the name is ambiguous. The transcript carries across the switch, and your choice is remembered for the next launch.
-
-**Large output leaves the conversation instead of being cut off.** A tool result too big for the transcript is written to `.archymedes/artifacts/`, and the model receives the beginning, the end, and the path. The end is the half that matters — a failing test says what failed on its last line — and the rest stays reachable through `read_file` with an offset, so nothing is lost to make room. Artifacts are content-addressed, so the same output repeated three times is one file.
-
-**Compaction happens at a boundary, and cannot quietly drop the rules.** Past 70% of the context window Archymedes summarizes as soon as the work reaches a clean stopping point; past 90% it summarizes regardless. A summary is lossy by design, so the governing facts are never left inside one: the permission mode, the original request, every action you approved or refused, and the plan's open items are re-derived from live state at each compaction and restated verbatim above the summary. A constraint that survives only as a sentence in a summary is a constraint that stops existing a few compactions later.
-
-**Undo is real.** Each turn snapshots the workspace into a private git index. `/undo` reverts modified files *and* removes files the agent created, without touching your staged changes.
-
-**Verification is required.** An agent that changes files and then declares success without running anything is reported as `needs_verification`, not `completed`.
-
-Passing targeted tests finish a focused change. Archymedes does not automatically pay another model
-round to demand new property tests and an assembled-app smoke test after every small fix; when no
-verification ran, it asks once for the smallest relevant existing check. If a model names a tool
-the current mode does not expose, the runtime returns that fact once so Plan mode can recover with
-a useful answer, then fails closed if the model repeats it.
-
-**Paying happens on the provider's page, never in the terminal.** `/pay 5000` tops up your Archymedes credit: Archymedes creates a checkout, shows the link, a short code and a reference, and waits. Your card, PIN and mobile-money confirmation are entered on Circuit Pay's own page — Archymedes never sees them and never asks. Nothing is created until you answer the confirmation, amounts are whole RWF (a decimal is refused, not rounded), and every attempt carries an idempotency key so a retried request cannot become a second charge. Ctrl+C stops waiting without cancelling the payment; if it is still unconfirmed, Archymedes says so and keeps the reference for `/pay status <ref>` rather than calling it failed. `/pay` on its own shows the gateway balance. If that endpoint is unavailable, `/balance 5000` stores the balance the user sees in their account and bypasses the endpoint; Archymedes labels it as locally estimated and subtracts measured token costs after every completed turn. `/balance clear` returns to the endpoint. Both sources power the low/critical alerts and pre-turn affordability check, but only an endpoint reading is called confirmed. Archymedes never tops up automatically.
-
-**Costs are honest.** Sub-cent amounts display as `$0.0034` rather than `$0.00`, converted amounts name the daily rate and its date, and an unpriced model says so instead of showing zero. Automatic conversion uses the keyless daily [exchange-api](https://github.com/fawazahmed0/exchange-api) endpoints with their fallback host; set `ARCHYMEDES_FX_OFFLINE=true` to disable lookup.
-
-**Estimates are token-based.** Before a turn, Archymedes counts the actual system prompt, conversation history, objective, and tool schemas, then forecasts cumulative input growth across the expected agent loop. `archymedes --estimate "task"` performs that preflight without starting a sandbox or calling a model. Provider-reported usage remains the final accounting truth.
-
-## Memory and recall
-
-Archymedes keeps durable memory in plain markdown you can inspect, commit, edit, or delete: project knowledge lives in `.archymedes/memory.md`; personal preferences live beside your Archymedes settings. `# we use bun, not npm` records a project fact. `/memory` shows both stores and their budgets.
-
-Memory is deliberately smaller than history. Core facts marked with `--core` are always recalled; everything else is selected locally for the current request by matching repository names, commands, files, and domain terms. Already-recalled entries are not sent again in the same thread. This keeps prompt cost bounded without an embedding service or sending memory to another provider.
-
-```text
-/memory add --kind convention we use bun, not npm
-/memory add --core --user --kind preference keep explanations concise
-/memory replace use bun => use bun 1.3 and never npm
-/memory recall package scripts
-/memory forget 2
-```
-
-Kinds are `preference`, `convention`, `decision`, `lesson`, and `fact`. Memory writes reject invisible formatting and instruction-shaped injection content. A unique text fragment can replace an entry, avoiding fragile row numbers when correcting knowledge. `/history search <text>` uses the local native SQLite + FTS5 index when its platform package is installed, returning ranked snapshot or journal evidence with context. It falls back automatically to verified session JSON when the native engine is unavailable. `/history status` shows which path is active. This is the larger episodic layer for details that do not deserve permanent prompt space.
-
-`/history resume` opens a searchable conversation chooser and works across processes. The saved
-permission mode returns with the transcript, while an explicit startup flag such as
-`archymedes --auto --resume …` deliberately overrides it. Archymedes's verification nudges are internal: they
-are neither counted as user turns nor indexed as things you said.
-
-Defender mode has a second, security-only memory layer. `query_defensive_brain` searches Archymedes's
-native Rust + SQLite FTS5 index and returns only a few reviewed records with confidence, review and
-expiry dates, and primary-source provenance. The reviewed corpus covers red teaming, vulnerability
-assessment and safe impact validation, application/cloud security testing, detection-evasion gap
-investigation, malware reverse engineering, cryptographic research, and threat intelligence.
-Existing `read_playbook` checklists remain the portable fallback when the native sidecar is absent.
-Web/Exa refreshes are quarantined candidates and never become active knowledge automatically.
-
-## Reliability evidence
-
-Archymedes's scheduled end-to-end suite runs build, debug, scoped search, Defender review, and
-cross-process resume journeys. It independently validates the result and scores completion,
-verification, valid tools, token economy, estimate calibration, scope, and state. The repository's
-`reliability/` directory contains the raw report and animated spectator UI. False success and
-silent permission escalation impose hard score caps.
-
-## Voice, language and keyboard input
-
-Run `/voice` to record from the default microphone, or `/voice path/to/audio.wav` to transcribe an existing file. The transcript is shown and can be edited or cancelled before it becomes a prompt. Voice transcription uses `OPENAI_API_KEY`, `gpt-4o-mini-transcribe` by default, and an OpenAI-compatible `/audio/transcriptions` endpoint. Set `VOICE_TRANSCRIPTION_URL` or `VOICE_MODEL` in `archymedes settings` when needed.
-
-Microphone recording uses `ffmpeg` because it provides one maintained capture path across operating systems. Install it with your normal package manager and set `VOICE_INPUT_DEVICE` if the default device is not correct. Archymedes uses PulseAudio on Linux, AVFoundation on macOS, and DirectShow on Windows; `ARCHYMEDES_FFMPEG_PATH` can point to a non-standard executable.
-
-Controls are available in English, Mandarin Chinese, Hindi, Spanish, French, Arabic, Bengali, Portuguese, Russian, and Urdu. Choose one in `archymedes settings`, set `ARCHYMEDES_LANGUAGE`, or pass `--language`. Stable slash-command names remain unchanged for scripts and muscle memory; `/help` and `/keys` localize their descriptions.
-
-Prompt history is persisted per user, deduplicated, and filters likely credentials. Tab completes commands, `@path` completes project files, arrow keys search history, Home/End navigate, Alt-Backspace/Ctrl-U delete, Ctrl-L redraws, and Ctrl-C interrupts the active turn.
-
-### Suggestions as you type
-
-Typing `/` opens a list above the input bar, narrowing with every letter and showing what each command does — plus the key that also runs it, so the list teaches its own shortcuts. Up and Down move through it and Enter takes a row; keep typing and it keeps narrowing; press Return and the command runs. It is never modal: every keystroke still reaches the line editor, so `/model haiku` types straight through the list that is offering `/model`. Greyed-out ghost text completes the rest of the name inline, and `→` accepts it.
-
-The list draws upward, into the rows directly above the bar. That is not a style choice — readline redraws its own line by erasing everything below it, so the rows above the bar are the only ones a list can occupy and survive a keystroke.
-
-### Keys
-
-The commands people reach for most are on Ctrl:
-
-| | | | |
-|---|---|---|---|
-| `Ctrl+A` auto mode | `Ctrl+W` wander | `Ctrl+S` settings | `Ctrl+G` palette |
-
-Every command with a shortcut also has an Alt mnemonic, which is the fuller set:
-
-| | | | |
-|---|---|---|---|
-| `Alt+W` wander | `Alt+M` model | `Alt+A` auto mode | `Alt+P` plan mode |
-| `Alt+D` diff | `Alt+U` undo | `Alt+C` cost | `Alt+O` tools |
-| `Alt+H` help | `Alt+T` new tab | `Alt+←` `Alt+→` tabs | `Alt+B` detach |
-
-**Tabs hold several pieces of work; the one in front is the one that runs.** Each tab keeps its own
-conversation, model, mode, cost and location, and switching away pauses that piece of work rather
-than leaving it running — a terminal transcript has one bottom, and two agents printing into it at
-once would interleave into something neither of them said. When you want work that keeps going while
-you do something else, that is `/detach`, `/jobs` and `/watch`: a detached job survives the terminal
-closing and streams into the session without taking the prompt. (Archymedes's desktop window is the other
-way round — it has a transcript per tab, so its tabs do run at the same time.)
-
-The function keys still work for the commands that had them (`F1` help, `F2` mode, `F3` model, `F4` wander, `F6` jobs, `F8` diff, `F9` todos) — several routes to the same command, so a terminal that swallows one does not cost you the feature. That redundancy is the reason there is a Ctrl layer at all: Alt is the modifier terminals are worst at delivering (tmux eats it by default, and macOS Terminal sends Option as a composition modifier unless you have found the "Use Option as Meta key" checkbox), so the most-used commands get a route that does not depend on it.
-
-Three of those Ctrl chords were readline line-editing keys, and taking them is not free. Each function moved to a key readline already handles natively, and `/keys` prints the move beside the chord that took it:
-
-| Was | Now | Still available as |
-|---|---|---|
-| `Ctrl+A` move to start of line | `/auto` | `Home` |
-| `Ctrl+W` delete the previous word | `/wander` | `Alt+Backspace` |
-| `Ctrl+S` XOFF flow control | `/settings` | — (raw mode disables flow control, so this key was inert) |
-
-A line-editing key can only be taken when its function has somewhere else to live, which is why `Ctrl+U` (delete to start of line) and `Ctrl+K` (delete to end) stay refused — nothing else does their job. `Ctrl+C`, `Ctrl+D`, Tab and Enter can never be rebound at all.
-
-There is no `Ctrl+M`. It is byte `0x0D`, which is exactly what Return sends, so no terminal can tell the two apart — binding it would fire the shortcut on every message you send. The same is true of `Ctrl+I` (Tab) and `Ctrl+J`. `/model` is on `Alt+M` and `F3`; asking for `ctrl+m` in your configuration reports this rather than failing silently.
-
-Bare letters are not shortcuts, for a reason worth knowing: this prompt is where you type your request, so a bare `w` for wander would cost you every message beginning with "write".
-
-`Ctrl+G` opens the command palette, which searches every command by name *or* by what it does — typing `revert` finds `/undo`, and letters that are not adjacent still match, so `wndr` finds `/wander`. Arrow keys, `Ctrl+P`/`Ctrl+N`, PageUp/PageDown and Home/End all move through it.
-
-`/keys` shows the live table, including anything your terminal is unlikely to deliver. To rebind, set `ARCHYMEDES_KEYS` (or the key-bindings entry in `archymedes settings`) to a comma-separated list like `/diff=alt+x, /wander=off`. An override replaces that command's default keys rather than adding to them.
-
-## Sandbox mode
-
-`--sandbox` runs everything in a disposable E2B container. Files exist only there; `--upload` seeds it with a copy of your project, and `/pull` brings results back.
-
-```bash
-archymedes --sandbox --upload "try upgrading to the new API and run the tests"
-```
-
-The sandbox executes commands as argv against an allowlist rather than through a shell, so pipes and redirection are unavailable there — Archymedes says so rather than failing obscurely.
-
-`--sandbox docker` uses a local Docker container instead of a remote one, for keeping work off your working tree without sending it to a third party. Pick the image with `--docker-image` or `DOCKER_CODING_IMAGE`.
-
-## Extending Archymedes: skills, hooks, plugins and MCP
-
-Everything here lives under `.archymedes/` in your project, so it travels with the repository and works the same in a local, Docker or E2B session. `/tools` lists whatever is currently loaded and where each piece came from.
-
-**Skills** are commands you name and describe, in `.archymedes/skills/<name>/skill.json`:
+The first run asks for a provider: pick one, paste its key, choose a model from the list the
+provider sends back. Nothing else is required.
+
+## The interface
+
+`archymedes` opens a small desktop in the terminal: a top bar with a `◇` start menu
+(`ctrl+space` finds any app, action, session or file), a tab per open window, and a dock with every
+app and its key — **F1** Chat, **F2** Files, **F3** Search, **F4** Sessions, **F5** Models,
+**F6** Themes, **F7** Keys, **F8** Help, **F9** Stats, **F10** Changes, **F12** Gallery; `alt+p`
+Providers and `alt+s` Settings. Everything is reachable by key and by mouse.
+
+- **Chat** streams the reply and every tool call with its result, folded (`ctrl+o` unfolds).
+- **Changes** is the working tree against the last commit, file by file, with each file's diff;
+  `b` turns to **Branches**: local and remote branches with how they stand against their upstream,
+  worktrees, and the stash, each readable in place.
+- **Models** lists every model of every provider, read live, with prices; **Providers** connects,
+  switches and sets the default.
+- **Stats** draws the session: tokens, time and tools per turn.
+
+`/help` lists every command; the most used are below.
+
+## Working with the agent
+
+| | |
+| --- | --- |
+| `/plan` `/build` `/auto` `/defender` | What the agent may do: read only; edit with approval (default); edit and run ordinary things without asking; security review where every change asks |
+| `/model [name]` | Switch model; the conversation carries on, across providers |
+| `/undo [code\|conversation]` | Revert the last turn — files, conversation or both; again for the one before |
+| `/rewind` | Every turn of the session with what it changed; go back to before any of them |
+| `/diff` | What changed since the last checkpoint |
+| `/review [base <ref>\|commit <ref>\|branch <ref>\|focus]` | A read-only review of a change, findings worst first; `R` on a branch in Branches reviews it |
+| `/commit [guidance]` | The agent reviews the changes and commits them (never pushes) |
+| `/push`, `/pr [guidance]` | Push the branch; `/pr` then has the agent open the pull request with `gh`. On the default branch a new branch is offered first |
+| `/goal <condition>` | Keep working, turn after turn, until the condition holds — judged after each turn, at most ten |
+| `/worktree [name]` | A new session on a new branch in its own worktree; `.archymedes/setup.sh` runs there first; `/worktree back` returns |
+| `/fork` | Copy the conversation into a new session; the original stays as it was |
+| `/compact [focus]`, `/context` | Summarize the conversation to free room; see what fills the context window |
+| `/resume`, `/new`, `/export` | Earlier sessions; a fresh one; this one as Markdown |
+| `!command` | Run a shell command yourself; its output shows here and is not sent to the agent |
+| `@path` | Mention a file in your message |
+
+**Steering.** A message sent while a turn runs reaches the agent after the tool calls in flight,
+within the same turn — "use tabs, not spaces" lands before the next edit.
+
+**Comments on diffs.** In Changes, `[` and `]` pick a line and `c` writes a note on it; your notes
+go with your next message, each with its file, line and code.
+
+## What keeps it safe
+
+**Approval.** In build mode every edit and command is shown and asked for: once, always for that
+exact action, or for a pattern (a command prefix, a directory). Plan mode does not load the write
+tools at all. Auto mode still stops for anything sensitive — credentials, deploys, publishing,
+pushes, destructive commands.
+
+**Checkpoints.** Before each turn the workspace is snapshotted into a private git index and kept by a
+hidden ref (`refs/archymedes/checkpoints/…`, never a branch), so `/undo` and `/rewind` work after a
+resume and after `git gc`, and your staged changes are never touched.
+
+**Command rules.** `.archymedes/rules.json` (or `rules.json` in the config directory) says what to
+`allow`, always `ask`, or `forbid`, by a command's leading words. Each rule can carry examples that
+are checked when it loads, so a rule that does not do what you meant is reported, not trusted:
 
 ```json
-{
-  "name": "coverage",
-  "description": "Reports test coverage for a package.",
-  "command": "npm run coverage -- --scope {{package}}",
-  "inputSchema": {
-    "type": "object",
-    "properties": { "package": { "type": "string" } },
-    "required": ["package"],
-    "additionalProperties": false
-  }
-}
+{ "rules": [
+  { "prefix": ["rm", ["-rf", "-fr"]], "decision": "forbid", "reason": "Use trash-put instead.", "match": ["rm -rf build"] },
+  { "prefix": ["git", "push"], "decision": "ask", "not_match": ["git pull"] },
+  { "prefix": ["npm", ["test", "run"]], "decision": "allow" }
+] }
 ```
 
-`{{package}}` is filled in with the model's argument, quoted for the shell that will run it — arguments are never pasted into the command raw.
-
-**Hooks** are scripts that see every tool call, in `.archymedes/hooks/pre-tool-use/` and `.archymedes/hooks/post-tool-use/`. They run in filename order and receive the call as base64 JSON in `ARCHYMEDES_HOOK_EVENT_B64`. A pre-tool-use hook that exits non-zero blocks the call and its stderr becomes the reason the model is given; a post-tool-use hook can only warn, since the work has already happened.
-
-**MCP servers** go in `.archymedes/mcp.json` as `{ "servers": [{ "id": "…", "command": "…", "args": [], "env": {} }] }`. Archymedes speaks stdio JSON-RPC to them and offers their tools alongside its own.
+A forbidden command is refused with its reason, and the agent carries on another way.
+
+**Command sandbox (Linux).** With `ARCHYMEDES_SANDBOX=on` and bubblewrap installed, commands can
+write only to the project and the temporary directory, `.archymedes` stays read-only, and there is
+no network (`ARCHYMEDES_SANDBOX_NETWORK=on` allows it). When something needs more, the agent asks
+to run that one command outside, and you are always asked. Off by default; without it, an approved
+command runs with your own permissions. `--sandbox` (E2B) and `--sandbox docker` run the whole
+session in a container instead.
+
+**Verification.** A turn that changed files without running anything that checks them ends as
+`needs_verification`, not `completed`.
+
+**Files changed under it.** When a file the agent read changes on disk, the next turn names it, so
+it re-reads instead of editing from a stale copy.
+
+## Providers
+
+| Provider | Key |
+| --- | --- |
+| Anthropic | `ANTHROPIC_API_KEY` |
+| OpenAI | `OPENAI_API_KEY` |
+| Google Gemini | `GOOGLE_API_KEY` |
+| xAI | `XAI_API_KEY` |
+| DeepSeek | `DEEPSEEK_API_KEY` |
+| Mistral | `MISTRAL_API_KEY` |
+| Groq | `GROQ_API_KEY` |
+| Ollama (local) | — |
+| Any OpenAI-compatible endpoint | `OPENAI_COMPATIBLE_API_KEY` + `OPENAI_COMPATIBLE_BASE_URL` |
+| Free models (`--free`) | `OPENROUTER_API_KEY` |
+| Claude (your subscription) | none: your own Claude Code, signed in (`claude auth login`) |
+| Codex (your ChatGPT plan) | none: your own Codex CLI, signed in (`codex login`) |
+
+Keys can be set in the environment or saved through Providers or `archymedes settings`. Claude
+runs through your installed Claude Code with Anthropic's Agent SDK (installed on your machine when
+you connect it), and Codex through your installed Codex CLI (`codex app-server`); Archymedes never
+handles either account's credentials. Switching between them and any other model mid-session keeps
+the conversation: each engine is told what was said while it was not there.
+
+## Extending it
+
+Everything lives under `.archymedes/` in the project, so it travels with the repository.
+
+- **Custom commands** — `.archymedes/commands/audit.md` becomes `/audit`; `$ARGUMENTS` is what you
+  type after it.
+- **Skills** — `.archymedes/skills/<name>/skill.json`: a named command with an input schema.
+- **Hooks** — scripts in `.archymedes/hooks/pre-tool-use/` (can block a call) and
+  `post-tool-use/` (can warn).
+- **MCP servers** — `.archymedes/mcp.json`.
+- **Plugins** — `.archymedes/plugins/<name>/` bundle the above.
+- **Memory** — `/memory` shows and edits what the agent remembers about you and the project, kept as
+  plain Markdown.
+
+Tools that did not ship with Archymedes always ask, in every mode, and say where they came from.
+
+## Without the interface
 
-**Plugins** bundle all three under `.archymedes/plugins/<name>/`, with a `plugin.json` naming any MCP servers plus optional `skills/` and `hooks/` directories in the same formats.
-
-Every tool that does not ship with Archymedes is approval-gated on every call regardless of mode, and the approval prompt names where it came from — a tool called `deploy` from an MCP server never looks like one of Archymedes's own.
-
-On Windows, hook scripts need an extension `cmd.exe` can execute (`.cmd` or `.bat`, or a `.ps1` invoked through one); a `.sh` file will not run without a POSIX shell installed. Skill commands and hook invocations are quoted for `cmd.exe` automatically when the session is local — a sandbox session is always quoted for Linux, since that is what the container runs.
-
-## Editors: the Agent Client Protocol
-
-`archymedes acp` runs the same agent over stdio in [ACP](https://agentclientprotocol.com), the protocol Zed and JetBrains use to host an agent, so an editor can drive a Archymedes session without a bespoke integration. Streaming replies arrive as `session/update` notifications, every tool call is announced and updated, and an approval becomes a `session/request_permission` request the editor answers — the same four decisions the terminal offers, with the same rule that anything other than an explicit allow is a refusal.
-
-```jsonc
-// what an editor sends, one JSON-RPC message per line
-{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":1,"clientCapabilities":{}}}
-{"jsonrpc":"2.0","id":2,"method":"session/new","params":{"cwd":"/path/to/project"}}
-{"jsonrpc":"2.0","id":3,"method":"session/prompt","params":{"sessionId":"…","prompt":[{"type":"text","text":"fix the failing test"}]}}
 ```
-
-`session/load` resumes a stored session, and `session/set_mode` switches between `plan`, `build`, `auto` and `defender` — rebuilding the session under the new capability set, exactly as `/mode` does in the terminal, because plan mode is a mode in which the write tools are not loaded rather than one where they are discouraged. While `archymedes acp` is running, stdout carries only protocol messages; diagnostics go to stderr.
+archymedes "add a health check"      One request, then exit
+archymedes --json "…"                Machine-readable events and result
+archymedes --plan | --auto | --defender
+archymedes --provider groq --model openai/gpt-oss-120b
+archymedes --free                    Free models only; never falls back to a paid one
+archymedes --resume                  Continue the last session
+archymedes --budget 500              A spend cap for the session, in your currency
+archymedes --estimate "task"         Forecast tokens and cost without calling a model
+archymedes acp                       The Agent Client Protocol on stdio, for an editor (Zed, JetBrains)
+archymedes settings | history | doctor | update
+```
 
 ## Requirements
 
-Node 22.5 or newer on Windows, macOS, or Linux. `git` enables checkpoints (Archymedes degrades to no-undo without it). `ffmpeg` is optional and needed only for direct microphone recording; existing audio files can still be transcribed without it.
-
-Apache-2.0 licensed.
-
-
-## The Archymedes terminal
-
-The default `archymedes` theme uses bronze instruments, limestone text and olive accents.
-The opening nested tetrahedron geometry, composer, turn status line, result cards and workspace share the active palette. Startup is
-static and uses a compact identity on short or narrow terminals, leaving room for the conversation.
-Light terminals automatically use `parchment`; `blueprint`, `chalkboard` and `high-contrast` remain
-available through `/theme list`. Use `archymedes --theme blueprint` to keep the previous palette.
-`NO_COLOR` and `--ascii` retain plain output and compatible glyphs.
-
-Result cards distinguish failed checks, interrupted work and verification still needed. Changed
-files include `/diff` and `/undo` as the next review actions. A green result requires completed work
-and passing checks recorded by the runtime.
-
-## Release validation
-
-From the repository root, run `bun run release:check`. This tests and builds the packages, inspects
-the CLI archive, installs that exact archive in a temporary consumer, and verifies Node startup and
-TUI dependency resolution. The reviewed archive and SHA256 checksum are written to `artifacts/`.
-See [the release assessment](https://github.com/chrisnkuno/archymedes-cli/blob/main/docs/RELEASE_ASSESSMENT.md) for scope and remaining release proof.
-
-The startup geometry makes a brief rotation on roomy interactive terminals. Set `ARCHYMEDES_NO_MOTION=1` to keep it still. Preview it with `bun run preview:tui archymedes --animate`.
-
-## Fixed workspace
-
-Interactive sessions open in the fixed workspace: a persistent mode bar, an anchored composer, and
-menus that open inside the transcript area. `/layout` switches layouts during a session;
-`archymedes --layout scrollback` or `ARCHYMEDES_LAYOUT=scrollback` keeps the plain terminal log.
-
-Use `/mode` to choose plan, build, auto, or defender with the arrow keys. To read history, use the
-mouse wheel or Page Up / Page Down. Alt+Up / Alt+Down (or Ctrl) move one line, and Ctrl+Home jumps
-to the top. Escape, Ctrl+End, or scrolling back to the bottom returns to live output. History keeps
-its colours, a scrollbar shows your position, and the header counts output that arrived while you
-were reading. Arrow keys, Home and End still edit the composer. Wheel scrolling uses mouse
-reporting, so hold Shift to select text, or set `ARCHYMEDES_MOUSE=0` to keep the terminal's own
-selection. Each tab retains up to 5,000 output lines, and resizing reflows the transcript.
-
-`/find <text>` searches the tab's history and jumps to the first match; `/find` again moves to the
-next one, `/find prev` to the previous, and `/find off` or Escape returns to live output. `/pager`
-opens the whole transcript in `$PAGER` (`less -R` by default). `/cat image.png` draws a PNG in the
-transcript with coloured half-blocks; in the scrollback layout, `ARCHYMEDES_IMAGES=kitty` uses Kitty
-graphics for real pixels, and `/clear` removes them.
+Node 22.5 or newer on Linux, macOS or Windows. The interface is a native binary installed with the
+package for linux, darwin and win32 on x64 and arm64; where none fits, every mode without the
+interface still works. `git` enables checkpoints, Changes, review and worktrees; `gh` is needed for
+`/pr`; bubblewrap for the command sandbox; Claude Code or the Codex CLI to run on those plans.
 
-The opening geometry rotates while the workspace is idle and settles as soon as you type.
-`ARCHYMEDES_NO_MOTION=1` disables this motion and menu focus animation. `--ascii`, `NO_COLOR`,
-and the existing themes remain supported. Try the real interface offline from the repository
-with `bun run preview:workspace`; the preview uses a temporary project and a local model fixture.
+Apache-2.0 licensed. Source: [github.com/chrisnkuno/archymedes-cli](https://github.com/chrisnkuno/archymedes-cli).

package/dist/{archymedes-qm9bwbe7.mjs → archymedes-cfwtgnjx.mjs}

@@ -1,9 +1,9 @@
-// packages/core/src/cli/protocol.ts
+// ../core/src/cli/protocol.ts
 import { createHash } from "node:crypto";
 import { promises as fs2 } from "node:fs";
 import path2 from "node:path";
 
-// packages/core/src/cli/file-ownership.ts
+// ../core/src/cli/file-ownership.ts
 import { randomUUID } from "node:crypto";
 import { promises as fs } from "node:fs";
 import os from "node:os";
@@ -97,7 +97,7 @@ async function acquireFileOwnership(file, depth = 0) {
   }
 }
 
-// packages/core/src/cli/protocol.ts
+// ../core/src/cli/protocol.ts
 var ARCHYMEDES_PROTOCOL_VERSION = 1;
 var JOURNAL_GENESIS_HASH = "0".repeat(64);
 var TRANSITIONS = {