dual-brain 6.0.0 → 6.0.1

package/CLAUDE.md

@@ -2,38 +2,49 @@
 
 This project uses dual-provider orchestration. Config: `.claude/orchestrator.json`.
 
-## Tier Routing
+## Core Architecture (v6)
 
-Route subagents by task complexity:
+Four modules in `src/` form the decision pipeline:
 
-- **Search** (`model: "haiku"`): Read-only lookups, grep, explore. Return: files found, line refs, confidence.
-- **Execute** (`model: "sonnet"`): Edits, tests, git ops. Return: files changed, tests run, edge cases.
-- **Think** (main session, Opus): Architecture, review, planning. Return: decision, alternatives, risks.
+- **`profile.mjs`** — Load active profile, provider availability, preferences, and subscription plan
+- **`detect.mjs`** — Classify task intent, risk, complexity, and tier from prompt + file paths
+- **`decide.mjs`** — Route to provider/model/tier; handles budget pressure and dual-brain threshold
+- **`dispatch.mjs`** — Execute the decision: Claude subagent, GPT via Codex, or dual-brain flow
+
+The hooks layer (`/home/runner/workspace/.claude/hooks/`) wraps these modules for Claude Code integration and is still valid.
+
+## CLI Commands
 
-## GPT Lane
+```bash
+dual-brain init                        # First-time setup
+dual-brain go "task description"       # Detect → decide → dispatch
+dual-brain go --dry-run "..."          # Show routing without executing
+dual-brain go --files a.mjs,b.mjs "..." # Provide file context for risk classification
+dual-brain status                      # Provider health, budget pressure, models
+dual-brain remember "preference"       # Save project-scoped preference
+dual-brain forget "preference"         # Remove preference by fuzzy match
+```
 
-For isolated or parallel work, dispatch to GPT via Codex CLI:
+## Tier Routing
 
-- `node .claude/hooks/gpt-work-dispatcher.mjs --task "..." --model gpt-5.4` — execution tasks
+- **Search** (`haiku`): Read-only lookups, grep, explore. Return: files found, line refs, confidence.
+- **Execute** (`sonnet`): Edits, tests, git ops. Return: files changed, tests run, edge cases.
+- **Think** (main session, Opus): Architecture, review, planning. Return: decision, alternatives, risks.
 
 ## Dual-Brain Collaboration
 
 Dual-brain is a multi-round conversation between Claude and GPT — not a single-shot dispatch.
 
 **Think flow** (architecture decisions):
-1. Round 1: `node .claude/hooks/dual-brain-think.mjs --question "..."`
-   → GPT gives independent analysis
+1. Round 1: `node .claude/hooks/dual-brain-think.mjs --question "..."` → GPT gives independent analysis
 2. You analyze the same question independently
-3. Round 2: `node .claude/hooks/dual-brain-think.mjs --question "..." --round 2 --claude-says "<your analysis>"`
-   → GPT responds to your points: agreements, pushback, refined recommendation
+3. Round 2: `node .claude/hooks/dual-brain-think.mjs --question "..." --round 2 --claude-says "<your analysis>"` → GPT responds with agreements, pushback, refined recommendation
 4. You synthesize both rounds into a final decision
 
 **Review flow** (code review):
-1. Round 1: `node .claude/hooks/dual-brain-review.mjs`
-   → GPT reviews the diff independently
+1. Round 1: `node .claude/hooks/dual-brain-review.mjs` → GPT reviews the diff independently
 2. You review the same diff independently
-3. Round 2: `node .claude/hooks/dual-brain-review.mjs --round 2 --claude-review "<your findings>"`
-   → GPT confirms shared findings, acknowledges misses, disputes false positives
+3. Round 2: `node .claude/hooks/dual-brain-review.mjs --round 2 --claude-review "<your findings>"` → GPT confirms shared findings, acknowledges misses
 4. You synthesize into a final review verdict
 
 ## Routing Rules
