multi-forge 0.9.1__tar.gz → 0.9.3__tar.gz

multi_forge-0.9.3/PKG-INFO

@@ -0,0 +1,348 @@
+Metadata-Version: 2.4
+Name: multi-forge
+Version: 0.9.3
+Summary: Multi-runtime agent toolkit: proxy routing, cost control, session management, policy enforcement, and workflow orchestration
+Project-URL: Homepage, https://github.com/hapa1i/multi-forge
+Project-URL: Repository, https://github.com/hapa1i/multi-forge
+Project-URL: Issues, https://github.com/hapa1i/multi-forge/issues
+Project-URL: Documentation, https://github.com/hapa1i/multi-forge/tree/main/docs
+Author-email: Habib Farr <hapali@pm.me>
+License-Expression: Apache-2.0
+License-File: LICENSE
+License-File: NOTICE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Requires-Python: <3.14,>=3.11
+Requires-Dist: click>=8.3.1
+Requires-Dist: coolname<6,>=5.0.0
+Requires-Dist: dacite>=1.8.0
+Requires-Dist: fastapi>=0.115.14
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: litellm[proxy]>=1.88.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: packaging>=21.0
+Requires-Dist: pydantic>=2.0.0
+Requires-Dist: python-dotenv>=1.2.2
+Requires-Dist: pyyaml>=6.0.0
+Requires-Dist: rich>=13.9.0
+Requires-Dist: ruamel-yaml>=0.18.0
+Requires-Dist: tenacity>=8.0.0
+Requires-Dist: uvicorn>=0.31.1
+Requires-Dist: watchfiles>=0.20
+Description-Content-Type: text/markdown
+
+# Multi-Forge
+
+<p align="left">
+  <img src="assets/logo.jpg" alt="Dusk" width=240">
+</p>
+
+[![PyPI](https://img.shields.io/pypi/v/multi-forge)](https://pypi.org/project/multi-forge/)
+[![Python](https://img.shields.io/pypi/pyversions/multi-forge)](https://pypi.org/project/multi-forge/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+
+> [!WARNING]
+> **Research Preview** -- Forge is under active development. APIs, commands, and file formats may change without notice
+> between releases. Not recommended for production use.
+
+**Multi-runtime control plane for coding agents: put one vendor's model to work checking another's.**
+
+Forge runs Claude Code or Codex as a managed session, then dispatches other models around it -- supervising writes
+against an approved plan, curating handoffs across the vendor boundary, reviewing in a multi-model panel, and metering
+what all of it cost. You launch through `forge session start` instead of invoking the runtime directly. Claude sessions
+can route to a chosen provider through a local proxy; both runtimes share Forge's session state and policy model.
+
+```bash
+# Claude with session tracking (no proxy needed)
+forge session start
+
+# Route through a different provider -- --proxy takes a template name and starts it
+forge session start planner --proxy openrouter-openai
+
+# Have OpenAI's Codex police a Claude session's edits against the approved plan
+forge session fork planner -n executor -w --supervise --supervisor-runtime codex --no-launch
+```
+
+## Why Forge?
+
+Claude Code talks to Anthropic and tracks conversations. Forge adds an operational layer on top:
+
+- **Cross-Vendor Supervision** -- Bind the plan supervisor or memory writer to a different consumer lane, or select a
+  different runtime per review worker. The policy can evaluate every Write/Edit against the approved plan with a
+  read-only `codex exec`; exact repeats may reuse its short-lived verdict cache.
+- **Two Runtimes, One Session Graph** -- Claude sessions fork and resume; Codex sessions resume, and new Codex branches
+  use `forge session start --runtime codex --resume-from <parent>` to carry curated context across the boundary.
+  `forge session adopt` binds a conversation you started outside Forge.
+- **Multi-Model Routing** -- Route to GPT, Gemini, or any model via OpenRouter or LiteLLM through a local proxy. Forge
+  sets `CLAUDE_CODE_AUTO_COMPACT_WINDOW` so compaction timing matches the routed model's context window.
+- **Cost Control** -- `forge telemetry costs show` reports what each proxy actually spent; per-proxy daily and monthly
+  caps reject or warn at the ceiling. Cost is reported or marked unavailable -- never inferred from token counts.
+- **Sessions That Outlive Context** -- Named sessions persist artifacts, plans, and transcripts. When context fills up,
+  hand off to a fresh session with structured or AI-curated history you can edit before it lands.
+- **Policy, Review, and Verification** -- TDD and coding-standard bundles, semantic alignment checks, multi-model review
+  fan-out, and verification loops that keep an agent working until tests pass.
+
+### Why launch through Forge?
+
+Running `claude` directly bypasses session tracking. When you launch through Forge (`forge session start`), you get:
+
+| Feature                | `claude` directly | `forge session start`                             |
+| ---------------------- | ----------------- | ------------------------------------------------- |
+| Session tracking       | No                | Yes -- named sessions, artifacts, transcripts     |
+| Session resume         | No                | Yes -- editable handoff to fresh context          |
+| Status line            | No                | Yes -- proxy, session, policy info                |
+| Hook-driven artifacts  | No                | Yes -- plan snapshots, transcript capture         |
+| Policy enforcement     | No                | Yes -- TDD, coding standards, supervisor          |
+| Search across sessions | No                | Yes -- `forge search` indexes transcripts         |
+| Project memory         | No                | Yes -- opt-in; passported docs curated after exit |
+| Adopt an existing chat | n/a               | Yes -- `forge session adopt <conversation-id>`    |
+
+Already deep into a bare `claude` or `codex` conversation? `forge session adopt` binds it to a managed session instead
+of making you start over -- run it from the directory the conversation was launched in.
+
+## How it Works
+
+Forge sits between you and the agent runtime. It owns session state and policy, dispatches auxiliary consumers through
+persisted lane bindings, selects review workers independently per workflow, and optionally routes model traffic through
+a local proxy.
+
+```text
+You  ->  forge session  ->  Claude Code  |  Codex
+              |
+              +-- consumer lanes  -> supervisor       (claude | codex)
+              |                      memory_writer     (claude | codex)
+              |                      shadow_curation   (claude | codex)
+              |                      team_supervisor   (claude)
+              |
+              +-- workflow workers -> panel | analyze | debate | consensus
+              |                      (claude | opt-in codex)
+              |
+              +-- proxy            -> OpenRouter | LiteLLM -> any model
+              +-- state            -> artifacts, policy, telemetry
+```
+
+**Claude direct mode** (the default for Claude sessions) skips the proxy and talks to Anthropic directly; you still get
+sessions, hooks, consumer lanes, and the status line. Add `--proxy` for routing. **OpenRouter** templates call the
+OpenRouter API directly -- one API key covers Anthropic, OpenAI, Google, and more. **LiteLLM** templates route through a
+[LiteLLM](https://github.com/BerriAI/litellm) proxy, remote or a local subprocess. Twenty user-facing templates ship;
+see [docs/end-user/proxy.md](docs/end-user/proxy.md).
+
+## Requirements
+
+- **Platform**: macOS or Linux
+- **Python**: 3.11-3.13 (3.14 blocked on upstream `uvloop` wheels -- see #1)
+- **Installer**: [`uv`](https://docs.astral.sh/uv/) or [`pipx`](https://pipx.pypa.io/) for the recommended global
+  install
+- **Claude Code**: required for the default and other Claude-backed workflows; a Codex-only session or skill path does
+  not require it
+- **Codex** (optional): needed for `--runtime codex` sessions, `forge codex start`, Codex-backed consumer lanes, and the
+  opt-in Codex workflow worker. Check readiness with `forge runtime preflight codex`; proxy-routed `forge codex start`
+  needs codex >= 0.141.0.
+- **Provider auth**: Claude Code login is enough for direct interactive sessions. Proxies and headless workflows need a
+  supported API or gateway credential such as `OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`,
+  `OPENAI_API_KEY`, or LiteLLM auth.
+
+## Quick Start
+
+```bash
+# Install Forge as a global tool (recommended -- puts `forge` on your PATH)
+uv tool install multi-forge
+# or: pipx install multi-forge
+
+# Make uv's tool bin available in this shell and future shells
+uv tool update-shell
+export PATH="$(uv tool dir --bin):$PATH"
+
+# Confirm how forge is installed and whether it is globally reachable
+forge extension doctor
+
+# Register runtime hooks once, at user scope
+forge extension enable --scope user --profile minimal --with hooks,codex-hooks --without commands
+
+# Then, inside a project: install project-owned assets and settings
+forge extension enable
+
+# Launch Claude with session tracking (no proxy needed)
+forge session start
+
+# Or with multi-model routing -- --proxy accepts a template name and starts the proxy for you
+forge auth login -c openrouter                        # store OPENROUTER_API_KEY
+forge session start --proxy openrouter-anthropic
+```
+
+Developing on Forge itself? See [CONTRIBUTING.md](CONTRIBUTING.md) for the editable install.
+
+Once running, try `/forge:smoke-test` (Claude) or `$smoke-test` (Codex) for a read-only health check, or
+`/forge:walkthrough` for a guided tour in a sandboxed test repo.
+
+## Plan, Execute, Review
+
+A typical feature workflow assigns different model roles to planning, execution, and review. The supervisor is a *lane*,
+not a fixed model -- pin it to `codex` and a second vendor grades the first.
+
+```bash
+# 1. Plan with a high-reasoning model (--proxy takes a template; Forge starts it)
+forge session start planner --proxy openrouter-openai
+# ... Claude writes a plan, you approve it, /exit
+
+# 2. Execute in a worktree, with the policy evaluating every Write/Edit against
+#    the approved plan through read-only Codex (exact repeats may reuse its cache).
+forge runtime preflight codex                 # cache the readiness the lane reads
+forge session fork planner -n executor -w --supervise --supervisor-runtime codex --no-launch
+forge policy supervisor reload -s executor    # REQUIRED: codex has no --resume, so the
+                                              # approved plan must reach it in-band
+cd ../multi-forge-executor                    # worktrees land at ../<repo-name>-<session-name>
+forge session resume executor
+
+# 3. Context filling up? Resume fresh -- supervisor config carries over.
+forge session resume executor --fresh --strategy ai-curated
+
+# 4. Review from the planner's perspective, inside the executor's worktree
+forge session fork planner --into ../multi-forge-executor
+
+# 5. Push and open a PR
+git push origin feature-branch
+```
+
+Two prerequisites keep the Codex lane enforcing instead of failing open with a warning:
+
+- **The plan reload is mandatory.** Codex has no `--resume`, so it cannot read the planning conversation. With no plan
+  in-band, Forge fails the check open *without spawning Codex* -- it warns, it does not block. Use
+  `forge policy supervisor reload`, or `%policy supervisor reload` from inside the session.
+- **Preflight is cached, never probed during a check.** `codex doctor` is slow, but it is the probe that discovers
+  stored ChatGPT-login auth. The policy hook therefore reads the full result cached by `forge runtime preflight codex`
+  instead of rerunning it. A cold or stale cache fails open and prints a refresh hint.
+
+`forge policy supervisor status` shows the bound `(runtime, backend, model)` lane. When preflight selects stored ChatGPT
+tokens as the auth source, the check is labeled `subscription_quota` rather than Anthropic usage. Full details in
+[docs/end-user/policy.md](docs/end-user/policy.md).
+
+### Codex as a worker runtime
+
+Codex is not only an alternate frontend -- it is a runtime Forge dispatches work to:
+
+- **Other lanes.** `forge session lane set --consumer memory_writer --runtime codex` (also `shadow_curation`) moves that
+  consumer onto `codex exec`. `team_supervisor` has no Codex lane and rejects it.
+- **A whole task, seeded from a Claude parent.**
+  `forge session start impl --runtime codex --resume-from planner --task "Implement the plan."` carries curated context
+  across the vendor boundary; continue with `forge session resume impl --task "Now add tests."`.
+- **Codex TUI through a Forge proxy.** `forge codex start --proxy <id>` -- the proxy owns upstream auth, so no OpenAI
+  login is required or leaked.
+- **Capability matrix.** `forge runtime list` shows what each detected runtime supports.
+
+## Cost and Wire Control
+
+```bash
+forge telemetry costs show --period month --by-model   # authoritative proxy-scoped spend
+forge telemetry activity planner                       # what Forge's automation did in one session
+forge proxy set openrouter-openai costs.caps.per_day=20
+forge proxy set openrouter-openai costs.on_cap_hit=reject   # or 'warn' for a header-only alert
+```
+
+Caps take effect when the proxy next starts, and are enforced *after* each completed request -- one request can cross a
+cap and finish before the next is refused. `forge session start --subprocess-proxy <id>` keeps the interactive session
+on direct Anthropic routing while supervisor, panel, and memory-writer subprocesses run metered through a proxy (it is
+mutually exclusive with `--proxy`). Direct routing does not by itself guarantee subscription billing: the default
+`interactive_anthropic_api_key=inherit` passes a resolvable API key. To force the interactive process to use its Claude
+login, run `forge config set interactive_anthropic_api_key=omit`; see
+[authentication.md](docs/end-user/authentication.md#keeping-a-key-out-of-interactive-sessions-interactive_anthropic_api_key).
+
+A Forge proxy can also be an audit chokepoint. The default wire shape translates Anthropic to OpenAI and **drops
+`thinking` blocks**; the shipped `anthropic-passthrough` template forwards the raw body byte-for-byte and already ships
+`intercept.mode: inspect`, which hashes the system prompt and tool surface and flags drift when either changes
+underneath you. `forge proxy audit show|diff` renders the timeline. Records are redacted before they reach disk --
+hashes, lengths, and counts, never prompt or completion text.
+
+## Skills
+
+Nine skills compile for **both** runtimes -- Claude invokes `/forge:<name>`, Codex invokes `$<name>`: `analyze`,
+`challenge`, `consensus`, `debate`, `panel`, `review`, `review-docs`, `smoke-test`, `understand`. Only
+`/forge:walkthrough` and `/forge:qa` are Claude-only.
+
+The same runners are available from the terminal, and `--check` turns one into an exit-code gate you can script:
+
+```bash
+forge workflow panel src/forge/session/ --code   # fan a review out to several models
+forge workflow debate "Should we rewrite this in Rust?"
+forge workflow panel src/ --code --check         # exit 0 if every worker accepts, else 1
+forge workflow list-models                       # which workers are ready right now
+```
+
+See [docs/end-user/skills.md](docs/end-user/skills.md) and [docs/end-user/workflow.md](docs/end-user/workflow.md).
+
+## CLI Overview
+
+| Command Group     | Purpose                                               |
+| ----------------- | ----------------------------------------------------- |
+| `forge session`   | Named sessions, worktrees, resume, fork, adopt, lanes |
+| `forge claude`    | Bare launch, settings preset management               |
+| `forge codex`     | Codex status, proxy-routed TUI launch                 |
+| `forge runtime`   | Runtime inventory and readiness preflight             |
+| `forge proxy`     | Model routing, templates, tier mappings, wire audit   |
+| `forge model`     | Model catalog, backends, local backend lifecycle      |
+| `forge telemetry` | Costs, per-session activity, provider traces          |
+| `forge policy`    | Policy enforcement, plan supervision, shadow audit    |
+| `forge workflow`  | Workflow runners (panel, analyze, debate, consensus)  |
+| `forge memory`    | Project memory passports, shadow proposals            |
+| `forge search`    | Transcript search across sessions                     |
+| `forge auth`      | Credential management (`credentials.yaml`)            |
+| `forge config`    | Runtime preferences (`~/.forge/config.yaml`)          |
+| `forge extension` | Enable/sync/disable extensions                        |
+| `forge clean`     | Preview and remove orphaned Forge state               |
+| `forge logs`      | Log file locations and cleanup                        |
+| `forge info`      | System health and installation info                   |
+
+Run `forge <command> --help` for details on any command.
+
+## Documentation
+
+| Audience            | Location                                             | Contents                                              |
+| ------------------- | ---------------------------------------------------- | ----------------------------------------------------- |
+| **Users**           | [docs/end-user/](docs/end-user/)                     | 13 guides -- start with the Day 1 workflow            |
+| **Developers**      | [docs/developer/](docs/developer/)                   | Setup, coding standards, testing guidelines           |
+| **Architecture**    | [docs/design.md](docs/design.md)                     | Core system narrative, data flow, invariants          |
+| **Workflow design** | [docs/design_workflows.md](docs/design_workflows.md) | Policy, skills, workflow runners, memory architecture |
+| **CLI reference**   | [docs/cli_reference.md](docs/cli_reference.md)       | Terminal and direct-command inventory                 |
+| **Work Board**      | [docs/board/](docs/board/)                           | Cards, checklists, change log, implementation memory  |
+
+Common starting points: [sessions](docs/end-user/session.md), [proxies](docs/end-user/proxy.md),
+[policy and supervision](docs/end-user/policy.md), [model selection](docs/end-user/model_selection.md),
+[transfer context](docs/end-user/transfer.md), and [project memory](docs/end-user/memory.md).
+
+## Troubleshooting
+
+> [!NOTE]
+> **Corrupt state?** If Forge reports that its state is corrupt, it names the offending file and stops -- it never
+> silently runs on bad state. Run `forge clean` to preview what would be removed, then `forge clean --yes` to remove it
+> (add `--scope all` to cover every project). For a full reset, delete `.forge` (project-local) or `~/.forge` (global)
+> and re-run `forge extension enable`. Your own files and `proxy.yaml` config are never touched by `forge clean`.
+
+`forge extension doctor` reports how Forge is installed, whether the launcher is reachable, and the state of the hook
+dispatcher. Upgrading from a pre-OSS Forge install? See
+[docs/end-user/README.md](docs/end-user/README.md#upgrading-from-pre-oss-forge).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and PR guidelines.
+
+## Uninstall
+
+```bash
+forge extension disable
+uv tool uninstall multi-forge   # or: pipx uninstall multi-forge
+```
+
+## License
+
+Apache 2.0 -- see [LICENSE](LICENSE).
+
+Originally developed as Claude Forge at [Thomson Reuters](https://github.com/thomsonreuters/claude-forge) and
+open-sourced under Apache 2.0. Continued as Multi-Forge by the original author.

multi_forge-0.9.3/README.md

@@ -0,0 +1,307 @@
+# Multi-Forge
+
+<p align="left">
+  <img src="assets/logo.jpg" alt="Dusk" width=240">
+</p>
+
+[![PyPI](https://img.shields.io/pypi/v/multi-forge)](https://pypi.org/project/multi-forge/)
+[![Python](https://img.shields.io/pypi/pyversions/multi-forge)](https://pypi.org/project/multi-forge/)
+[![License](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)
+
+> [!WARNING]
+> **Research Preview** -- Forge is under active development. APIs, commands, and file formats may change without notice
+> between releases. Not recommended for production use.
+
+**Multi-runtime control plane for coding agents: put one vendor's model to work checking another's.**
+
+Forge runs Claude Code or Codex as a managed session, then dispatches other models around it -- supervising writes
+against an approved plan, curating handoffs across the vendor boundary, reviewing in a multi-model panel, and metering
+what all of it cost. You launch through `forge session start` instead of invoking the runtime directly. Claude sessions
+can route to a chosen provider through a local proxy; both runtimes share Forge's session state and policy model.
+
+```bash
+# Claude with session tracking (no proxy needed)
+forge session start
+
+# Route through a different provider -- --proxy takes a template name and starts it
+forge session start planner --proxy openrouter-openai
+
+# Have OpenAI's Codex police a Claude session's edits against the approved plan
+forge session fork planner -n executor -w --supervise --supervisor-runtime codex --no-launch
+```
+
+## Why Forge?
+
+Claude Code talks to Anthropic and tracks conversations. Forge adds an operational layer on top:
+
+- **Cross-Vendor Supervision** -- Bind the plan supervisor or memory writer to a different consumer lane, or select a
+  different runtime per review worker. The policy can evaluate every Write/Edit against the approved plan with a
+  read-only `codex exec`; exact repeats may reuse its short-lived verdict cache.
+- **Two Runtimes, One Session Graph** -- Claude sessions fork and resume; Codex sessions resume, and new Codex branches
+  use `forge session start --runtime codex --resume-from <parent>` to carry curated context across the boundary.
+  `forge session adopt` binds a conversation you started outside Forge.
+- **Multi-Model Routing** -- Route to GPT, Gemini, or any model via OpenRouter or LiteLLM through a local proxy. Forge
+  sets `CLAUDE_CODE_AUTO_COMPACT_WINDOW` so compaction timing matches the routed model's context window.
+- **Cost Control** -- `forge telemetry costs show` reports what each proxy actually spent; per-proxy daily and monthly
+  caps reject or warn at the ceiling. Cost is reported or marked unavailable -- never inferred from token counts.
+- **Sessions That Outlive Context** -- Named sessions persist artifacts, plans, and transcripts. When context fills up,
+  hand off to a fresh session with structured or AI-curated history you can edit before it lands.
+- **Policy, Review, and Verification** -- TDD and coding-standard bundles, semantic alignment checks, multi-model review
+  fan-out, and verification loops that keep an agent working until tests pass.
+
+### Why launch through Forge?
+
+Running `claude` directly bypasses session tracking. When you launch through Forge (`forge session start`), you get:
+
+| Feature                | `claude` directly | `forge session start`                             |
+| ---------------------- | ----------------- | ------------------------------------------------- |
+| Session tracking       | No                | Yes -- named sessions, artifacts, transcripts     |
+| Session resume         | No                | Yes -- editable handoff to fresh context          |
+| Status line            | No                | Yes -- proxy, session, policy info                |
+| Hook-driven artifacts  | No                | Yes -- plan snapshots, transcript capture         |
+| Policy enforcement     | No                | Yes -- TDD, coding standards, supervisor          |
+| Search across sessions | No                | Yes -- `forge search` indexes transcripts         |
+| Project memory         | No                | Yes -- opt-in; passported docs curated after exit |
+| Adopt an existing chat | n/a               | Yes -- `forge session adopt <conversation-id>`    |
+
+Already deep into a bare `claude` or `codex` conversation? `forge session adopt` binds it to a managed session instead
+of making you start over -- run it from the directory the conversation was launched in.
+
+## How it Works
+
+Forge sits between you and the agent runtime. It owns session state and policy, dispatches auxiliary consumers through
+persisted lane bindings, selects review workers independently per workflow, and optionally routes model traffic through
+a local proxy.
+
+```text
+You  ->  forge session  ->  Claude Code  |  Codex
+              |
+              +-- consumer lanes  -> supervisor       (claude | codex)
+              |                      memory_writer     (claude | codex)
+              |                      shadow_curation   (claude | codex)
+              |                      team_supervisor   (claude)
+              |
+              +-- workflow workers -> panel | analyze | debate | consensus
+              |                      (claude | opt-in codex)
+              |
+              +-- proxy            -> OpenRouter | LiteLLM -> any model
+              +-- state            -> artifacts, policy, telemetry
+```
+
+**Claude direct mode** (the default for Claude sessions) skips the proxy and talks to Anthropic directly; you still get
+sessions, hooks, consumer lanes, and the status line. Add `--proxy` for routing. **OpenRouter** templates call the
+OpenRouter API directly -- one API key covers Anthropic, OpenAI, Google, and more. **LiteLLM** templates route through a
+[LiteLLM](https://github.com/BerriAI/litellm) proxy, remote or a local subprocess. Twenty user-facing templates ship;
+see [docs/end-user/proxy.md](docs/end-user/proxy.md).
+
+## Requirements
+
+- **Platform**: macOS or Linux
+- **Python**: 3.11-3.13 (3.14 blocked on upstream `uvloop` wheels -- see #1)
+- **Installer**: [`uv`](https://docs.astral.sh/uv/) or [`pipx`](https://pipx.pypa.io/) for the recommended global
+  install
+- **Claude Code**: required for the default and other Claude-backed workflows; a Codex-only session or skill path does
+  not require it
+- **Codex** (optional): needed for `--runtime codex` sessions, `forge codex start`, Codex-backed consumer lanes, and the
+  opt-in Codex workflow worker. Check readiness with `forge runtime preflight codex`; proxy-routed `forge codex start`
+  needs codex >= 0.141.0.
+- **Provider auth**: Claude Code login is enough for direct interactive sessions. Proxies and headless workflows need a
+  supported API or gateway credential such as `OPENROUTER_API_KEY`, `ANTHROPIC_API_KEY`, `GEMINI_API_KEY`,
+  `OPENAI_API_KEY`, or LiteLLM auth.
+
+## Quick Start
+
+```bash
+# Install Forge as a global tool (recommended -- puts `forge` on your PATH)
+uv tool install multi-forge
+# or: pipx install multi-forge
+
+# Make uv's tool bin available in this shell and future shells
+uv tool update-shell
+export PATH="$(uv tool dir --bin):$PATH"
+
+# Confirm how forge is installed and whether it is globally reachable
+forge extension doctor
+
+# Register runtime hooks once, at user scope
+forge extension enable --scope user --profile minimal --with hooks,codex-hooks --without commands
+
+# Then, inside a project: install project-owned assets and settings
+forge extension enable
+
+# Launch Claude with session tracking (no proxy needed)
+forge session start
+
+# Or with multi-model routing -- --proxy accepts a template name and starts the proxy for you
+forge auth login -c openrouter                        # store OPENROUTER_API_KEY
+forge session start --proxy openrouter-anthropic
+```
+
+Developing on Forge itself? See [CONTRIBUTING.md](CONTRIBUTING.md) for the editable install.
+
+Once running, try `/forge:smoke-test` (Claude) or `$smoke-test` (Codex) for a read-only health check, or
+`/forge:walkthrough` for a guided tour in a sandboxed test repo.
+
+## Plan, Execute, Review
+
+A typical feature workflow assigns different model roles to planning, execution, and review. The supervisor is a *lane*,
+not a fixed model -- pin it to `codex` and a second vendor grades the first.
+
+```bash
+# 1. Plan with a high-reasoning model (--proxy takes a template; Forge starts it)
+forge session start planner --proxy openrouter-openai
+# ... Claude writes a plan, you approve it, /exit
+
+# 2. Execute in a worktree, with the policy evaluating every Write/Edit against
+#    the approved plan through read-only Codex (exact repeats may reuse its cache).
+forge runtime preflight codex                 # cache the readiness the lane reads
+forge session fork planner -n executor -w --supervise --supervisor-runtime codex --no-launch
+forge policy supervisor reload -s executor    # REQUIRED: codex has no --resume, so the
+                                              # approved plan must reach it in-band
+cd ../multi-forge-executor                    # worktrees land at ../<repo-name>-<session-name>
+forge session resume executor
+
+# 3. Context filling up? Resume fresh -- supervisor config carries over.
+forge session resume executor --fresh --strategy ai-curated
+
+# 4. Review from the planner's perspective, inside the executor's worktree
+forge session fork planner --into ../multi-forge-executor
+
+# 5. Push and open a PR
+git push origin feature-branch
+```
+
+Two prerequisites keep the Codex lane enforcing instead of failing open with a warning:
+
+- **The plan reload is mandatory.** Codex has no `--resume`, so it cannot read the planning conversation. With no plan
+  in-band, Forge fails the check open *without spawning Codex* -- it warns, it does not block. Use
+  `forge policy supervisor reload`, or `%policy supervisor reload` from inside the session.
+- **Preflight is cached, never probed during a check.** `codex doctor` is slow, but it is the probe that discovers
+  stored ChatGPT-login auth. The policy hook therefore reads the full result cached by `forge runtime preflight codex`
+  instead of rerunning it. A cold or stale cache fails open and prints a refresh hint.
+
+`forge policy supervisor status` shows the bound `(runtime, backend, model)` lane. When preflight selects stored ChatGPT
+tokens as the auth source, the check is labeled `subscription_quota` rather than Anthropic usage. Full details in
+[docs/end-user/policy.md](docs/end-user/policy.md).
+
+### Codex as a worker runtime
+
+Codex is not only an alternate frontend -- it is a runtime Forge dispatches work to:
+
+- **Other lanes.** `forge session lane set --consumer memory_writer --runtime codex` (also `shadow_curation`) moves that
+  consumer onto `codex exec`. `team_supervisor` has no Codex lane and rejects it.
+- **A whole task, seeded from a Claude parent.**
+  `forge session start impl --runtime codex --resume-from planner --task "Implement the plan."` carries curated context
+  across the vendor boundary; continue with `forge session resume impl --task "Now add tests."`.
+- **Codex TUI through a Forge proxy.** `forge codex start --proxy <id>` -- the proxy owns upstream auth, so no OpenAI
+  login is required or leaked.
+- **Capability matrix.** `forge runtime list` shows what each detected runtime supports.
+
+## Cost and Wire Control
+
+```bash
+forge telemetry costs show --period month --by-model   # authoritative proxy-scoped spend
+forge telemetry activity planner                       # what Forge's automation did in one session
+forge proxy set openrouter-openai costs.caps.per_day=20
+forge proxy set openrouter-openai costs.on_cap_hit=reject   # or 'warn' for a header-only alert
+```
+
+Caps take effect when the proxy next starts, and are enforced *after* each completed request -- one request can cross a
+cap and finish before the next is refused. `forge session start --subprocess-proxy <id>` keeps the interactive session
+on direct Anthropic routing while supervisor, panel, and memory-writer subprocesses run metered through a proxy (it is
+mutually exclusive with `--proxy`). Direct routing does not by itself guarantee subscription billing: the default
+`interactive_anthropic_api_key=inherit` passes a resolvable API key. To force the interactive process to use its Claude
+login, run `forge config set interactive_anthropic_api_key=omit`; see
+[authentication.md](docs/end-user/authentication.md#keeping-a-key-out-of-interactive-sessions-interactive_anthropic_api_key).
+
+A Forge proxy can also be an audit chokepoint. The default wire shape translates Anthropic to OpenAI and **drops
+`thinking` blocks**; the shipped `anthropic-passthrough` template forwards the raw body byte-for-byte and already ships
+`intercept.mode: inspect`, which hashes the system prompt and tool surface and flags drift when either changes
+underneath you. `forge proxy audit show|diff` renders the timeline. Records are redacted before they reach disk --
+hashes, lengths, and counts, never prompt or completion text.
+
+## Skills
+
+Nine skills compile for **both** runtimes -- Claude invokes `/forge:<name>`, Codex invokes `$<name>`: `analyze`,
+`challenge`, `consensus`, `debate`, `panel`, `review`, `review-docs`, `smoke-test`, `understand`. Only
+`/forge:walkthrough` and `/forge:qa` are Claude-only.
+
+The same runners are available from the terminal, and `--check` turns one into an exit-code gate you can script:
+
+```bash
+forge workflow panel src/forge/session/ --code   # fan a review out to several models
+forge workflow debate "Should we rewrite this in Rust?"
+forge workflow panel src/ --code --check         # exit 0 if every worker accepts, else 1
+forge workflow list-models                       # which workers are ready right now
+```
+
+See [docs/end-user/skills.md](docs/end-user/skills.md) and [docs/end-user/workflow.md](docs/end-user/workflow.md).
+
+## CLI Overview
+
+| Command Group     | Purpose                                               |
+| ----------------- | ----------------------------------------------------- |
+| `forge session`   | Named sessions, worktrees, resume, fork, adopt, lanes |
+| `forge claude`    | Bare launch, settings preset management               |
+| `forge codex`     | Codex status, proxy-routed TUI launch                 |
+| `forge runtime`   | Runtime inventory and readiness preflight             |
+| `forge proxy`     | Model routing, templates, tier mappings, wire audit   |
+| `forge model`     | Model catalog, backends, local backend lifecycle      |
+| `forge telemetry` | Costs, per-session activity, provider traces          |
+| `forge policy`    | Policy enforcement, plan supervision, shadow audit    |
+| `forge workflow`  | Workflow runners (panel, analyze, debate, consensus)  |
+| `forge memory`    | Project memory passports, shadow proposals            |
+| `forge search`    | Transcript search across sessions                     |
+| `forge auth`      | Credential management (`credentials.yaml`)            |
+| `forge config`    | Runtime preferences (`~/.forge/config.yaml`)          |
+| `forge extension` | Enable/sync/disable extensions                        |
+| `forge clean`     | Preview and remove orphaned Forge state               |
+| `forge logs`      | Log file locations and cleanup                        |
+| `forge info`      | System health and installation info                   |
+
+Run `forge <command> --help` for details on any command.
+
+## Documentation
+
+| Audience            | Location                                             | Contents                                              |
+| ------------------- | ---------------------------------------------------- | ----------------------------------------------------- |
+| **Users**           | [docs/end-user/](docs/end-user/)                     | 13 guides -- start with the Day 1 workflow            |
+| **Developers**      | [docs/developer/](docs/developer/)                   | Setup, coding standards, testing guidelines           |
+| **Architecture**    | [docs/design.md](docs/design.md)                     | Core system narrative, data flow, invariants          |
+| **Workflow design** | [docs/design_workflows.md](docs/design_workflows.md) | Policy, skills, workflow runners, memory architecture |
+| **CLI reference**   | [docs/cli_reference.md](docs/cli_reference.md)       | Terminal and direct-command inventory                 |
+| **Work Board**      | [docs/board/](docs/board/)                           | Cards, checklists, change log, implementation memory  |
+
+Common starting points: [sessions](docs/end-user/session.md), [proxies](docs/end-user/proxy.md),
+[policy and supervision](docs/end-user/policy.md), [model selection](docs/end-user/model_selection.md),
+[transfer context](docs/end-user/transfer.md), and [project memory](docs/end-user/memory.md).
+
+## Troubleshooting
+
+> [!NOTE]
+> **Corrupt state?** If Forge reports that its state is corrupt, it names the offending file and stops -- it never
+> silently runs on bad state. Run `forge clean` to preview what would be removed, then `forge clean --yes` to remove it
+> (add `--scope all` to cover every project). For a full reset, delete `.forge` (project-local) or `~/.forge` (global)
+> and re-run `forge extension enable`. Your own files and `proxy.yaml` config are never touched by `forge clean`.
+
+`forge extension doctor` reports how Forge is installed, whether the launcher is reachable, and the state of the hook
+dispatcher. Upgrading from a pre-OSS Forge install? See
+[docs/end-user/README.md](docs/end-user/README.md#upgrading-from-pre-oss-forge).
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for development setup and PR guidelines.
+
+## Uninstall
+
+```bash
+forge extension disable
+uv tool uninstall multi-forge   # or: pipx uninstall multi-forge
+```
+
+## License
+
+Apache 2.0 -- see [LICENSE](LICENSE).
+
+Originally developed as Claude Forge at [Thomson Reuters](https://github.com/thomsonreuters/claude-forge) and
+open-sourced under Apache 2.0. Continued as Multi-Forge by the original author.