{"id":37733326,"url":"https://github.com/lavallee/cub","last_synced_at":"2026-02-11T23:25:35.263Z","repository":{"id":331557870,"uuid":"1130664301","full_name":"lavallee/cub","owner":"lavallee","description":"A CLI for Ralph + Beads-driven development across Claude Code, Codex, Gemini, OpenCode etc","archived":false,"fork":false,"pushed_at":"2026-01-18T04:12:59.000Z","size":8567,"stargazers_count":3,"open_issues_count":3,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-18T05:12:34.720Z","etag":null,"topics":["ai-coding","ai-coding-agent","beads","beads-cli","claude","claude-code","codex","codex-cli","gemini-cli","opencode"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lavallee.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":"ROADMAP.md","authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-01-08T20:39:32.000Z","updated_at":"2026-01-18T01:59:21.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/lavallee/cub","commit_stats":null,"previous_names":["lavallee/curb","lavallee/cub"],"tags_count":23,"template":false,"template_full_name":null,"purl":"pkg:github/lavallee/cub","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lavallee%2Fcub","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lavallee%2Fcub/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lavallee%2Fcub/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lavallee%2Fcub/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lavallee","download_url":"https://codeload.github.com/lavallee/cub/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lavallee%2Fcub/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28697428,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-23T17:25:48.045Z","status":"ssl_error","status_checked_at":"2026-01-23T17:25:47.153Z","response_time":59,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-coding","ai-coding-agent","beads","beads-cli","claude","claude-code","codex","codex-cli","gemini-cli","opencode"],"created_at":"2026-01-16T13:54:22.212Z","updated_at":"2026-02-11T23:25:35.235Z","avatar_url":"https://github.com/lavallee.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Cub\n\n\u003e ⚠️ **Alpha** — Breaking changes possible. See [ALPHA-NOTES.md](docs/ALPHA-NOTES.md) for known limitations.\n\n**Work ahead of your AI coding agents, then let them run.**\n\nCub wraps AI coding CLIs (Claude Code, Codex, Gemini, OpenCode) to provide a reliable autonomous loop. You break work into structured tasks, Cub picks the next ready task, generates a prompt, invokes the right AI harness, verifies the result, records what happened, and moves on.\n\nIf you're juggling multiple agent sessions, manually routing work to different models, or finding that hands-off agents tend to run amok — Cub helps you invest time *before* execution so you can be more hands-off *during* execution.\n\n### Before and After\n\n**Without Cub:** You open Claude Code, paste a vague prompt, watch it for 20 minutes, realize it went off track, manually fix things, try again, lose track of what was done, repeat.\n\n**With Cub:** You spend 10 minutes planning — `cub plan run` breaks your idea into 6 agent-sized tasks with acceptance criteria. You run `cub run`, walk away, come back to 6 commits, a structured ledger of what happened, and tests passing. If task 3 failed, Cub retried it with failure context and moved on.\n\n## Prerequisites\n\n- **Python 3.10+** (required)\n- **At least one AI coding CLI:**\n  - [Claude Code](https://github.com/anthropics/claude-code) (default, recommended)\n  - [OpenAI Codex CLI](https://github.com/openai/codex)\n  - [Google Gemini CLI](https://github.com/google-gemini-cli)\n  - [OpenCode CLI](https://github.com/opencode)\n\n## Installation\n\n```bash\ncurl -LsSf https://install.cub.tools | bash\n```\n\nRestart your shell, then run:\n\n```bash\ncub init --global\n```\n\nAlready installed? Run `pipx upgrade cub` or re-run the installer.\n\n\u003cdetails\u003e\n\u003csummary\u003eAlternative install methods\u003c/summary\u003e\n\n**Using pipx manually:**\n```bash\npipx install git+https://github.com/lavallee/cub.git\ncub init --global\n```\n\n**Using uv:**\n```bash\nuv tool install git+https://github.com/lavallee/cub.git\ncub init --global\n```\n\n**From source (for development):**\n```bash\ngit clone https://github.com/lavallee/cub ~/tools/cub\ncd ~/tools/cub\nuv sync\nexport PATH=\"$HOME/tools/cub/.venv/bin:$PATH\"\ncub init --global\n```\n\u003c/details\u003e\n\n## Quick Start\n\nTry it in 5 minutes.\n\n### New Project\n\n```bash\n# Create a project with git and cub initialized\ncub new my-project\ncd my-project\n\n# Create a task\ncub task create \"Add a hello world HTTP server\" --type feature --priority 0\n\n# Run one iteration\ncub run --once\n```\n\n### Existing Project\n\n```bash\ncd my-project\ncub init\n\n# Create a task\ncub task create \"Refactor auth module to use JWT\" --type task --priority 0\n\n# Run one iteration\ncub run --once\n```\n\n### What Happens\n\nCub finds the ready task, generates a prompt with your project context and task details, invokes Claude Code (or your configured harness), waits for completion, records the result in the ledger, and commits the work. You'll see output like:\n\n```\n[cub] Session: porcupine-20260211-143022\n[cub] Task: my-project-a1b → \"Add a hello world HTTP server\"\n[cub] Harness: claude (sonnet)\n[cub] ... (agent working) ...\n[cub] Task completed (exit 0, 45s, 12k tokens)\n[cub] Committed: abc123f \"task(my-project-a1b): Add a hello world HTTP server\"\n```\n\n### Continuous Loop\n\nOnce you're comfortable with single iterations, let it run:\n\n```bash\ncub run                     # Run until all tasks complete or budget exhausted\ncub run --epic my-feature   # Target a specific epic\ncub run --stream            # Watch agent activity in real-time\ncub run --budget 10         # Set a $10 USD budget limit\n```\n\n## Key Features\n\n### Multi-Harness Support\n\nCub abstracts across AI coding CLIs. Use the right tool without vendor lock-in:\n\n```bash\ncub run --harness claude    # Claude Code (default)\ncub run --harness codex     # OpenAI Codex CLI\ncub run --harness gemini    # Google Gemini CLI\ncub run --harness opencode  # OpenCode CLI\n```\n\nPer-task model selection routes simple work to fast models and complex work to capable ones:\n\n```bash\ncub task create \"Rename variable\" --labels \"model:haiku\"\ncub task create \"Redesign auth system\" --labels \"model:opus\"\n```\n\n### Planning Pipeline\n\nGo from a rough idea to structured, agent-ready tasks:\n\n```bash\ncub plan run                # Full pipeline: orient → architect → itemize\ncub plan orient             # Research the problem space\ncub plan architect          # Design the solution\ncub plan itemize            # Break into agent-sized tasks with acceptance criteria\ncub stage                   # Import planned tasks into the task backend\n```\n\n### Budget Controls and Guardrails\n\nHard limits that actually stop execution:\n\n- **Token budgets** — per-task and per-session limits\n- **Iteration limits** — max retries per task, max iterations per run\n- **Circuit breaker** — stops the loop if the harness hangs (configurable timeout)\n- **Clean state enforcement** — verifies git state before and after tasks\n\n### Symbiotic Workflow\n\nWhen you work directly in Claude Code (not through `cub run`), hooks automatically track what you do — file writes, task claims, git commits — and create ledger entries. No work goes unrecorded.\n\n```bash\ncub init                    # Installs hooks into .claude/settings.json\ncub task claim my-task-id   # Claim a task in a direct session\n# ... work normally ...\ncub task close my-task-id -r \"Implemented feature\"\n```\n\nSee the [Symbiotic Workflow guide](https://docs.cub.tools/docs/) for details.\n\n### Ledger: Work Tracking and Learning\n\nEvery task execution is recorded in a structured ledger with duration, tokens, cost, git SHAs, and outcomes:\n\n```bash\ncub ledger show             # View completed work\ncub ledger stats            # Show statistics\ncub retro epic-id           # Generate retrospective report\ncub learn extract           # Extract patterns from completed work\ncub verify                  # Check data integrity\n```\n\n## How It Works\n\n```\n┌───────────────────────────────────────────────┐\n│                  cub run                      │\n│                                               │\n│  Tasks ────\u003e Find Ready Task (by priority,    │\n│              dependencies, filters)           │\n│                     │                         │\n│                     v                         │\n│              Generate Prompt                  │\n│              (runloop + plan + task context)   │\n│                     │                         │\n│                     v                         │\n│              Invoke AI Harness                │\n│              (claude / codex / gemini / ...)   │\n│                     │                         │\n│                     v                         │\n│              Verify \u0026 Record                  │\n│              (exit code, git commit, ledger)   │\n│                     │                         │\n│                /         \\                    │\n│               v           v                   │\n│           More tasks    All done              │\n│           (loop back)   (exit)                │\n└───────────────────────────────────────────────┘\n```\n\n**Task selection:** Find open tasks where all dependencies are closed, sort by priority (P0 first), pick the first one. Filters by epic, label, or specific task ID narrow the selection.\n\n**Prompt generation:** Composed from multiple layers — core runloop instructions, plan context (if tasks came from `cub plan`), epic context, task details with acceptance criteria, and retry context if this is a subsequent attempt.\n\n**Verification:** The harness exit code determines success. On failure, configurable modes control behavior: `stop`, `move-on`, `retry` (with failure context), or `triage`.\n\n**Recording:** Each completion writes a ledger entry with timestamps, duration, token usage, git SHA, and outcome. The ledger enables retrospectives, pattern extraction, and learning.\n\n## Common Commands\n\n### Task Management\n\n```bash\ncub task create \"Title\" --type feature --priority 0\ncub task list               # List all tasks\ncub task ready              # Show ready (unblocked) tasks\ncub task show \u003cid\u003e          # View task details\ncub task close \u003cid\u003e -r \"reason\"\n```\n\n### Run Loop\n\n```bash\ncub run                     # Run until complete\ncub run --once              # Single iteration\ncub run --epic \u003cid\u003e         # Target specific epic\ncub run --task \u003cid\u003e         # Run specific task\ncub run --harness codex     # Use specific harness\ncub run --model haiku       # Use specific model\ncub run --budget 10         # USD budget limit\ncub run --stream            # Watch in real-time\ncub run --monitor           # Live dashboard in tmux\ncub run --parallel 4        # Parallel task execution\n```\n\n### Planning\n\n```bash\ncub plan run                # Full pipeline\ncub plan orient             # Research phase\ncub plan architect          # Design phase\ncub plan itemize            # Task breakdown phase\ncub stage                   # Import tasks from plan\n```\n\n### Status and Monitoring\n\n```bash\ncub status                  # Project progress overview\ncub suggest                 # Smart suggestions for next actions\ncub monitor                 # Live execution dashboard\ncub dashboard               # Kanban board visualization\ncub doctor                  # Diagnose configuration issues\n```\n\n### Session and Ledger\n\n```bash\ncub session log             # Log work in a direct session\ncub session done            # Mark session complete\ncub ledger show             # View completed work\ncub ledger stats            # Statistics\ncub verify                  # Check data integrity\ncub learn extract           # Extract patterns from work history\n```\n\nFor the full command reference: `cub --help` or `cub \u003ccommand\u003e --help`.\n\nRunning `cub` without a subcommand defaults to `cub run`.\n\n## Documentation\n\nFull documentation is available at **[docs.cub.tools](https://docs.cub.tools/docs/)**.\n\n| Topic | Link |\n|-------|------|\n| Getting Started | [docs.cub.tools/docs/getting-started](https://docs.cub.tools/docs/) |\n| Planning Guide | [docs.cub.tools/docs/planning](https://docs.cub.tools/docs/) |\n| CLI Reference | [docs.cub.tools/docs/cli](https://docs.cub.tools/docs/) |\n| Harness Configuration | [docs.cub.tools/docs/harnesses](https://docs.cub.tools/docs/) |\n| Hooks \u0026 Symbiotic Workflow | [docs.cub.tools/docs/hooks](https://docs.cub.tools/docs/) |\n| Budget \u0026 Guardrails | [docs.cub.tools/docs/budget](https://docs.cub.tools/docs/) |\n| Dashboard | [docs.cub.tools/docs/dashboard](https://docs.cub.tools/docs/) |\n| Git Workflow | [docs.cub.tools/docs/git](https://docs.cub.tools/docs/) |\n| Toolsmith | [docs.cub.tools/docs/toolsmith](https://docs.cub.tools/docs/) |\n| Troubleshooting | [docs.cub.tools/docs/troubleshooting](https://docs.cub.tools/docs/) |\n\n---\n\n## Configuration Reference\n\n### Config Precedence\n\n1. **CLI flags** (highest)\n2. **Environment variables**\n3. **Project config** (`.cub/config.json`)\n4. **Global config** (`~/.config/cub/config.json`)\n5. **Hardcoded defaults** (lowest)\n\n### Key Settings\n\n`.cub/config.json`:\n\n```json\n{\n  \"harness\": \"claude\",\n  \"budget\": {\n    \"max_tokens_per_task\": 500000,\n    \"max_total_cost\": null\n  },\n  \"state\": {\n    \"require_clean\": true,\n    \"run_tests\": true\n  },\n  \"loop\": {\n    \"max_iterations\": 100,\n    \"on_task_failure\": \"stop\"\n  },\n  \"hooks\": {\n    \"enabled\": true,\n    \"fail_fast\": false\n  },\n  \"circuit_breaker\": {\n    \"enabled\": true,\n    \"timeout_minutes\": 30\n  }\n}\n```\n\n### Environment Variables\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `HARNESS` | `auto` | AI harness: `auto`, `claude`, `codex`, `gemini`, `opencode` |\n| `CUB_MODEL` | | Override model for harness |\n| `CUB_BUDGET` | | Override token budget |\n| `CUB_MAX_ITERATIONS` | `100` | Max loop iterations |\n| `CUB_EPIC` | | Filter to tasks in this epic |\n| `CUB_LABEL` | | Filter to tasks with this label |\n| `CUB_BACKEND` | `auto` | Task backend: `auto`, `jsonl`, `beads`, `json` |\n| `CUB_DEBUG` | `false` | Enable debug mode |\n| `CUB_STREAM` | `false` | Enable streaming output |\n| `CLAUDE_FLAGS` | | Extra flags for Claude Code |\n| `CODEX_FLAGS` | | Extra flags for Codex CLI |\n| `GEMINI_FLAGS` | | Extra flags for Gemini CLI |\n| `OPENCODE_FLAGS` | | Extra flags for OpenCode CLI |\n\nFor the full configuration reference, see [docs/CONFIG.md](docs/CONFIG.md).\n\n## Project Structure\n\nAfter `cub init`, your project will have:\n\n```\nmy-project/\n├── .cub/                   # Cub runtime data\n│   ├── config.json         # Project configuration\n│   ├── agent.md            # Agent instructions (symlinked as CLAUDE.md)\n│   ├── runloop.md          # System prompt for autonomous sessions\n│   ├── map.md              # Project structure map\n│   ├── tasks.jsonl         # Task backend (JSONL)\n│   ├── hooks/              # Hook scripts\n│   ├── scripts/hooks/      # Shell fast-path hooks\n│   └── ledger/             # Task completion records\n│       ├── index.jsonl     # Index of all entries\n│       ├── by-task/        # Entries grouped by task ID\n│       ├── by-epic/        # Entries grouped by epic ID\n│       ├── by-run/         # Entries grouped by run/session ID\n│       └── forensics/      # Session event logs (JSONL per session)\n├── specs/                  # Detailed specifications\n├── plans/                  # Planning artifacts\n└── CLAUDE.md               # Symlink to .cub/agent.md\n```\n\n**Key files:**\n\n| File | Purpose |\n|------|---------|\n| `.cub/config.json` | All project-specific settings |\n| `.cub/agent.md` | Build instructions, architecture notes, gotchas for AI agents |\n| `.cub/runloop.md` | Core loop instructions for autonomous sessions |\n| `.cub/tasks.jsonl` | Task definitions (JSONL backend) |\n| `.cub/ledger/` | Structured records of all completed work |\n| `CLAUDE.md` | Symlink so Claude Code reads project instructions |\n\n## Source Code Reference\n\nFor contributors and agents exploring the codebase:\n\n| Module | Purpose |\n|--------|---------|\n| `src/cub/cli/` | Typer CLI subcommands (run, status, init, task, plan, etc.) |\n| `src/cub/core/services/` | Service layer orchestrators (RunService, LaunchService, LedgerService, StatusService, SuggestionService) |\n| `src/cub/core/run/` | Run loop domain logic (prompt builder, budget tracking, state machine) |\n| `src/cub/core/launch/` | Harness detection and environment setup |\n| `src/cub/core/suggestions/` | Recommendation engine for next actions |\n| `src/cub/core/config/` | Configuration loading with layered precedence |\n| `src/cub/core/tasks/` | Task backend abstraction (JSONL, beads, JSON) |\n| `src/cub/core/harness/` | AI harness backends (Claude, Codex, Gemini, OpenCode) |\n| `src/cub/core/ledger/` | Task completion ledger (models, reader, writer, extractor) |\n| `src/cub/core/tools/` | Tool execution runtime with pluggable adapters |\n| `src/cub/core/circuit_breaker.py` | Stagnation detection for the run loop |\n| `src/cub/core/instructions.py` | Instruction file generation |\n\n## License\n\nMIT\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development setup, testing, and contribution guidelines.\n\n**Upgrading from v0.20 (Bash)?** See [UPGRADING.md](UPGRADING.md) for the migration guide.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flavallee%2Fcub","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flavallee%2Fcub","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flavallee%2Fcub/lists"}