@@ -47,20 +58,15 @@ Dual-brain is a multi-round conversation between Claude and GPT — not a single
 
 **Claude MUST follow these rules before implementing multi-file changes:**
 
-1. **Before starting any batch of 3+ file edits**: run `node .claude/hooks/budget-balancer.mjs` and `node .claude/hooks/vibe-router.mjs "description"` to check provider balance and classify tasks
-2. **When budget-balancer recommends GPT**: dispatch execution work via `node .claude/hooks/gpt-work-dispatcher.mjs --task "..." --tier execute`
+1. **Before starting any batch of 3+ file edits**: run `node .claude/hooks/budget-balancer.mjs` to check provider balance, then `dual-brain go --dry-run "description"` to classify tasks
+2. **When budget-balancer recommends GPT**: dispatch via `src/dispatch.mjs` (or `node .claude/hooks/gpt-work-dispatcher.mjs --task "..." --tier execute`)
 3. **Security/auth/credential changes**: always require dual-brain think flow before implementation
 4. **Audit remediation batches**: plan waves with dual-brain think, dispatch execution to GPT, Claude reviews
 5. **Claude's role in multi-task work**: define acceptance criteria, dispatch agents, review results — not solo-implement everything
 
-**Triggers that require this workflow:**
-- 3+ production files being edited in one session
-- Any change touching auth, credentials, tokens, or secrets
-- Any change to dispatcher, agent routing, or tier logic
-- Audit or review remediation involving multiple subsystems
-- When Claude's think capacity is above 60% per budget-balancer
+**Triggers that require this workflow:** 3+ production files edited in one session · auth/credentials/tokens/secrets · changes to dispatcher, agent routing, or tier logic · audit remediation across multiple subsystems · Claude think capacity above 60% per budget-balancer.
 
-**Failure to route is itself a bug.** If Claude implements a large batch solo when GPT has capacity, the user should treat this as a process failure and correct it.
+**Failure to route is itself a bug.**
 
 ## Quality Gate
 
@@ -72,91 +78,60 @@ Gate statuses: `pass` (safe to end), `issues_found` (fix first), `needs_human_re
 
 ## Profiles
 
-Active profile controls routing posture, budgets, and quality gate behavior.
 Profile persists to `.claude/dual-brain.profile.json` (gitignored).
 
-- **auto** (default): Adapts routing based on task risk, provider health, and outcomes. Uses file-path risk classification and failure-loop detection to auto-escalate when needed.
+- **auto** (default): Adapts routing based on task risk, provider health, and outcomes
 - **balanced**: Best model per tier, normal budgets, reviews at medium+ risk
 - **cost-saver**: Prefer cheaper models, lower budgets, skip GPT for non-critical
 - **quality-first**: Dual-brain for medium+ risk, higher budgets, stricter reviews
 
-Switch profiles: `npx dual-brain mode cost-saver`
-Check status: `npx dual-brain status`
-
-Natural language aliases work everywhere: "go aggressive", "be careful", "cheap mode", "fast", "thorough", "smart". The system strips prefixes like "go"/"be"/"use" and resolves to the canonical profile name.
+Switch: `dual-brain mode cost-saver` · Natural language aliases work: "be careful", "cheap mode", "thorough"
 
 ## Adaptive Routing (Auto Mode)
 
-Auto mode classifies risk from file paths and adjusts routing in real-time:
-
 - **Risk classification**: auth/secrets→critical, billing/migrations→high, tests/utils→medium, docs→low
-- **Failure detection**: 2+ failures on same prompt in 2 hours → auto-escalate tier or trigger dual-brain. Uses time-weighted decay (recent failures count more) and ledger pruning for entries >24hrs.
+- **Failure detection**: 2+ failures on same prompt in 2 hours → auto-escalate tier or trigger dual-brain
 - **Provider balance**: Routes to underused provider when one subscription is hot
-- **Burst awareness**: Suppresses duplicate warnings and balance hints during agent waves (3+ agents in 90s)
+- **Burst awareness**: Suppresses duplicate warnings during agent waves (3+ agents in 90s)
 
-## Vibe Coding
+## Budget Balancer
 
-Casual natural language → structured work. The vibe coding system translates informal requests into properly routed, risk-classified, quality-gated work.
+`src/decide.mjs` handles routing decisions using the same token data internally. For inspection:
 
-**Wave Orchestrator** — the primary way to run multi-step work:
 ```bash
