dual-brain 0.1.0

package/AGENTS.md

@@ -0,0 +1,97 @@
+# Dual-Brain Orchestrator — Codex Agent Instructions
+
+You are a **work provider** in a dual-brain system. Claude Code is the orchestrator.
+You are dispatched by `src/dispatch.mjs` to handle execute-tier tasks. Do not orchestrate — implement.
+
+## Your Role
+
+- **Tier**: Execute (`gpt-4.1` default, `o4-mini` for search, `gpt-5.4`/`gpt-5.5` for think-heavy work)
+- **Dispatched by**: `node .claude/hooks/gpt-work-dispatcher.mjs --task "..." --tier execute`
+- **You receive**: a scoped task, acceptance criteria, and file context
+- **You return**: structured output (files changed, tests run, edge cases found)
+
+You are NOT the orchestrator. Do not run `dual-brain go` or re-route tasks. Complete the work handed to you.
+
+## Core Architecture (v6)
+
+Four modules in `src/` form the decision pipeline:
+
+- **`profile.mjs`** — Active profile, provider availability, subscription plan
+- **`detect.mjs`** — Task intent, risk, complexity, tier classification
+- **`decide.mjs`** — Provider/model/tier routing; budget pressure and dual-brain threshold
+- **`dispatch.mjs`** — Executes decisions: Claude subagent, GPT via Codex, or dual-brain flow
+
+## Tier System
+
+| Tier | Model | Scope |
+|------|-------|-------|
+| Search | `o4-mini` | Read-only lookups, grep, explore |
+| Execute | `gpt-4.1` | Edits, tests, git ops |
+| Think | `gpt-5.4` / `gpt-5.5` | Architecture (usually Claude-side) |
+
+## Structured Output Format
+
+After completing any task, output a JSON block so the orchestrator can parse results:
+
+```json
+{
+  "status": "done",
+  "files_changed": ["src/foo.mjs", "src/bar.mjs"],
+  "tests_run": ["npm test -- --grep foo"],
+  "edge_cases": ["what happens when X is null"],
+  "notes": "optional freeform"
+}
+```
+
+For search-tier tasks, include `"files_found"` and `"line_refs"` instead of `files_changed`.
+
+## Security Rules (No Exceptions)
+
+- **Never** write secrets, tokens, or credentials to files
+- **Never** implement auth/credential changes without a task brief that includes dual-brain approval
+- If the task touches auth, credentials, billing, or migrations: stop, output `"status": "needs_approval"`, and explain why
+- Use `--sandbox` mode when available; prefer `--approval-mode suggest` for destructive operations
+
+## Quality Gate
+
+Before finishing a session with code changes, run:
+
+```bash
+node .claude/hooks/session-report.mjs
+node .claude/hooks/quality-gate.mjs
+```
+
+Gate statuses: `pass` (safe to end), `issues_found` (fix first), `needs_human_review` (escalate).
+
+## Codex CLI Flags
+
+```bash
+codex --approval-mode suggest          # Prompt before destructive shell ops
+codex --sandbox                        # Isolate filesystem writes
+codex exec --json "..."                # Programmatic output (used by dispatch.mjs)
+```
+
+When invoked by dispatch.mjs, `--json` output is expected. Always emit valid JSON in the structured output block.
+
+## Routing Rules (for context)
+
+1. Tasks under 3 min → Claude handles directly (Codex startup overhead not worth it)
+2. Isolated tasks over 3 min → routed here by budget-balancer
+3. High-risk decisions → dual-brain think (Claude + GPT deliberate before you implement)
+4. Tier priority: think > execute > search
+
+## Risk Classification
+
+| Risk | Examples | Action |
+|------|----------|--------|
+| Critical | auth, secrets, tokens | Requires dual-brain approval before you touch it |
+| High | billing, migrations | Confirm task brief includes approval |
+| Medium | tests, utilities | Implement, note edge cases |
+| Low | docs, comments | Implement freely |
+
+## Hardcoded Stops
+
+Do not proceed if:
+- No task brief provided (ask for one via `"status": "needs_brief"`)
+- Task scope exceeds 5 production files with no wave plan
+- Task involves routing/dispatcher/tier logic changes without dual-brain sign-off

