CodeWave 🌊

Model-agnostic autonomous development chain. Install into any project for full-cycle AI-driven development.

codewave init          → onboard a project (static analysis → knowledge model)
codewave ideate        → brainstorm features
codewave specify       → promote idea to spec
codewave plan          → generate wave plan from spec
codewave run           → start autonomous execution chain
codewave status        → check chain health
codewave halt          → stop the chain
codewave resume        → clear halt and continue
codewave watchdog      → manage chain health monitor

Quick start

npm install -g codewave
cd your-project
codewave init
codewave run

How it works

CodeWave runs an autonomous development chain — the same mechanism that powers the Torch0 ralph-loop, decoupled and model-agnostic.

The dev cycle

ONBOARD → IDEATE → SPECIFY → PLAN → EXECUTE (ralph-loop)
  ↑______________________________________________↓
             continuous learning loop

• Onboard — codewave init scans your project, infers architecture, detects safety boundaries, and builds a PROJECT.knowledge.md that every session loads.
• Ideate — codewave ideate "your idea" captures a structured idea doc.
• Specify — codewave specify docs/ideas/feature.md generates a spec.
• Plan — codewave plan docs/specs/feature.md creates a wave plan with bite-sized tasks.
• Execute — codewave run starts the autonomous chain: grounding → implement → accept → review → fix → supervise → wrap → next session.

Safety

The chain runs unattended with strict guardrails:

• HALT.flag — one-way kill switch. Chain can set it but never remove it.
• DECISION_LOG.md — append-only ledger of every judgment call.
• LESSONS.md — failure accumulation that auto-promotes patterns to fix tasks.
• Safety boundary detection — auto-detects production databases, external APIs, deploy commands and generates HALT rules.

Model agnostic

Configure any LLM CLI as a provider:

# .codewave/config.yaml
providers:
  primary:
    cli: claude           # quality gates
    args: ["--permission-mode", "bypassPermissions"]
  secondary:
    cli: deepseek         # implementation work
    args: []
  fallback:
    cli: gemini           # rate-limit fallback
    args: []

Project learning

The chain doesn't need you to document your project. codewave init builds a knowledge model automatically, and every session can append discoveries:

# PROJECT.knowledge.md
## Architecture
Monorepo with packages/apps. Source in src/.

## Safety Boundaries
### DATABASE: DATABASE_URL found in .env.local
- Rule: HALT-AND-FLAG for destructive DB operations

## Discoveries
[SESSION-3] [DISCOVERY] Auth middleware expects JWT in Authorization header

Requirements

• Node.js >= 20
• tmux (for session management)
• At least one LLM CLI (claude, deepseek, codex, etc.)
• Optional: Claude Code Router (npm install -g @musistudio/claude-code-router) for multi-provider support

Multi-Provider Mode

CodeWave supports per-tier CLIs — the controller can run Claude Code (subscription) while implementation tasks use a different model.

Recommended: Tiered Claude Code (subscription)

# .codewave/config.yaml
providers:
  primary:
    cli: claude
    auth: subscription               # OAuth — no API keys needed
    model: opus
    args: ["--permission-mode", "bypassPermissions"]
  secondary:
    cli: claude
    auth: subscription               # Same subscription, cheaper model
    model: sonnet
    args: ["--model", "sonnet", "--permission-mode", "bypassPermissions"]
  fallback:
    cli: claude
    auth: subscription
    model: haiku
    args: ["--model", "haiku", "--permission-mode", "bypassPermissions"]

Quality gates use opus. Implementation uses sonnet. All through one Claude Code subscription.

Optional: CCR Proxy (requires API keys)

If you have API keys and want to route through Claude Code Router:

npm install -g @musistudio/claude-code-router

providers:
  primary:
    auth: ccr
    cli: claude
    ccr:
      providers:
        - name: openrouter
          api_base_url: "https://openrouter.ai/api/v1/chat/completions"
          api_key: "$OPENROUTER_API_KEY"
          models: ["anthropic/claude-opus-4", "anthropic/claude-sonnet-4"]
          transformer: { use: ["openrouter"] }
        - name: deepseek
          api_base_url: "https://api.deepseek.com/chat/completions"
          api_key: "$DEEPSEEK_API_KEY"
          models: ["deepseek-chat"]
          transformer: { use: ["deepseek"] }
      router:
        default: "openrouter,anthropic/claude-opus-4"
        background: "deepseek,deepseek-chat"

Note: CCR requires API keys from each provider. If you have a Claude Code subscription (OAuth), use auth: subscription instead.

View current provider config:

codewave providers

From Torch0

CodeWave is the decoupled, open-source evolution of the ralph-loop autonomous chain that built Torch0. It preserves:

• The full execute pipeline (grounding → implementer → acceptance → reviewer → fix → supervisor)
• HALT.flag inviolability and DECISION_LOG append-only discipline
• Multi-tier model dispatch (cheap for implementation, expensive for quality gates)
• Self-resolve, auto-promote, and recurring escalation mechanisms
• Acceptance script purity rules

And adds:

• Project onboarding and continuous learning
• Full upstream dev cycle (ideate → specify → plan)
• Model-agnostic provider abstraction
• Installability (npm install -g codewave)
• Safety boundary auto-detection

License

MIT