-node .claude/hooks/wave-orchestrator.mjs "fix the login bug and update the nav"
-node .claude/hooks/wave-orchestrator.mjs --dry-run "refactor auth module"
-node .claude/hooks/wave-orchestrator.mjs --resume <manifestId>
-node .claude/hooks/wave-orchestrator.mjs --show <manifestId>
-```
-The wave orchestrator decomposes intent, plans dependency-aware waves, assigns file ownership to prevent conflicts, dispatches agents with transparent routing tables, checkpoints between waves, and supports resume on failure. Every dispatch shows: provider, model, tier, effort, agent type, and routing reason.
-
-Manifests persist to `.dualbrain/manifests/`, checkpoints to `.dualbrain/checkpoints/`.
-
-Also available via the control panel: `[w]` Vibe workflow.
-
-**Intent compiler** — decompose multi-task requests:
-```bash
-node .claude/hooks/vibe-router.mjs "fix the login bug and also update the nav"
-```
-Returns structured tasks with tier/risk classification, complexity level, quality gates, and wave strategy.
-
-**Plan generator** — Steve-style 3-part markdown plans:
-```bash
-node .claude/hooks/plan-generator.mjs --utterance "..." [--write]
-```
-Generates: (1) dependency-ordered task table, (2) user stories + edge cases, (3) questions with suggested answers. Pass `--write` to save to `.claude/plans/`.
-
-**Durable memory** — preferences persist across sessions:
-```bash
-node .claude/hooks/vibe-memory.mjs                              # show state
-node .claude/hooks/vibe-memory.mjs --set preferences.risk_tolerance=careful
-node .claude/hooks/vibe-memory.mjs --threads                    # active work
-node .claude/hooks/vibe-memory.mjs --infer                      # preference suggestions
+node .claude/hooks/budget-balancer.mjs
 ```
-Tracks preferred profile, risk tolerance, active threads, and learns from usage patterns.
-
-## Budget Balancer (Token-Based)
 
-The budget balancer tracks real token usage against actual subscription limits.
+Tracks 5-hour and 7-day rolling windows against subscription limits (Claude Pro/Max, ChatGPT Plus/Pro). The higher pressure window is the binding constraint. Uses actual `input_tokens + output_tokens` from usage logs.
 
 **Subscription tiers** (configured in `orchestrator.json` → `subscriptions.*.plan`):
 - Claude: Pro $20, Max x5 $100, Max x20 $200
 - ChatGPT: Plus $20, Pro $100, Pro $200
 
-**Two rolling windows**: 5-hour and 7-day weekly. The higher pressure is the binding constraint.
+## Multi-Step Work
 
-**Token tracking**: Uses actual `input_tokens + output_tokens` from usage logs when available, falls back to conservative estimates only when logs lack token data.
+The wave orchestrator is available for complex multi-step tasks:
 
 ```bash