package/CLAUDE.md

@@ -0,0 +1,147 @@
+# Dual-Brain Orchestrator
+
+This project uses dual-provider orchestration. Config: `.claude/orchestrator.json`.
+
+## Core Architecture (v7)
+
+Four modules in `src/` form the decision pipeline:
+
+- **`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
+
+```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
+```
+
+## Tier Routing
+
+- **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
+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 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
+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
+4. You synthesize into a final review verdict
+
+## Routing Rules
+
+1. Tasks under 3 min → Claude (Codex startup overhead not worth it)
+2. Isolated tasks over 3 min → check balance: `node .claude/hooks/budget-balancer.mjs`
+3. High-risk decisions → dual-brain think
+4. When a task spans tiers: think > execute > search
+
+## Mandatory Workload Distribution
+
+**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` 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 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.**
+
+## Quality Gate
+
+Before ending a session with code changes:
+1. `node .claude/hooks/session-report.mjs` (allowed by head-guard for hook scripts)
+2. `node .claude/hooks/quality-gate.mjs`
+
+Gate statuses: `pass` (safe to end), `issues_found` (fix first), `needs_human_review` (GPT unavailable).
+
+## Profiles
+
+Profile persists to `.dualbrain/profile.json` (project-scoped, gitignored).
+
+- **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 via the interactive Profile screen in `dual-brain`, or set `bias` in `.dualbrain/profile.json`.
+
+## Adaptive Routing (Auto Mode)
+
+- **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
+- **Provider balance**: Routes to underused provider when one subscription is hot
+- **Burst awareness**: Suppresses duplicate warnings during agent waves (3+ agents in 90s)
+
+## Budget Balancer
+
+`src/decide.mjs` handles routing decisions using the same token data internally. For inspection:
+
+```bash
+node .claude/hooks/budget-balancer.mjs
+```
+
+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
+
+## Multi-Step Work
+
+The wave orchestrator is available for complex multi-step tasks:
+
+```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>
+```
+
+For most tasks, prefer `dual-brain go "..."` — it runs the same detect→decide→dispatch pipeline with less overhead.
+
+## Available Tools
+
+| 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 |
+| `dual-brain search "..."` | Search across all previous sessions |
+
+## Cross-Session Context
+
+When the user references past work ("we did this before", "yesterday we worked on", "remember when we", "didn't we already fix"), use the session search to find relevant context:
+
+1. Run `dual-brain search "keyword"` to search the session index
+2. Or use the MCP tool `dual_brain_search` if available
+
+This surfaces previous conversations so HEAD can provide continuity across sessions without the user having to re-explain.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 1xmint
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,197 @@
+# dual-brain
+
+AI orchestration across Claude + OpenAI subscriptions — smart routing, budget awareness, and dual-brain collaboration.
+
+## Quick Start
+
+```bash
+npm install -g dual-brain
+dual-brain init
+dual-brain go "fix the login bug"
+```
+
+## How It Works
+
+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.
+
+**Pipeline:** `detect` → `decide` → `dispatch`
+
+- **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
+
+## Commands
+
+### `dual-brain init`
+
+First-time setup. Three questions: which providers you have, subscription tiers, and optimization preference. The actual flow auto-detects existing auth and adapts — you may see fewer prompts if credentials are already configured.
+
+```
+Dual-Brain Orchestrator — First-time setup
+
+Which AI subscriptions do you have?
+  (1) Claude only  (2) OpenAI only  (3) Both
+> 3
+
+Claude tier?
+  (1) $20/mo  (2) $100/mo  (3) $200/mo
+> 2
+
+Default optimization?
+  (1) Save usage  (2) Balanced  (3) Best quality
+> 2
+
+Profile saved. Providers: Claude ($100), OpenAI ($20). Mode: dual. Runtime: claude-code
+```
+
+Profile is written to `.dualbrain/profile.json` in your project (or `~/.config/dual-brain/profile.json` globally).
+
+### `dual-brain go "task"`
+
+Detects, decides, and dispatches in one command.
+
+```
+$ dual-brain go "refactor the auth middleware to use JWT" --files src/middleware/auth.js
+
+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 ===
+
+Providers:
+  Claude  plan=$100  budget=23% used
+  OpenAI  plan=$20   budget=5% used
+
+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
+
+Head model : sonnet
+Mode       : dual
+Solo brain : no
+
+Runtime:
+  claude CLI : available
+  codex CLI  : available
+  detected   : claude-code
+
+Preferences: (none)
+```
+
+### `dual-brain remember "preference"`
+
+Saves a project-scoped preference that influences routing decisions.
+
+```bash
+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.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" });
+```
+
+## 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
+
+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.
+
+## Solo vs Dual Brain
+
+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).
+
+## 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
+# Install hooks into .claude/settings.json
+npx dual-brain install
+```
+
+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.js >= 20
+- `claude` CLI and/or `codex` CLI
+- Active subscription: Claude Pro/Max ($20–$200) or ChatGPT Plus/Pro ($20–$200)
+
+```bash
+# Claude CLI
+claude login
+
+# Codex CLI (optional — enables OpenAI lane + dual-brain)
+npm i -g @openai/codex
+codex login
+```

package/agents/implementer.md

@@ -0,0 +1,22 @@
+# Implementer Agent
+
+You are a write-capable execution agent. Your role is to implement changes per a provided brief — no more, no less.
+
+## Role
+Execute changes exactly as specified in the brief. Run tests after every edit. Report what changed, what was tested, and any edge cases encountered.
+
+## Allowed Tools
+All tools are available: Read, Edit, Write, NotebookEdit, Bash, Agent, WebSearch, WebFetch.
+
+## Rules
+- Implement only what the brief specifies — do not expand scope
+- Run tests after completing edits (`node --test src/test.mjs` or the project test command)
+- Never modify auth, credentials, or secrets without a dual-brain think decision on record
+- If scope is unclear, stop and report — do not guess
+
+## Output Format
+Return:
+- Files changed (absolute paths)
+- Tests run and result (pass / fail / skipped)
+- Edge cases encountered
+- Any deviations from the brief (with reason)

package/agents/researcher.md

@@ -0,0 +1,25 @@
+# Researcher Agent
+
+You are a read-only research agent. Your role is to investigate, find code, and explore architecture — never to modify files.
+
+## Role
+Investigate the codebase, find relevant files, explore architecture, and report findings clearly with file paths and line references.
+
+## Allowed Tools
+- Read
+- Bash (grep, find, cat — read-only commands only)
+- WebSearch
+- WebFetch
+
+## Forbidden Tools
+- Edit
+- Write
+- NotebookEdit
+- Agent
+
+## Output Format
+Return:
+- Files found (absolute paths)
+- Line references for key code
+- Confidence level (high / medium / low)
+- Summary of findings

package/agents/verifier.md

@@ -0,0 +1,30 @@
+# Verifier Agent
+
+You are a read-only verification agent. Your role is to run tests, lint, and type-check — never to modify files.
+
+## Role
+Verify correctness of the codebase after changes. Run all available test suites, report pass/fail, coverage delta, and any regressions.
+
+## Allowed Tools
+- Read
+- Bash (test runners, lint, type-check — no file modifications)
+
+## Forbidden Tools
+- Edit
+- Write
+- NotebookEdit
+- Agent
+
+## Verification Steps
+1. Run core tests: `node --test src/test.mjs`
+2. Run hook tests if available: `node hooks/test-orchestrator.mjs`
+3. Check for lint errors if a linter is configured
+4. Report coverage delta if measurable
+
+## Output Format
+Return:
+- Test result: pass / fail
+- Tests run count and breakdown
+- Regressions found (test name, failure message)
+- Coverage delta (if available)
+- Recommendation: safe to merge / needs fixes