aiforcecli-chat 0.1.0

package/License.MD

@@ -0,0 +1,49 @@
+# Proprietary License
+
+Copyright (c) [2026] [Apoorv Iyer]. All rights reserved.
+
+This software package, including all source code, compiled code, documentation, examples, assets, and related files, is proprietary and confidential.
+
+## License Grant
+
+You may use this software only if you have received explicit written permission from [YOUR NAME OR COMPANY NAME] or have an active paid license, subscription, or agreement that allows you to use it.
+
+Subject to that permission, you are granted a limited, non-exclusive, non-transferable, revocable license to install and use this package solely for the purposes permitted by your agreement with [YOUR NAME OR COMPANY NAME].
+
+## Restrictions
+
+You may not, without prior written permission:
+
+* copy, modify, adapt, translate, or create derivative works based on this software;
+* distribute, publish, sublicense, rent, lease, sell, resell, or otherwise transfer this software;
+* make this software available to any third party, including through a public repository, package registry, SaaS product, or hosted service;
+* reverse engineer, decompile, disassemble, or attempt to derive the source code or underlying structure of this software;
+* remove, alter, or obscure any copyright, trademark, proprietary, or license notices;
+* use this software to build a competing product or service;
+* use this software in violation of any applicable law or regulation.
+
+## No Open Source License
+
+This software is not open source. No rights are granted under any open source license. Any access to this package through npm or another package registry does not grant permission to use, copy, modify, or distribute the software except as expressly allowed by this license or a separate written agreement.
+
+## Ownership
+
+[YOUR NAME OR COMPANY NAME] retains all ownership, intellectual property rights, and proprietary rights in and to the software. No ownership rights are transferred to you.
+
+## Termination
+
+This license automatically terminates if you violate any of its terms. Upon termination, you must immediately stop using the software and delete all copies in your possession or control.
+
+## Disclaimer of Warranty
+
+This software is provided “as is” without warranties of any kind, whether express, implied, statutory, or otherwise, including but not limited to warranties of merchantability, fitness for a particular purpose, and non-infringement.
+
+## Limitation of Liability
+
+To the maximum extent permitted by law, [YOUR NAME OR COMPANY NAME] shall not be liable for any indirect, incidental, special, consequential, exemplary, or punitive damages, or for any loss of profits, revenue, data, goodwill, or business opportunities arising out of or related to the use of this software.
+
+## Contact
+
+For licensing inquiries, contact:
+
+[apoorviy@hcltech.com]

package/README.md