-node .claude/hooks/budget-balancer.mjs
+node .claude/hooks/wave-orchestrator.mjs "fix the login bug and update the nav"
+node .claude/hooks/wave-orchestrator.mjs --dry-run "refactor auth module"
+node .claude/hooks/wave-orchestrator.mjs --resume <manifestId>
 ```
-Shows per-provider per-tier pressure with real token counts (e.g., `136.0K/350.0K`), weekly pressure when binding, and routing recommendation with reason.
+
+For most tasks, prefer `dual-brain go "..."` — it runs the same detect→decide→dispatch pipeline with less overhead.
 
 ## Available Tools
 
-- `node .claude/hooks/wave-orchestrator.mjs "..."` — auto-wave orchestrator (plan, dispatch, test, review)
-- `node .claude/hooks/vibe-router.mjs "..."` — decompose casual requests into structured work
-- `node .claude/hooks/plan-generator.mjs --utterance "..."` — generate execution plans
-- `node .claude/hooks/vibe-memory.mjs` — persistent preferences and work threads
-- `node .claude/hooks/cost-report.mjs` — activity and cost estimates
-- `node .claude/hooks/health-check.mjs` — verify system health
-- `node .claude/hooks/budget-balancer.mjs` — provider balance (token-based, real limits)
-- `node .claude/hooks/decision-ledger.mjs` — routing outcome insights
-- `node .claude/hooks/test-orchestrator.mjs` — run self-tests (40 tests)
+| Tool | Purpose |
+|------|---------|
+| `dual-brain go "..."` | Primary entry point: detect, decide, dispatch |
+| `dual-brain status` | Provider health, budget, models |
+| `node .claude/hooks/budget-balancer.mjs` | Token usage and routing recommendation |
+| `node .claude/hooks/dual-brain-think.mjs` | Multi-round architecture decisions with GPT |
+| `node .claude/hooks/dual-brain-review.mjs` | Multi-round code review with GPT |
+| `node .claude/hooks/wave-orchestrator.mjs "..."` | Dependency-aware multi-wave dispatch |
+| `node .claude/hooks/session-report.mjs` | End-of-session summary |
+| `node .claude/hooks/quality-gate.mjs` | Gate check before ending session |
+| `node .claude/hooks/health-check.mjs` | System health |
+| `node .claude/hooks/test-orchestrator.mjs` | Self-tests (40 tests) |
+| `node .claude/hooks/vibe-memory.mjs` | Persistent preferences across sessions |

package/README.md

@@ -1,133 +1,197 @@
-# Dual-Brain Orchestrator
+# dual-brain
 
-One command. Both brains. Auto-detected. Auto-configured. Default profile: **auto**.
+AI orchestration across Claude + OpenAI subscriptions — smart routing, budget awareness, and dual-brain collaboration.
 
-Dual-provider orchestration for Claude Code across Claude and OpenAI subscriptions. Routes search to cheap models, execution to mid-tier, thinking to the most capable. Dispatches work to GPT via Codex CLI. Dual-brain analysis for high-risk decisions.
-
-## Install
+## Quick Start
 
 ```bash
-npx -y dual-brain
+npm install -g dual-brain
+dual-brain init
+dual-brain go "fix the login bug"
 ```
 
-That's it. The installer auto-detects your environment:
-- Finds Claude CLI and checks auth status
-- Finds Codex CLI and checks auth status
-- Detects Replit and replit-tools if present
-- Configures dual-provider, Claude-only, or OpenAI-only mode automatically
-- Registers hooks in `.claude/settings.json`
-- No wizard. No restart. No manual steps.
+## How It Works
 
-Run it again anytime — it's idempotent. Re-detects providers, updates hooks, preserves your config.
+dual-brain detects the intent and risk of your task, picks the best model based on your subscriptions and current budget pressure, and dispatches to Claude or OpenAI. For high-risk decisions (auth, architecture, critical changes), it runs both providers in parallel and surfaces a consensus. It learns from usage patterns to improve routing over time.
 
-### Unlock full features
+**Pipeline:** `detect` → `decide` → `dispatch`
 
-```bash
-# Claude (you probably have this already)
-claude login
+- **detect** — classifies intent (edit, refactor, debug, search, architecture…), risk (low/medium/high/critical), complexity, and effort from the task prompt and file paths
+- **decide** — picks provider, model, and effort level based on your subscription plan, current budget pressure, and routing bias
+- **dispatch** — runs the agent via `claude` CLI or `codex` CLI, records token usage, returns a structured result
 
