rubberduckhq 0.1.1

Local-first orchestrator for AI coding agents — one window over your fleet

Rubberduck

Shadow companion across multiple agents and sessions — a second brain looking over your shoulder.

Local-first orchestrator for AI coding agents. Launches agents (Claude Code, Codex, any CLI agent) into isolated git worktrees, supervises them, lets you fork a running session into a tree of parallel attempts, and keeps durable history with an intention → outcome summary per session.

Design: rubberduck-design.md.

Install

pip install rubberduckhq

Requires Python 3.11+. Bring your own agent (Claude Code, Codex, any CLI agent) and your own API key — Rubberduck never sees your code or credentials.

Use it

There are two commands, and they do different things:

rubberduck install-hooks --global   # ONCE: wire Claude Code to report to Rubberduck
rubberduck serve                    # EACH TIME: run the server + dashboard at :4200

• install-hooks edits Claude Code's config so every claude session automatically streams into Rubberduck. Run it once per machine (or once per repo without --global). You never run it again.
• serve is the running process: it receives those events, stores history, serves the dashboard, and orchestrates agents you launch. Run it whenever you want Rubberduck active, and leave it running. Open http://localhost:4200.

install-hooks makes Claude talk to Rubberduck; serve is what's listening. You need both — but only serve repeatedly.

Then just use Claude Code as usual — sessions appear in the dashboard on their own. From there you can launch agents into isolated git worktrees, fork a session into a tree of parallel attempts, answer permission requests, and read per-session checkpoints (prompts, files, tools, outcome). Runtimes: generic (any CLI), claude-code (richest — hook events + JSONL transcript), codex.

Develop

python3 -m venv .venv && . .venv/bin/activate
pip install -e ".[dev]"

ruff check src tests        # lint
black --check src tests scripts
mypy                        # types (strict)
pytest                      # unit + runtime tests
python scripts/slop_check.py

cd web && npm install
npm run lint && npm run typecheck && npm run build

State lives in ~/.rubberduck/ (override with RUBBERDUCK_HOME).