@@ -0,0 +1,642 @@
+# aiforcecli-chat
+
+Version: 0.1.0
+
+One CLI over multiple coding agents, with routing, verification, racing, local learning, and cost controls.
+
+`aiforcecli-chat` does not reimplement an agent or host models. It shells out to the agent CLIs you already have installed and authenticated, normalizes their output, records cost/outcomes locally, and uses your repo's tests as the objective signal for choosing what to trust.
+
+## What It Wraps
+
+Built-in adapters:
+
+| Agent id | CLI | What it supports |
+| --- | --- | --- |
+| `claude-code` | `claude` | Claude Code via `-p --output-format stream-json`; parses usage/cost from the CLI; supports session resume. |
+| `codex` | `codex` | OpenAI Codex via `codex exec --json`; parses JSONL events; computes cost from token usage; supports thread resume. |
+| `aider` | `aider` | Aider one-shot mode; model-agnostic through Aider's `--model`; parses Aider's token/cost summary when present. |
+| `antigravity` | `agy` | Google's Antigravity/Gemini CLI through `agy -p`; runs under a pseudo-terminal because output is TUI-oriented; no token/cost reporting from the CLI. |
+
+Each adapter implements the same contract: detect whether the CLI exists, run a prompt in a working directory, stream normalized events, and optionally resume an existing session.
+
+## Why Use It
+
+The product is built around a simple workflow:
+
+1. Use `advise` before spending money to choose an agent/model.
+2. Use `run --heal` when you want one agent to fix, verify, retry, and escalate.
+3. Use `race` when quality matters: run multiple agents in isolated git worktrees, verify each result, and apply the passing winner.
+4. Use `pr` when you want a complete branch -> verify -> commit -> push -> GitHub pull request workflow.
+5. Use `bench` and `eval` to learn which agent/model actually works on your repo.
+6. Use `cost` and budgets to avoid bill shock.
+
+The strongest differentiator is that `aiforcecli-chat` is horizontal: it compares and governs several coding agents instead of locking you into one.
+
+## Quickstart
+
+Install the wrapper:
+
+```bash
+npm install -g aiforcecli-chat
+```
+
+Install at least one underlying agent CLI:
+
+```bash
+npm install -g @anthropic-ai/claude-code
+npm install -g @openai/codex
+python -m pip install aider-chat
+```
+
+Antigravity uses Google's `agy` binary; install and authenticate it through Google's current Antigravity distribution.
+
+Check what is available:
+
+```bash
+aiforcecli-chat agents
+aiforcecli-chat models
+```
+
+Scaffold project config:
+
+```bash
+cd my-project
+aiforcecli-chat init
+```
+
+Run a task:
+
+```bash
+aiforcecli-chat run "add a health check endpoint and a test for it"
+```
+
+Run a verified healing loop:
+
+```bash
+aiforcecli-chat run "fix the failing auth test" --heal --verify "npm test"
+```
+
+Race multiple agents:
+
+```bash
+aiforcecli-chat race "fix the failing tests" --agents claude-code,codex --verify "npm test" --select cheapest
+```
+
+Create a tested GitHub pull request:
+
+```bash
+aiforcecli-chat pr "add input validation to the signup form" --agent codex --model gpt-5.4-mini --heal
+```
+
+See spend:
+
+```bash
+aiforcecli-chat cost
+```
+
+## Commands
+
+| Command | Summary |
+| --- | --- |
+| `aiforcecli-chat run "<task>"` | Run a coding task. Without `--agent`, auto-routes to an agent/model. Supports `--agent`, `--model`, `--cwd`, `--budget`, `--resume`, `--explain`, `--json`, `--heal`, `--max-attempts`, `--verify`, `--skip-verify`, `--route deterministic|bayesian`, `--explore`, and `--no-explore`. |
+| `aiforcecli-chat advise "<task>"` | Recommend an agent/model without running an agent. Supports `--cwd`, `--budget`, `--explore`, and `--json`. |
+| `aiforcecli-chat scorecard update` | Manually fetch public benchmark leaderboards and generate local public-prior scorecard artifacts. |
+| `aiforcecli-chat pr "<task>"` | Run a task on a new branch, verify it, commit, push, and open a GitHub pull request. Supports `--agent`, `--model`, `--cwd`, `--budget`, `--branch`, `--base`, `--title`, `--body`, `--commit-message`, `--remote`, `--draft`, `--no-push`, `--no-pr`, `--allow-dirty`, `--heal`, `--max-attempts`, `--verify`, `--skip-verify`, `--route`, `--explore`, and `--no-explore`. |
+| `aiforcecli-chat race "<task>"` | Run several agents in parallel in isolated git worktrees, verify each, and apply the winner. Supports `--agents`, `--cwd`, `--budget`, `--select cheapest|fastest|first-pass`, `--verify`, `--keep`, and `--json`. |
+| `aiforcecli-chat eval` | Run private eval cases against installed agent/model targets to calibrate `advise`. Supports `--cwd`, `--dir`, `--agents`, and `--json`. |
+| `aiforcecli-chat bench` | Local leaderboard from recorded outcomes. Supports `--since`, `--by-task`, `--clean`, and `--json`. |
+| `aiforcecli-chat models` | Show the built-in plus config-added model catalog, tiers, prices, install status, and `routing.only` allow-list status. Supports `--json`. |
+| `aiforcecli-chat agents` | Show agent install status. Supports `--enable <id>`, `--disable <id>`, and `--json`. |
+| `aiforcecli-chat cost` | Report spend by `day`, `agent`, or `project`. Supports `--since`, `--by day|agent|project`, and `--json`. |
+| `aiforcecli-chat init` | Write `aiforcecli.config.json` and install bundled assets. Supports `--cwd` and `--force`. |
+| `aiforcecli-chat mcp` | Command is reserved for Phase 3. In 0.1.0 it is a stub and exits with a not-implemented message. |
+
+## Public Prior Scorecard
+
+Bayesian `advise`, `run --route bayesian`, chat auto-routing, and `pr --route bayesian` use the generated public-prior scorecard by default. Refresh it manually:
+
+```bash
+aiforcecli-chat scorecard update
+```
+
+The generated scorecard is stored under the installed package at `tools/scorecard/generated/scorecard/scorecard.json`. If it is unavailable, routing falls back to the bundled static scorecard.
+
+## Architecture
+
+```text
+CLI
+  commands: run, advise, pr, race, eval, bench, models, agents, cost, init, mcp
+  adapters: claude-code, codex, aider, antigravity
+  routing: catalog, classifier, deterministic router
+  advise: task analysis, public scorecard, private stats, scorer, bandit policy
+  core: orchestrator, subprocess runner, worktree isolation, race, heal
+  verify: test command detection and execution
+  finops: SQLite usage store, budgets, pricing, telemetry
+```
+
+Adapters normalize native agent output into this event shape:
+
+```ts
+type NormalizedEvent =
+  | { type: 'token'; text: string }
+  | { type: 'message'; role: 'assistant' | 'user'; text: string }
+  | { type: 'tool_call'; name: string; input?: unknown; id?: string }
+  | { type: 'usage'; usage: Usage; cumulative: boolean }
+  | { type: 'error'; message: string; fatal: boolean };
+```
+
+A finished run resolves to message, usage, exit code, optional session/thread id, and abort metadata.
+
+## Model Catalog
+
+`aiforcecli-chat models` displays the catalog used for routing estimates and recommendations.
+
+Built-in catalog in 0.1.0:
+
+| Key | Agent | Model | Tier |
+| --- | --- | --- | --- |
+| `claude-haiku` | `claude-code` | `haiku` | light |
+| `claude-sonnet` | `claude-code` | `sonnet` | standard |
+| `claude-opus` | `claude-code` | `opus` | heavy |
+| `claude-fable` | `claude-code` | `fable` | heavy |
+| `codex-gpt-5.4-mini` | `codex` | `gpt-5.4-mini` | light |
+| `codex-gpt-5.4` | `codex` | `gpt-5.4` | standard |
+| `codex-gpt-5.5` | `codex` | `gpt-5.5` | heavy |
+| `aider-deepseek` | `aider` | `deepseek` | standard |
+| `aider-codestral` | `aider` | `codestral/codestral-latest` | standard |
+| `gemini-3-flash` | `antigravity` | `gemini-3-flash` | light |
+| `gemini-3.5-flash` | `antigravity` | `gemini-3.5-flash` | standard |
+| `gemini-3.1-pro` | `antigravity` | `gemini-3.1-pro` | heavy |
+
+You can restrict routing with `routing.only` and add or override catalog entries with `routing.models`.
+
+Example:
+
+```json
+{
+  "routing": {
+    "only": ["claude-sonnet", "codex-gpt-5.4-mini"],
+    "models": [
+      {
+        "key": "codex-mini",
+        "agent": "codex",
+        "model": "gpt-5.4-mini",
+        "tier": 1,
+        "price": { "input": 0.1875, "output": 1.13 }
+      }
+    ]
+  }
+}
+```
+
+Prices are USD per 1M tokens and are used for estimates. Runtime cost uses the agent CLI's reported cost when available; otherwise it is computed from the local pricing table.
+
+Claude Fable is exposed through Claude Code as `--model fable` and is treated as a heavy-tier option. Its estimate is `$10` input / `$50` output per 1M tokens, so it is best reserved for harder refactors, architecture work, security-sensitive changes, and complex PRs rather than small edits.
+
+## Routing
+
+When `run` is called without `--agent`, `aiforcecli-chat` routes the task.
+
+Routing strategies:
+
+| Strategy | Behavior |
+| --- | --- |
+| `deterministic` | Default. Classifies the prompt as light, standard, or heavy with keyword/length heuristics, estimates candidate costs, and picks the cheapest model that meets the desired tier within the effective budget. |
+| `bayesian` | Uses the same learned recommendation pipeline as `advise`: public priors plus private verified outcomes, with optional Thompson-sampling exploration. |
+
+Effective budget is the tightest of:
+
+- `--budget`
+- `budgets.maxCostPerRunUsd`
+- remaining `dailyCapUsd`
+- remaining `weeklyCapUsd`
+- remaining `monthlyCapUsd`
+
+Explicit `--agent` always wins. Explicit `--model` overrides the routed or configured model.
+
+Examples:
+
+```bash
+aiforcecli-chat run "fix a typo in the README"
+aiforcecli-chat run "refactor the auth architecture" --budget 5 --explain
+aiforcecli-chat run "fix the cache bug" --route bayesian --explore
+aiforcecli-chat run "add validation" --agent codex --model gpt-5.4-mini
+aiforcecli-chat pr "redesign the calculator architecture" --agent claude-code --model fable --branch fable-refactor --base dev-ai-base
+```
+
+## Advise
+
+`advise` is a no-run recommendation engine:
+
+```bash
+aiforcecli-chat advise "migrate auth from sessions to JWT" --budget 2
+```
+
+It produces:
+
+- task type: `bugfix`, `feature`, `refactor`, `test`, `docs`, `security`, `perf`, or `general`
+- complexity tier: light, standard, or heavy
+- codebase scan: top languages and file count
+- test detection
+- budget headroom
+- ranked agent/model recommendations
+- confidence, expected cost, estimated capability, and reasons
+- policy mix: how often each arm would be selected under Thompson sampling
+
+Scoring:
+
+```text
+capability = posterior(public prior, private pass/fail history)
+score = wCapability * capability + wCost * costFit + wSpeed * speedFit
+```
+
+Defaults:
+
+```json
+{
+  "advise": {
+    "weights": { "capability": 0.7, "cost": 0.2, "speed": 0.1 },
+    "privatePseudocount": 5,
+    "explore": false
+  }
+}
+```
+
+The public scorecard is a dated, curated prior. Your verified `heal`, `race`, and `eval` outcomes override it as data accumulates.
+
+## Race
+
+`race` is the high-trust workflow:
+
+```bash
+aiforcecli-chat race "fix the failing checkout test" --agents claude-code,codex --verify "npm test" --select cheapest
+```
+
+What happens:
+
+1. Finds the local git repo root from `--cwd` or the current directory.
+2. Captures tracked and untracked dirty changes.
+3. Creates one detached temp git worktree per agent.
+4. Carries your current changes into each worktree and commits them as that worktree's base.
+5. Runs each agent independently.
+6. Runs the verify command in each worktree.
+7. Selects a passing non-empty diff by `cheapest`, `fastest`, or `first-pass`.
+8. Applies the winner's diff back to your real working tree.
+9. Records outcome, cost, duration, task class/type, reward, and winner flag.
+
+Requirements:
+
+- The target directory must be inside a git repo.
+- The repo must have at least one commit, because worktrees are created from `HEAD`.
+- A verify command is strongly recommended. Without one, `race` cannot objectively pick a winner and only offers manual selection in an interactive terminal.
+
+Budget behavior:
+
+- `--budget` is the total race budget.
+- It is split evenly across racers.
+
+Model behavior:
+
+- `race --agents` accepts agent ids, not per-agent model syntax.
+- To race specific models, set `agents.<id>.model` in config.
+
+Example:
+
+```json
+{
+  "agents": {
+    "claude-code": { "model": "sonnet" },
+    "codex": { "model": "gpt-5.4-mini" }
+  }
+}
+```
+
+Then:
+
+```bash
+aiforcecli-chat race "fix the discount bug" --agents claude-code,codex --verify "npm test"
+```
+
+Dependency links:
+
+- `node_modules` is linked into worktrees automatically when present.
+- Add other gitignored dependency/build directories with `race.linkPaths`, for example `.venv`, `target`, or `vendor`.
+- Cleanup severs symlinks/junctions before removing worktrees to avoid deleting through dependency links.
+
+## PR Mode
+
+`pr` is the one-command workflow for turning an AI task into a normal GitHub pull request:
+
+```bash
+aiforcecli-chat pr "fix the checkout timeout bug" --agent codex --model gpt-5.4 --heal
+```
+
+What happens:
+
+1. Requires a clean git working tree by default so AI edits do not mix with existing local work.
+2. Creates a new branch, or uses `--branch <name>`.
+3. Runs the selected or routed agent on the task.
+4. Runs final verification if a verify command is available.
+5. Commits the change when verification passes.
+6. Pushes the branch to the configured remote.
+7. Opens a GitHub pull request with the GitHub CLI (`gh`).
+
+Useful examples:
+
+```bash
+aiforcecli-chat pr "add a contact form" --branch ai-contact-form
+aiforcecli-chat pr "fix the parser bug" --heal --verify "npm test"
+aiforcecli-chat pr "update the About page copy" --no-push
+aiforcecli-chat pr "prepare a docs-only change" --skip-verify --draft
+aiforcecli-chat pr "push a branch but do not open a PR" --no-pr
+```
+
+Requirements:
+
+- The target directory must be inside a git repo.
+- Start from a clean working tree unless you intentionally pass `--allow-dirty`.
+- `gh` must be installed and authenticated to open the PR automatically.
+- If `gh` is unavailable, the branch is still pushed and the command prints the `gh pr create` command to run later.
+
+## Self-Healing Runs
+
+`run --heal` turns a single agent run into a verify/fix/escalate loop:
+
+```bash
+aiforcecli-chat run "fix the failing parser test" --heal --verify "npm test"
+```
+
+Loop:
+
+1. Run selected agent/model.
+2. Run verify command.
+3. If passed, stop.
+4. If failed and the adapter supports resume, retry the same agent with the verify failure output.
+5. If still failing and escalation is enabled, select a stronger untried catalog entry.
+6. Stop on pass, budget breach, or `heal.maxAttempts`.
+
+Config:
+
+```json
+{
+  "heal": {
+    "enabled": false,
+    "maxAttempts": 3,
+    "escalate": true
+  }
+}
+```
+
+`--heal` edits the real working tree by design. Use `race` when you want isolated candidates.
+
+## Verification
+
+Verification resolves in this order:
+
+1. `--verify "<cmd>"`
+2. `verify.command` in config
+3. auto-detection, if `verify.enabled` is true
+
+Auto-detected commands include:
+
+- `npm test`, `pnpm test`, or `yarn test` when `package.json` has a `test` script
+- `pytest`
+- `cargo test`
+- `go test ./...`
+- `bundle exec rake test`
+- `mvn test`
+- `gradle test`
+
+The verify command runs through a shell, has a timeout, returns pass/fail, and captures the tail of output for healing.
+
+## Eval And Bench
+
+`eval` runs a private suite of representative cases against candidate agent/model pairs.
+
+Case example:
+
+```json
+{
+  "prompt": "fix the off-by-one in parseRange",
+  "verify": "npm test",
+  "taskType": "bugfix"
+}
+```
+
+Run:
+
+```bash
+aiforcecli-chat eval
+aiforcecli-chat eval --agents claude-code,codex
+```
+
+Targets come from `eval.models` or all installed agents' catalog entries. Each trial runs in an isolated worktree and records outcomes for `advise` and `bench`.
+
+`bench` shows local history:
+
+```bash
+aiforcecli-chat bench
+aiforcecli-chat bench --by-task
+aiforcecli-chat bench --since 7d
+aiforcecli-chat bench --clean
+```
+
+`--clean` hides zero-signal rows such as typoed/retired model ids or unverified runs with no cost/pass/win signal.
+
+Note: the current CLI command does not expose a project filter for `bench`; reports are from the local usage database.
+
+## FinOps And Budgets
+
+Every recorded run stores:
+
+- timestamp
+- agent and model
+- project path
+- prompt hash
+- input/output/cache tokens
+- cost and cost source
+- exit code and abort reason
+- mode: `run`, `heal`, `race`, or `eval`
+- outcome: `pass`, `fail`, or `unknown`
+- duration
+- task class/type
+- race winner flag
+- learning context, propensity, and reward when available
+
+Cost source:
+
+- Claude Code reports cost directly; that is trusted.
+- Codex reports tokens; cost is computed from local prices.
+- Aider cost is parsed from Aider's summary line when present.
+- Antigravity currently reports no usage/cost in this integration, so recorded cost may be zero even though the underlying service may charge separately.
+
+Budget controls:
+
+```json
+{
+  "budgets": {
+    "maxCostPerRunUsd": 1.0,
+    "dailyCapUsd": 10.0,
+    "weeklyCapUsd": 50.0,
+    "monthlyCapUsd": 150.0
+  }
+}
+```
+
+Window caps are checked before starting a run. Per-run caps are enforced during a run when usage events arrive. For agents that only report usage at the end, mid-run enforcement is best effort.
+
+Cost reports:
+
+```bash
+aiforcecli-chat cost
+aiforcecli-chat cost --since 24h
+aiforcecli-chat cost --by agent
+aiforcecli-chat cost --by project --json
+```
+
+## Telemetry
+
+Telemetry is opt-in and off by default.
+
+When enabled with `telemetry.enabled` and `telemetry.endpoint`, it sends only coarse anonymized outcome fields:
+
+- task class
+- agent
+- model
+- outcome
+- winner flag
+- mode
+- cost
+- duration
+
+It does not send prompts, prompt hashes, project paths, or output. Upload is fire-and-forget with a short timeout and never blocks a run.
+
+In 0.1.0 telemetry is a primitive upload hook, not a hosted shared leaderboard.
+
+## Configuration
+
+Config files are deep-merged:
+
+1. user-level config
+2. project-level `aiforcecli.config.json` or `aiforcecli.config.ts`
+3. CLI flags
+
+User-level paths:
+
+| Platform | Path |
+| --- | --- |
+| Windows | `%APPDATA%\aiforcecli\Config\aiforcecli.config.json` |
+| macOS | `~/Library/Preferences/aiforcecli/aiforcecli.config.json` |
+| Linux | `~/.config/aiforcecli/aiforcecli.config.json` or `$XDG_CONFIG_HOME` |
+
+Schema summary:
+
+| Block | Keys | Purpose |
+| --- | --- | --- |
+| `agents.<id>` | `enabled`, `model`, `bin`, `defaultFlags`, `allowedTools` | Per-agent settings. `enabled:false` removes the agent from registry/routing/race/eval/listing. |
+| `defaultAgent` | string | Agent used when routing is disabled and no explicit agent is passed. |
+| `routing` | `enabled`, `strategy`, `prefer`, `only`, `models` | Auto-routing behavior and model catalog customization. |
+| `verify` | `enabled`, `command`, `timeoutMs` | Verification command resolution and timeout. |
+| `heal` | `enabled`, `maxAttempts`, `escalate` | Self-healing behavior. |
+| `race` | `agents`, `select`, `keepWorktrees`, `linkPaths` | Race defaults, winner selection, worktree retention, dependency links. |
+| `advise` | `weights`, `privatePseudocount`, `explore` | Recommendation scoring and exploration. |
+| `eval` | `dir`, `models` | Private eval suite location and catalog target keys. |
+| `telemetry` | `enabled`, `endpoint` | Opt-in anonymized upload. |
+| `budgets` | `maxCostPerRunUsd`, `dailyCapUsd`, `weeklyCapUsd`, `monthlyCapUsd` | Cost caps. |
+| top-level | `timeoutMs`, `inactivityTimeoutMs` | Agent subprocess watchdogs. |
+
+Enable or disable built-in agents globally:
+
+```bash
+aiforcecli-chat agents --disable antigravity
+aiforcecli-chat agents --enable aider
+```
+
+These toggles write to the user-level config.
+
+## `init`
+
+`aiforcecli-chat init` writes a project config and installs bundled assets when present:
+
+- `assets/skills` -> `.claude/skills`
+- `assets/subagents` -> `.claude/agents`
+- `assets/prompts` -> `.aiforcecli/prompts`
+
+Use `--force` to overwrite an existing project config:
+
+```bash
+aiforcecli-chat init --force
+```
+
+## Known Limitations
+
+- `aiforcecli-chat mcp` is not implemented in 0.1.0.
+- `race` and `eval` require a git repo with a commit because they use git worktrees.
+- Verification quality depends on the repo's tests/build command.
+- Task classification is heuristic and keyword-based.
+- The public scorecard is curated and dated, not live.
+- New or custom models without scorecard rows start from a neutral prior until private evidence accumulates.
+- `pr` needs the GitHub CLI (`gh`) installed and authenticated to open pull requests automatically.
+- Some agent fatal errors can still look like no-change/no-usage outcomes in `race` or `eval`; inspect output and use `--keep` when debugging.
+- Codex model availability can differ by account type; configure `routing.only` or `agents.codex.model` to match what your local Codex CLI accepts.
+- Antigravity usage/cost is not reported by the CLI in this integration.
+- Mid-run budget enforcement is best effort for agents that only emit usage at the end.
+- `bench` currently reports from the local global usage DB; there is no CLI `--project` filter yet.
+
+## Development
+
+```bash
+npm install
+npm run build
+npm run typecheck
+npm test
+```
+
+Build:
+
+- TypeScript is bundled with `tsup`.
+- `npm run build` runs `tsup` and then `scripts/obfuscate.mjs`.
+- `npm run build:raw` runs `tsup` only.
+
+Tests cover:
+
+- adapter parsers
+- routing
+- recommendation scoring
+- bandit policy
+- reward
+- budget enforcement
+- SQLite store
+- verify detection
+- worktree isolation
+- self-healing policy
+- race selection
+- PR command helpers
+- command helpers
+
+Recorded fixtures live under `test/fixtures`.
+
+## Roadmap
+
+Shipped in 0.1.0:
+
+- adapters for Claude Code, Codex, Aider, and Antigravity
+- config loading/schema
+- model catalog and `models` command
+- deterministic and bayesian routing
+- `run`, `run --heal`, `pr`, `race`, `advise`, `eval`, `bench`, `cost`, `agents`, `init`
+- local SQLite usage/outcome store
+- budgets and cost reporting
+- opt-in telemetry hook
+- worktree isolation for race/eval
+- contextual-bandit recommendation policy and off-policy logging fields
+
+Next:
+
+- clearer fatal error surfacing in `race` and `eval`
+- richer task classification
+- Codex model compatibility auto-detection
+- learned route/escalation policy from logged context/action/reward/propensity
+- project-scoped `bench` filtering
+- real MCP server with auth and budget-capped tools
+- hosted or federated aggregate leaderboard