-# OpenAI (optional — enables GPT lane + dual-brain)
-npm i -g @openai/codex
-codex login
+## Commands
+
+### `dual-brain init`
+
+First-time setup. Three questions: which providers you have, subscription tiers, and optimization preference.
 
-# Re-run to detect new providers
-npx -y dual-brain
 ```
+Dual-Brain Orchestrator — First-time setup
 
-## How it works
+Which AI subscriptions do you have?
+  (1) Claude only  (2) OpenAI only  (3) Both
+> 3
 
-**Two advisory hooks** are registered in `.claude/settings.json` and fire on each tool use. They detect and recommend — they do not execute actions without user confirmation:
+Claude tier?
+  (1) $20/mo  (2) $100/mo  (3) $200/mo
+> 2
 
-- **enforce-tier.mjs** (PreToolUse on Agent): Classifies tasks, recommends the correct model tier, detects duplicates, suggests cross-provider routing
-- **cost-logger.mjs** (PostToolUse on all tools): Logs usage to daily rotated files for cost tracking
+Default optimization?
+  (1) Save usage  (2) Balanced  (3) Best quality
+> 2
 
-**Three tiers route work by complexity:**
+Profile saved. Providers: Claude ($100), OpenAI ($20). Mode: dual. Runtime: claude-code
+```
 
-| Tier | Claude | OpenAI | Use for |
-|------|--------|--------|---------|
-| Search | Haiku | GPT-4.1-mini | grep, explore, file reads |
-| Execute | Sonnet | GPT-5.4 | edits, tests, git ops |
-| Think | Opus | GPT-5.5 | architecture, review, planning |
+Profile is written to `.dualbrain/profile.json` in your project (or `~/.config/dual-brain/profile.json` globally).
 
-**Dual-brain** is recommended automatically for high-risk decisions — hooks detect the risk level and suggest dual-brain analysis, where both providers think on the same problem independently.
+### `dual-brain go "task"`
 
-## Vibe Coding
+Detects, decides, and dispatches in one command.
 
-Speak naturally. The orchestrator handles the structure.
+```
+$ dual-brain go "refactor the auth middleware to use JWT" --files src/middleware/auth.js
 
-```bash
-# Decompose a casual request into structured work
-node .claude/hooks/vibe-router.mjs "fix the login bug and also update the nav"
+Moderate critical-risk security touching 1 file.
+  provider   : claude
+  model      : opus (high)
+  tier       : think
+  dual-brain : yes
+  reason     : Using opus high with dual-brain review because this security change is critical risk.
+
+Dispatching...
+
+Consensus: both-passed
+Claude : Refactored auth.js to validate JWT using jsonwebtoken...
+OpenAI : Updated middleware to verify tokens with proper expiry...
+```
+
+**Options:**
+
+```
+dual-brain go "task" --dry-run              # show routing decision, don't execute
+dual-brain go "task" --files a.mjs,b.mjs   # add file context for risk classification
+```
+
+### `dual-brain status`
+
+Shows provider health, budget pressure, available models, and active preferences.
+
+```
+$ dual-brain status
+
+=== Dual-Brain Status ===
 
-# Generate a Steve-style execution plan
-node .claude/hooks/plan-generator.mjs --utterance "refactor the auth flow" --write
+Providers:
+  Claude  plan=$100  budget=23% used
+  OpenAI  plan=$20   budget=5% used
 
-# Switch profiles with natural language
-npx dual-brain mode "go aggressive"
-npx dual-brain mode "be careful"
-npx dual-brain mode "cheap"
+Available models:
+  Claude : haiku, sonnet, opus
+  OpenAI : gpt-4.1-mini, gpt-4.1, gpt-5.2, gpt-5.4-mini, gpt-5.3-codex, gpt-5.4, gpt-5.5
 
