Public: anyone can read this; the crew can change it.
docs/AI_AGNOSTIC.md lists every place the forge names or assumes one AI vendor #12239
Check · Review · Land · Live done — Landed and live in production.
mason/forge:mason/12121-docs-ai-agnostic-md-lists-every-place-th → main 3 commits fork
2 files
changed +177
−0
docs/AI_AGNOSTIC.md added +174
| @@ -0,0 +1,174 @@ | ||
| 1 | # AI agnostic: where the forge names or assumes one vendor | |
| 2 | ||
| 3 | The forge is meant to connect whichever AI a person brings. Claude has been | |
| 4 | the first and is still recommended, so it may head a list a person picks from; | |
| 5 | it is not what the forge is built around. This is the inventory (#12121, from | |
| 6 | the owner's ask #12068): every place under `src/`, `scripts/` and the docs that | |
| 7 | names or assumes one vendor, so each can be removed by the issue named beside | |
| 8 | it. It changes no code. | |
| 9 | ||
| 10 | Marks: | |
| 11 | ||
| 12 | - **seam**: code that is one vendor's CLI, protocol or credential format and | |
| 13 | would have to be written again for another AI. It moves behind the agent | |
| 14 | runner (`src/crew/agent_runner.ts`); the vendor's implementation stays, as | |
| 15 | the first runner. | |
| 16 | - **word**: a name a person reads (page, terminal, log, error, setting, doc, | |
| 17 | env name). It becomes "your AI", "model" or "runner"; a vendor's name stays | |
| 18 | only where a person picks one. | |
| 19 | - **tuning**: a number, alias, ladder or prompt chosen for one model family's | |
| 20 | habits (aliases, prices, limits, session files). | |
| 21 | ||
| 22 | Removing issues: **#12122** the runner seam (the CLI stays the first runner), | |
| 23 | **#12123** usage and limits through the seam, **#12124** the OpenAI-compatible | |
| 24 | second runner, **#12125** the real-cell hello-app test with it, **#12126** | |
| 25 | pages and terminal words, **#12127** neutral env names and log lines (old | |
| 26 | names still read), **#12128** briefs and prompts with nothing for one model | |
| 27 | family. "Stays" means a person picks it there, so the name is right; the row is | |
| 28 | listed so nothing is forgotten. | |
| 29 | ||
| 30 | Symbols are given where a line number would drift; `grep -n` the symbol. | |
| 31 | ||
| 32 | ## Code seams | |
| 33 | ||
| 34 | | File | Line or symbol | Mark | What it assumes | Removed by | | |
| 35 | | --- | --- | --- | --- | --- | | |
| 36 | | `src/crew/claude.ts` | `runClaude`, `claudeArgs`, `claudeSettings`, `detectClaude` | seam | `claude -p` stream-json, its flags, its settings JSON, its `result` and `rate_limit_event` records | #12122 (becomes the first runner; stays) | | |
| 37 | | `src/crew/agent_runner.ts` | `claude` runner object, import of `./claude.ts` | seam | the only registered runner is Claude's | #12124 adds the second | | |
| 38 | | `src/crew/runner.ts` | spawn env: `CLAUDE_CONFIG_DIR`, `CLAUDE_CODE_TMPDIR`, `TMPDIR` pairing (~1480-1515) | seam | the CLI's config and temp variables are set by the crew loop | #12122 | | |
| 39 | | `src/crew/runner.ts` | credential variable list: `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN`, `ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN` (~2411-2426, ~1463) | seam | which env carries a credential into a run | #12122, #12127 | | |
| 40 | | `src/crew/one_shot.ts` | env with `CLAUDE_CONFIG_DIR` | seam | one-shot calls use the CLI's config directory | #12122 | | |
| 41 | | `src/crew/conversation.ts` | `sessionsDir` (`claude-config`), `CLAUDE_CONFIG_DIR`, resume refusal text, `claudeSessionId` use | seam | a conversation resumes a CLI session file | #12122 | | |
| 42 | | `src/core/conversations.ts` | `claudeSessionId`, `claude_session_id`, `setClaudeSession` | seam | the conversation row stores the CLI's session id (a column name; a rename needs a migration) | #12122 | | |
| 43 | | `src/core/migrations/20261101090000-conversation.ts`, `20261103120000-conversations-many.ts` | `claude_session_id` column | seam | the same column; migrations are pinned and stay as written | #12122 (a new migration renames it) | | |
| 44 | | `src/crew/plan.ts` | `PLAN_MODEL = "haiku"`, `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`, `ANTHROPIC_API_KEY`, `CLAUDE_CODE_OAUTH_TOKEN`, `planningAvailable` runs `claude` | seam | the planner's one-shot call is the CLI | #12122, #12127 | | |
| 45 | | `src/crew/sandbox.ts` | `.claude`, `.claude.json` denials, `claude-<uid>` temp dir, `CLAUDE_CODE_TMPDIR`, socket-name limits | seam | the sandbox policy is written for the CLI's bridge sockets and files | #12122 | | |
| 46 | | `src/crew/leftovers.ts` | sweep of the CLI's sandbox bridges | seam | cleans processes only that CLI leaves | #12122 | | |
| 47 | | `src/crew/network.ts` | transient network error handling "Claude Code ends such a run…" | seam | which errors the CLI reports and how | #12123 | | |
| 48 | | `src/crew/grant.ts` | env filter `^(FORGE_\|GIT_\|CLAUDE_\|ANTHROPIC_…` | seam | which names are stripped from an agent's environment | #12127 | | |
| 49 | | `src/crew/dispatch.ts` | `detected.version`, `claude not usable`, `Claude Code ${version}` (health detail) | seam, word | startup check is for the CLI | #12122 (check), #12127 (words) | | |
| 50 | | `src/main.ts` | `FORGE_CLAUDE` (lines 586, 604), `FORGE_CLAUDE_CONFIG_DIR` (lines 594-596, 608), comment on the CLI's bridges | seam | the binary and config directory come from vendor-named env | #12127 | | |
| 51 | | `src/actions/apps.ts` | `process.env["FORGE_CLAUDE"] ?? "claude"` | seam | planning looks for the CLI | #12127 | | |
| 52 | | `src/web/pages/apps.ts` | `planningAvailable(FORGE_CLAUDE ?? "claude")` | seam | same, on the page | #12127 | | |
| 53 | | `src/spawn/cell.ts` | `claude?` input, `FORGE_CLAUDE` passed to a child forge | seam | a hosted forge's crew binary | #12127 | | |
| 54 | | `src/spawn/funding.ts` | `ANTHROPIC_BASE_URL`, `ANTHROPIC_API_KEY` for a child | seam | a child's starter key is an Anthropic-shaped credential | #12122, #12127 | | |
| 55 | | `src/spawn/model_door.ts` | `ANTHROPIC_*`, `CLAUDE_CODE_OAUTH_TOKEN`, `anthropic-version`, `anthropic-beta` headers, `api.anthropic.com` default | seam | the model door proxies one vendor's wire protocol | #12124 (a second protocol beside it) | | |
| 56 | | `src/spawn/door.ts` | credential help text: "Anthropic key, `claude setup-token`", the `sk-ant-oat` rule | seam, word | validation of one vendor's token shapes | #12126 (words), #12124 | | |
| 57 | | `src/core/subscriptions.ts` | `tokenEnvName` (`CLAUDE_CODE_OAUTH_TOKEN` / `ANTHROPIC_API_KEY`), `ANTHROPIC_BASE_URL`, `ANTHROPIC_AUTH_TOKEN` dance, `sk-ant-oat` and `sk-ant-api` detection, "Anthropic-compatible base URL", env presence check (~749) | seam | an account is one vendor's credential kind | #12122, #12124, #12127 | | |
| 58 | | `src/core/subscriptions_words.ts` | `claude setup-token`, `sk-ant-oat`, OpenRouter note | word | help text for one vendor's token | #12126 | | |
| 59 | | `src/core/migrations/0026-subscriptions.ts`, `0071-an-optional-anthropic-compatible-api.ts` (+ pin in `migration-pins.json`) | table and column history | word | historic migrations; pinned, never edited | #12122 (a new migration renames the column); these stay | | |
| 60 | | `src/core/capacity.ts` | `kind` values `off / openrouter / anthropic / both`, hosts `api.anthropic.com:443`, comments | seam, word | a child forge's allowed model hosts name two vendors | #12127, #12126 | | |
| 61 | | `src/apps/egress.ts` | comment: a crew's Claude Code reaches nothing | word | comment only | #12127 | | |
| 62 | | `src/apps/process.ts` | comments: the CLI's login, keychain | word | comment only | #12127 | | |
| 63 | | `src/core/plugin_install.ts` | `claudeInstall`, `claudeMarketplace`, `claude plugin marketplace add` | seam | the Claude Code plugin install flow | #12126 (stays: a person picks Claude Code; listed beside `opencodeInstall`) | | |
| 64 | | `src/core/mcp_card.ts` | harness `claude-code` / "Claude Code" | word | the harness list | #12126 (stays: kept as one picker choice) | | |
| 65 | | `src/http/plugin_routes.ts` | `/plugins/claude-code/marketplace.json`, `plugins/claude-code/commands` | seam | route and path of the Claude Code plugin | #12126 (stays: one picker choice) | | |
| 66 | | `plugins/claude-code/`, `plugins/opencode/` | plugin directories | seam | one plugin per harness | #12126 (stays: one picker choice each) | | |
| 67 | | `scripts/cold-read.ts` | `ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL`, `x-api-key` / `anthropic-version`, default `claude-sonnet-5-5` | seam | the cold-read audit calls one vendor's API | #12124 | | |
| 68 | | `src/crew/first_look.ts` | `FIRST_LOOK_MODEL = "claude-sonnet-5-5"` | tuning | a fixed model id | #12122 | | |
| 69 | ||
| 70 | ## Usage, limits and prices | |
| 71 | ||
| 72 | | File | Line or symbol | Mark | What it assumes | Removed by | | |
| 73 | | --- | --- | --- | --- | --- | | |
| 74 | | `src/core/measure.ts` | header, `rate_limit_event` parser | seam | the usage meter reads the CLI's rate-limit event format | #12123 | | |
| 75 | | `src/core/standing.ts` | comments: "Claude Code's refusal names the window", 5 h / 7 d windows | tuning | windows of one vendor's subscription | #12123 | | |
| 76 | | `src/crew/limits.ts` | refusal text, `api_error`, `resets 7:20am (UTC)` parser | seam | the CLI's wording of a limit | #12123 | | |
| 77 | | `src/core/usage.ts` | comment: cache reads "as Claude Code's `result.usage` reports them" | seam | the token fields | #12123 | | |
| 78 | | `src/crew/claude.ts` | `total_cost_usd`, `error_max_budget` handling | seam | cost and budget endings by the CLI's names | #12123 | | |
| 79 | | `src/crew/agent_runner.ts` | comments on `total_cost_usd`, "Claude: five minutes", "five seconds" | tuning | defaults named for the CLI | #12123 | | |
| 80 | | `src/spawn/list_price.ts` | table of Opus / Sonnet / Haiku prices from anthropic.com | tuning | list prices known for one family | #12123 (the runner reports cost; the table is a fallback) | | |
| 81 | | `src/kernel/tokens-format.ts` | "Claude's tokenizer" in tooltips (`counted`, estimate) and the ratio note on Anthropic and OpenAI | word | wording of the estimate | #12126 | | |
| 82 | | `src/actions/spend.ts`, `src/web/pages/spend.ts` | "as Claude Code reports them" | word | spend page caption | #12126 | | |
| 83 | ||
| 84 | ## Models and their tuning | |
| 85 | ||
| 86 | | File | Line or symbol | Mark | What it assumes | Removed by | | |
| 87 | | --- | --- | --- | --- | --- | | |
| 88 | | `src/crew/models.ts` | list: `claude-fable-5-1`, `opus`, `sonnet`, `haiku` | tuning | the picker's choices (the recommended one stays first) | #12126 (a picker, per runner) | | |
| 89 | | `src/crew/model_choice.ts` | `OPUS_MODEL`, `OPUS_LABEL = "opus"`, `PLANNER_MODEL = "sonnet"`, reasons `label:opus`, `planner:handed` | tuning | escalation is to a named model | #12122, #12126 (a "stronger model" tier per runner) | | |
| 90 | | `src/core/model_review.ts` | `LADDER = ["claude-fable-5-1","opus","sonnet","haiku"]`, SQL on `label:opus` | tuning | the review ladder | #12122 | | |
| 91 | | `src/core/agents.ts` | "A Claude Code model alias or id" | word | model field comment | #12126 | | |
| 92 | | `src/core/runs.ts` | comment: "what escalated the run to Opus" | word | comment | #12126 | | |
| 93 | | `src/core/migrations/20261027140000-run-model-reason.ts`, `20261109190000-run-context-tokens.ts` | comments | word | pinned history | #12126 (stays: pinned, never edited) | | |
| 94 | | `src/crew/runner.ts` | comments on Opus / Sonnet choice (~1527) | word | comment | #12126 | | |
| 95 | ||
| 96 | ## Prompts and briefs | |
| 97 | ||
| 98 | | File | Line or symbol | Mark | What it assumes | Removed by | | |
| 99 | | --- | --- | --- | --- | --- | | |
| 100 | | `src/crew/brief.ts` | system prompt "appended to Claude…", "the repository's CLAUDE.md or AGENTS.md" | tuning | text for one CLI and its memory file | #12128 | | |
| 101 | | `src/crew/claude.ts` | `claudeSettings` tools and permissions | tuning | tool names only that CLI knows | #12128 (lives with its runner) | | |
| 102 | | `src/crew/conversation.ts`, `src/crew/conversation_confirm.ts` | "add a Claude login", MCP-only settings via `claudeSettings` | tuning, word | conversation tools in the CLI's shape | #12128, #12126 | | |
| 103 | | `src/web/doors_words.ts` | "Read README.md and CLAUDE.md (when present)" | tuning | a prompt handed to any assistant names one memory file | #12128 | | |
| 104 | | `src/web/standards.ts` | "Claude Code plugin: not offered…", "its crew needs the claude CLI" | word | standards and install text | #12126 | | |
| 105 | | `CLAUDE.md` (repository root) | the project's own instructions file; `AGENTS.md` is the neutral twin | tuning | the file name the CLI reads | #12128 (point both at one text) | | |
| 106 | | `src/crew/dispatch.ts`, `src/crew/runner.ts` | log lines `claude: budget $…`, `claude: <reason>, N turns`, `claude: wrapping up with the reserve`; `crew is up` with `claude: <version>`; `claude not usable` | word | log lines other tools and `src/web/pages/runs.ts` / `src/web/client.ts` match on `^(claude:\|done:…` | #12127 (log), then the two matchers in the same change | | |
| 107 | ||
| 108 | ## Pages, settings and the terminal | |
| 109 | ||
| 110 | | File | Line or symbol | Mark | What it assumes | Removed by | | |
| 111 | | --- | --- | --- | --- | --- | | |
| 112 | | `src/web/pages/model.ts` | page "Model", `claude setup-token` hint | word | should read "Connect your AI" | #12126 | | |
| 113 | | `src/tui/screens/model.ts` | "token (from `claude setup-token`…)", "API base URL (empty for Anthropic)" | word | same, in the terminal | #12126 | | |
| 114 | | `src/web/pages/subscriptions.ts`, `src/tui/screens/subscriptions.ts`, `grants.ts`, `orggrants.ts` | "Claude subscription", "Add a Claude account", `claude setup-token`, "Empty for Anthropic itself" | word | the accounts page | #12126 | | |
| 115 | | `src/http/mcp/tools/subscriptions.ts`, `subscription_add.ts`, `subscription_wake.ts` | "Claude accounts", "Add a Claude login" | word | MCP tool descriptions | #12126 | | |
| 116 | | `src/actions/talk.ts`, `src/contract/openapi/routes/postApiV1ConversationMessages.ts`, `getApiV1AdminSubscriptions.ts` | "no Claude account is granted…" | word | error and API text (contract text, regenerate) | #12126 | | |
| 117 | | `src/web/studio/crew_key.ts`, `src/tui/screens/crewkey.ts` | "Your Anthropic API key or Claude login" | word | the first-run key form | #12126 | | |
| 118 | | `src/web/pages/crew.ts` | "Claude Code on PATH or at `FORGE_CLAUDE`" | word, seam | operator hint | #12126, #12127 | | |
| 119 | | `src/web/pages/new-forge.ts`, `src/tui/screens/newforge.ts` | "Anthropic-compatible gateway", "Leave empty for Anthropic", "a Claude sign-in key (sk-ant-oat…)" | word | hosted-forge form | #12126 | | |
| 120 | | `src/actions/spawn.ts` | comment on the Anthropic-compatible base URL | word | comment | #12127 | | |
| 121 | | `src/packs/up.ts` | "start this command again with ANTHROPIC_API_KEY set" | word, seam | CLI message | #12127 | | |
| 122 | | `src/web/pages/account.ts` | `connect-claude`, "Claude Code" plugin card, `claudeInstall` | word | connect-a-harness card | #12126 (stays: one entry in a picker list) | | |
| 123 | | `src/tui/screens/signins.ts` | "Claude Code plugin (c copies)", `claudeInstall` | word | terminal sign-in screen | #12126 (stays: one picker choice) | | |
| 124 | | `src/tui/screens/changelog.ts` | "by Scout, with Claude Sonnet 5.5" | word | an example of the co-author line | #12126 (stays: the commit's own words) | | |
| 125 | | `src/web/studio/home.ts` | "Open in ChatGPT, Claude and Grok" links, `claude.ai/new` | word | a list of assistants, one per vendor, already plural | #12126 (stays: a person picks one) | | |
| 126 | | `src/http/mcp.ts` | header: "Added to Claude as a connector…" | word | comment | #12126 | | |
| 127 | | `src/core/contribute_token.ts` | comment listing Codex, Jules, Claude Code, Cursor | word | already plural | #12126 (stays: a list of harnesses) | | |
| 128 | | `src/web/pages/runs.ts`, `src/web/client.ts` | line matcher `^(claude:\|done:…` | word | recognises the CLI's log prefix | #12127 | | |
| 129 | | `src/core/migrations/0061-an-agent-never-owns-an.ts` | line 1: "CLAUDE.md invariant 10" | word | comment naming the repo's rules file; pinned in `migration-pins.json` | #12128 (stays as written: pinned) | | |
| 130 | | `src/actions/orgs.ts`, `src/core/orgs.ts` | "CLAUDE.md, invariant 10" in comments | word | names the repo's own rules file | #12128 | | |
| 131 | ||
| 132 | ## Docs | |
| 133 | ||
| 134 | These name the CLI as how the crew runs today; each follows the code change | |
| 135 | that makes it true. "Line" is the first match; the count is every match. | |
| 136 | ||
| 137 | | File | Line (matches) | Mark | What it names | Removed by | | |
| 138 | | --- | --- | --- | --- | --- | | |
| 139 | | `docs/CREW.md` | 8 (11) | word | the crew "runs Claude Code"; env names | #12126, #12127 | | |
| 140 | | `docs/APPS.md` | 317 (16) | word | the `claude` one-shot call, `FORGE_CLAUDE` | #12127 | | |
| 141 | | `docs/MCP.md` | 210 (15) | word | "Add a Claude login", tool descriptions | #12126 | | |
| 142 | | `docs/REFERENCE.md` | 62 (9) | word | `opus`-labelled escalation, the CLI | #12126, #12127 | | |
| 143 | | `docs/ARCHITECTURE.md` | 645 (3) | word | a Claude Code session in the clone | #12126 | | |
| 144 | | `docs/CACHING.md` | 35 (2) | word | "CLAUDE.md, invariant 4": the rules file | #12128 | | |
| 145 | | `docs/features/tokens-harness.md` | 4 (5) | word | harness names | #12126 (stays where a person picks one) | | |
| 146 | | `docs/features/child-credit.md` | 26 (6) | word | `ANTHROPIC_API_KEY`, `ANTHROPIC_BASE_URL` | #12127 | | |
| 147 | | `docs/features/talk.md` | 9 (2) | word | "a granted Claude account" | #12126 | | |
| 148 | | `docs/features/talk-captain.md` | 3 (2) | word | Claude account, session | #12126 | | |
| 149 | | `docs/features/starter-crew.md` | 5 (1) | word | bring your own key, one vendor's | #12126 | | |
| 150 | | `docs/features/real-cell-proof.md` | 8 (1) | word | `FORGE_CLAUDE` in a cell | #12125, #12127 | | |
| 151 | | `docs/features/contribute-token.md` | 3 (1) | word | list of agents incl. Claude Code | #12126 (stays: a list) | | |
| 152 | | `docs/features/nightly.md` | 28 (1) | word | the crew's Claude credential | #12127 | | |
| 153 | | `docs/features/changelog.md` | 25 (1) | word | co-author line example | #12126 (stays: commit's own words) | | |
| 154 | | `docs/features/first_look.md` | 5 (1) | tuning | a fixed model id | #12122 | | |
| 155 | | `docs/features/model-escalation.md` | 1 (5) | tuning | escalate to Opus | #12122, #12126 | | |
| 156 | | `docs/features/model-review.md` | 3 (2) | tuning | the review ladder | #12122 | | |
| 157 | | `docs/DEVELOP.md` | 18 (1) | word | `cold-read.ts` and its key | #12124 | | |
| 158 | | `docs/EXTRACT.md` | 11 (2) | word | the `claude` binary | #12127 | | |
| 159 | | `docs/ON-YOUR-MACHINE.md` | 129 (1) | word | the CLI's login | #12126 | | |
| 160 | | `docs/STATUS.md` | 139 (1) | word | "in the background with Claude Code" | #12126 | | |
| 161 | | `docs/VISION.md` | 10 (1) | word | harness list | #12126 (stays: a list) | | |
| 162 | | `docs/design/audit.md` | 81 (1) | word | a page's wording | #12126 | | |
| 163 | | `docs/ops/RED-TEAM.md` | 23 (2) | seam | `claudeSettings` sandbox | #12122 | | |
| 164 | | `docs/research/celld.md` | 44 (1) | word | the CLI's bubblewrap policy | #12122 | | |
| 165 | | `README.md` | 33 (1) | word | "needs the `claude` CLI" | #12126, #12127 | | |
| 166 | | `CLAUDE.md` | 1 (4) | tuning | the file name the CLI reads | #12128 | | |
| 167 | ||
| 168 | ## How to keep this true | |
| 169 | ||
| 170 | `grep -rniE "claude|anthropic|opus|sonnet|haiku" src scripts` is the check | |
| 171 | this list was built from (318 matching lines in 86 files under `src` and | |
| 172 | `scripts` on the day it was written; the counts above drift, the grep is the truth). When #12126 lands, the same grep over `src/web` and `src/tui` | |
| 173 | should find only a picker's choices; a row that no longer matches is deleted | |
| 174 | from this file in the pull that removed it. |
docs/REFERENCE.md +3
| @@ -2,6 +2,8 @@ | ||
| 2 | 2 | |
| 3 | 3 | The long version: how it runs, its options and how it fits together. [](../README.md) is the short one. |
| 4 | 4 | |
| 5 | The forge is AI agnostic: you connect your AI, whichever it is. [](AI_AGNOSTIC.md) lists every place that still names or assumes one vendor, and the issue that removes each. | |
| 6 | ||
| 5 | 7 | It runs the apps it hosts, and a **crew** of agents builds them. You describe |
| 6 | 8 | an app in a sentence; the sentence becomes an issue, and the agent it is |
| 7 | 9 | assigned to works it in its own fork and opens a pull. Every push redeploys |
| @@ -499,6 +501,7 @@ Once a minute the forge measures its landing rate, names the one cause binding i | ||
| 499 | 501 | - [](ON-YOUR-MACHINE.md) — the `forge` command on your machine: the local copy, offline work and building the binary. |
| 500 | 502 | - [](web.md) — the rules for assets and HTML: what is cached where, how a page streams, and the byte budgets a test enforces. |
| 501 | 503 | - [](PRINCIPLES.md) — what the forge holds to, each with what enforces it; capped, and read by the crew and the in-forge conversation. |
| 504 | - [](AI_AGNOSTIC.md) — every place the forge still names or assumes one AI vendor, and the issue that removes each. | |
| 502 | 505 | This page is the front door. Everything else is a file of its own under |
| 503 | 506 | `docs/`, each about one thing: |
| 504 | 507 |
new above
offline