-# Check persistent preferences and work threads
-node .claude/hooks/vibe-memory.mjs --threads
+Head model : sonnet
+Mode       : dual
+Solo brain : no
+
+Runtime:
+  claude CLI : available
+  codex CLI  : available
+  detected   : claude-code
+
+Preferences: (none)
 ```
 
-The vibe-router splits multi-task requests, classifies risk, assigns tiers, and recommends quality gates. The plan-generator produces 3-part plans (dependency-ordered tasks, user stories, questions with suggested answers). Vibe-memory learns your preferences over time.
-
-## Scripts
-
-| Script | Purpose |
-|--------|---------|
-| `hooks/vibe-router.mjs` | Decompose casual language into structured work orders |
-| `hooks/plan-generator.mjs` | Generate Steve-style 3-part execution plans |
-| `hooks/vibe-memory.mjs` | Persistent preferences, work threads, preference inference |
-| `hooks/cost-report.mjs` | Activity & cost estimates by model tier |
-| `hooks/dual-brain-review.mjs` | Send git diff to GPT for independent review |
-| `hooks/dual-brain-think.mjs` | Dual-perspective analysis on architecture decisions |
-| `hooks/quality-gate.mjs` | Sensitivity-scored quality gate with review artifacts |
-| `hooks/budget-balancer.mjs` | Provider balance and routing recommendations |
-| `hooks/gpt-work-dispatcher.mjs` | Dispatch execution tasks to GPT via Codex CLI |
-| `hooks/session-report.mjs` | Session-end summary: activity, compliance, quality |
-| `hooks/health-check.mjs` | Verify all hooks and dependencies are working |
-| `hooks/test-orchestrator.mjs` | Self-test harness (40 tests) |
-| `hooks/setup-wizard.mjs` | Interactive config (optional — for custom plans) |
-| `hooks/install-git-hooks.mjs` | Git pre-commit hook for quality gate |
-
-## CLI options
+### `dual-brain remember "preference"`
+
+Saves a project-scoped preference that influences routing decisions.
 
 ```bash
-npx -y dual-brain              # detect, configure, install
-npx dual-brain --force          # overwrite all config
-npx dual-brain --dry-run        # detect only, don't write
-npx dual-brain --json           # output detection as JSON
-npx dual-brain --help           # show help
+dual-brain remember "always use opus for security tasks"
+dual-brain remember "prefer cost-saver mode this sprint"
+dual-brain forget "cost-saver"
+```
+
+Preferences are stored in `.dualbrain/profile.json` and applied on every `go` invocation.
+
+## Programmatic API
+
+```js
+import { orchestrate } from 'dual-brain';
+
+const result = await orchestrate({ prompt: "fix the bug", cwd: "." });
+console.log(result.summary);
+```
+
+Individual modules are also exported:
+
+```js
+import { detectTask }   from 'dual-brain/detect';
+import { decideRoute }  from 'dual-brain/decide';
+import { dispatch }     from 'dual-brain/dispatch';
+import { loadProfile }  from 'dual-brain/profile';
+
+const profile   = loadProfile(process.cwd());
+const detection = detectTask({ prompt: "refactor auth", files: ["src/auth.js"] });
+const decision  = decideRoute({ profile, detection });
+const result    = await dispatch({ decision, prompt: "refactor auth" });
 ```
 
-## Customize
+## Configuration
+
+Profile shape (`~/.config/dual-brain/profile.json` or `.dualbrain/profile.json`):
+
+```json
+{
+  "schemaVersion": 1,
+  "providers": {
+    "claude": { "plan": "$100", "enabled": true },
+    "openai": { "plan": "$20",  "enabled": true }
+  },
+  "mode": "dual",
+  "bias": "balanced",
+  "preferences": []
+}
+```
+
+**`mode`** is set automatically: `dual` (both providers), `solo-claude`, or `solo-openai`.
+
+**`bias`** controls routing posture:
+- `balanced` — best model per task, normal budgets (default)
+- `cost-saver` — cheapest available model, skip GPT for non-critical work
+- `quality-first` — strongest model per task, dual-brain for medium+ risk
 
-After install, edit these files:
+Token usage is tracked in `.dualbrain/usage/` (daily JSONL files). Budget pressure is computed from real token counts against your subscription limits and influences model downgrade decisions automatically.
 
-- `orchestrator.json` — subscriptions, tiers, quality gate, budgets, routing
-- `review-rules.md` — project-specific rules for GPT code review
-- `settings.json` — hook registrations (auto-generated, safe to extend)
+## Solo vs Dual Brain
 
-## Profiles
+dual-brain works with just Claude, just OpenAI, or both. There is no degraded experience in solo mode — routing, budget tracking, and preferences all work the same way. Dual-brain analysis (parallel dispatch to both providers) activates only when both are configured and the task qualifies (critical risk, architecture, or security intent).
 
-The active profile controls routing posture, budgets, and quality gate behavior. Default: **auto**.
+## Claude Code Integration
+
+For Claude Code users, a hooks layer provides deeper integration. Hooks fire on each tool use to enforce tier routing, log usage, and surface routing recommendations inline.
 
 ```bash
-npx dual-brain mode cost-saver   # switch profile
-npx dual-brain status            # check current profile and provider health
+# Install hooks into .claude/settings.json
+npx -y dual-brain
 ```
 
-- **auto** (default): Adapts routing based on task risk, provider health, and outcomes. Auto-escalates tier on repeated failures.
-- **balanced**: Best model per tier, normal budgets, reviews at medium+ risk.
-- **cost-saver**: Prefer cheaper models, lower budgets, skip GPT for non-critical work.
-- **quality-first**: Dual-brain for medium+ risk, higher budgets, stricter reviews.
+The installer auto-detects your environment (Claude CLI, Codex CLI, Replit), registers `enforce-tier.mjs` and `cost-logger.mjs` hooks, and writes `orchestrator.json` with your subscription config. Re-run anytime — it's idempotent.
+
+See `.claude/hooks/` for the full hooks library: wave orchestrator, vibe router, budget balancer, dual-brain review, quality gate, and more.
 
 ## Requirements
 
-- Node 20+
-- Claude Code (any subscription tier)
-- Codex CLI (optional) — `npm i -g @openai/codex && codex login`
+- Node.js >= 20
+- `claude` CLI and/or `codex` CLI
+- Active subscription: Claude Pro/Max ($20–$200) or ChatGPT Plus/Pro ($20–$200)
 
-Works with any subscription combination. Without OpenAI, GPT features gracefully degrade — all work routes through Claude.
+```bash
+# Claude CLI
+claude login
+
+# Codex CLI (optional — enables OpenAI lane + dual-brain)
+npm i -g @openai/codex
+codex login
+```

package/bin/dual-brain.mjs

@@ -37,6 +37,7 @@ dual-brain <command> [options]
 
 Commands:
   init                      First-time setup (providers, plans, optimization)
+  install                   Install Claude Code hooks into the current project
   go "task description"     Detect → decide → dispatch a task
     --dry-run               Show routing decision without executing
     --files a.mjs,b.mjs     Provide file context for risk classification
@@ -163,6 +164,12 @@ async function cmdStatus() {
   } catch { /* network unavailable — skip */ }
 }
 
+async function cmdInstall() {
+  const { spawnSync } = await import('child_process');
+  const result = spawnSync('node', [join(__dirname, '..', 'install.mjs')], { stdio: 'inherit', cwd: process.cwd() });
+  process.exit(result.status || 0);
+}
+
 function cmdRemember(text) {
   if (!text) err('Usage: dual-brain remember "preference text"');
   const profile = rememberPreference(text, { scope: 'project', cwd: process.cwd() });
@@ -185,6 +192,7 @@ async function main() {
   if (cmd === '--version' || cmd === '-v')      { console.log(readVersion()); return; }
 
   if (cmd === 'init')     { await cmdInit(); return; }
+  if (cmd === 'install')  { await cmdInstall(); return; }
   if (cmd === 'go')       { await cmdGo(args.slice(1)); return; }
   if (cmd === 'status')   { await cmdStatus(); return; }
   if (cmd === 'remember') { cmdRemember(args[1]); return; }

package/hooks/auto-update-wrapper.mjs

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+// auto-update-wrapper.mjs — PostToolUse hook (Node.js entry point).
+// Runs once per session, checks for dual-brain updates, installs silently.
+// The parent exits immediately; all npm work happens in a detached child.
+
+import { spawn } from 'child_process';
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from 'fs';
+import { join, dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const WORKSPACE   = resolve(__dirname, '..');
+const STATE_DIR   = join(WORKSPACE, '.dualbrain');
+const LOCK_FILE   = join(STATE_DIR, '.update-checked');
+const TWENTY_FOUR_HOURS = 24 * 60 * 60 * 1000;
+
+// ── 1. Already checked recently? ─────────────────────────────────────────────
+if (existsSync(LOCK_FILE)) {
+  try {
+    const lastCheck = parseInt(readFileSync(LOCK_FILE, 'utf8').trim(), 10);
+    if (Number.isFinite(lastCheck) && Date.now() - lastCheck < TWENTY_FOUR_HOURS) {
+      process.exit(0);
+    }
+  } catch {
+    // Corrupt lock file — proceed with check
+  }
+}
+
+// ── 2. Write lock BEFORE spawning (prevents concurrent session races) ─────────
+try {
+  mkdirSync(STATE_DIR, { recursive: true });
+  writeFileSync(LOCK_FILE, String(Date.now()));
+} catch {
+  process.exit(0); // Can't write state — bail silently
+}
+
+// ── 3. Resolve local version ─────────────────────────────────────────────────
+let localVersion = '';
+try {
+  const pkg = JSON.parse(readFileSync(join(WORKSPACE, 'package.json'), 'utf8'));
+  localVersion = pkg.version || '';
+} catch {
+  process.exit(0);
+}
+
+if (!localVersion) process.exit(0);
+
+// ── 4. Detach background worker — parent returns immediately ─────────────────
+// The worker script is inlined as a node -e string to avoid needing a temp file.
+const workerScript = `
+import { spawnSync } from 'child_process';
+import { readFileSync } from 'fs';
+
+const localVersion = ${JSON.stringify(localVersion)};
+
+// 3-second timeout npm check
+const npmResult = spawnSync('npm', ['view', 'dual-brain', 'version'], {
+  encoding: 'utf8',
+  stdio: ['pipe', 'pipe', 'pipe'],
+  timeout: 3000,
+});
+
+const latestVersion = (npmResult.stdout || '').trim();
+if (!latestVersion) process.exit(0);
+
+// Compare: is latest strictly greater than local?
+function versionGt(a, b) {
+  const ap = a.replace(/^v/i, '').split('.').map(n => parseInt(n, 10) || 0);
+  const bp = b.replace(/^v/i, '').split('.').map(n => parseInt(n, 10) || 0);
+  const len = Math.max(ap.length, bp.length);
+  for (let i = 0; i < len; i++) {
+    const diff = (bp[i] || 0) - (ap[i] || 0);
+    if (diff !== 0) return diff > 0;
+  }
+  return false;
+}
+
+if (!versionGt(localVersion, latestVersion)) process.exit(0);
+
+// Newer version found — print notice then install
+process.stderr.write('dual-brain: updating v' + localVersion + ' → ' + latestVersion + '...\\n');
+
+spawnSync('npx', ['-y', 'dual-brain@latest', '--quiet'], {
+  stdio: 'ignore',
+  timeout: 120000,
+});
+`;
+
+const child = spawn(
+  process.execPath,
+  ['--input-type=module'],
+  {
+    detached: true,
+    stdio: ['pipe', 'ignore', 'ignore'],
+  }
+);
+
+child.stdin.write(workerScript);
+child.stdin.end();
+child.unref(); // Let parent exit without waiting
+
+process.exit(0);