ctopus 🐙

One head. Eight arms. Zero standup meetings.

ctopus is an autonomous engineering orchestrator for Claude Code that drives PRs all the way to merge while you sleep, cook, or stare at the sea contemplating your Series A.

npm i -g ctopus
ctopus        # onboarding wizard → dashboard opens → you're the CTO now

The org chart

You are the CTO. ctopus is your Director of Technology — a tireless middle manager with no ego, no LinkedIn, and no vacation days. It:

1. Plans every task through adversarial planner ↔ reviewer rounds until a reviewer stamps APPROVED (they argue so you don't have to)
2. Gates — business decisions (money, auth, migrations, anything that costs a cent) wait for you; technical decisions ship and report after
3. Ships — implements in an isolated git worktree, proves the fix red/green, opens the PR, triages CI failures and review-bot findings, resolves the threads
4. Never merges. That click is yours. Forever. It's in the constitution.
5. Soaks — merged is not fixed; it watches real traffic for hours before declaring victory
6. Learns — every shipped task gets a retro distilled into knowledge the next planner reads first

You get one batched digest — "Needs you (2) · shipped (3)" — and answer it like royalty: go 1 3.

The delivery graph

Everyone else's coding agent stops at "PR opened 🎉" and hands you a baby to raise. ctopus owns the whole graph, and the dashboard renders it live — derived from your repo, CI, and review-thread state, not hand-wired like some DAG you drew at 2am:

Plan ──◆ Gate ── Ship ──◆ Merge ── Soak ── Learn
       human           human

The diamonds are you. They pulse politely when it's your turn. Loops are the motor, graphs are the rails: a 30-second ticker derives each task's next step from files on disk and pokes the orchestrator. No daemons to babysit. No agent "state" that lies about being busy.

Safety that survives bypass mode

Real talk: autonomous agents run with permissions bypassed — that's what "autonomous" costs. Every cloud vendor's answer is "run it in OUR datacenter." ctopus's answer is tripwires that fire on every shell command, bypass mode or not:

• 🛡 Branch protection — commits on main? Pushes to dev? The hook says no. There is no override. Don't email us.
• 🕵️ Secret scrubber — outbound PRs and pushes are scanned for credential shapes. Connect your database and its actual password joins the ban list. The scrubber reports pattern names, never the secret (it's not a snitch, it's a bouncer).
• 🪤 Suppression tripwire — an agent that "fixes" a failing test with .skip() gets its push bounced. Findings get fixed, not silenced.
• ⏱ SQL timeout guard — a 22-hour unbounded COUNT(*) against production is how this feature was invented. Never again.

And the paranoid cherry on top: ctopus run refuses to start until the hooks are proven working — verified with synthetic payloads at init and every ctopus doctor. Trust, but verify. Then verify again.

The whole runtime is zero-dependency, no-postinstall, stdlib-only Node — a few thousand lines you can audit in an afternoon with a coffee. npm i -g ctopus installs ctopus and nothing else.

Doctrine with teeth

Your engineering policy — what needs approval, how digests read, soak windows, round caps — ships as editable defaults in ~/.ctopus/policy/*.md. Unlike the markdown-prompt frameworks, this doctrine isn't a vibe: it's enforced by hooks, gates, and the ticker. Editing it is editing how your engineering department behaves. With great $EDITOR comes great responsibility.

Receipts

The dashboard counts what actually matters, and one click renders a share card:

🐙 ctopus autonomy report — 14 tasks shipped · 31 plans approved · 3 guard-hook saves · $12.40 agent spend

Post it. Your followers will assume you 10x'd. Only the octopus knows.

Commands

ctopus                open the dashboard (first run: onboarding wizard)
ctopus connect <x>    github · linear · slack · database · staging · browser
ctopus doctor         prove everything works (--deep spends a few cents on model-call probes)
ctopus sync           regenerate managed files after config/doctrine edits
ctopus stop|status|logs

Requires: Claude Code (runs on your existing Claude subscription — no separate API key, no metered cloud), plus git, gh, jq.

FAQ

Why "ctopus"? CTO + octopus. One head making decisions, many arms doing work. Also octopus was taken on npm, and we don't talk about CTO-pus.

Will it refactor my code at 3am? Only if the plan was approved. Which requires a reviewer. Which requires the plan to survive an adversarial review. Your 3am code is safer than your 3pm code.

Can it merge to main? No. It physically cannot — the hook fires even in bypass mode, and there's no override flag. The merge button is your love language.

What if an agent goes rogue? See docs/security-model.md, including the honest "what this does NOT protect against" section. TL;DR: tripwires for the catastrophic classes, your review for the code, a VM if you're running code you don't trust.

Roadmap

• Team control plane (hosted) — org-wide digest, guard-hook audit trail, fleet view, SSO. The local orchestrator stays MIT forever; the octopus does not do rug pulls.
• Multi-project dashboard · doctrine preset gallery (Rails shop · regulated fintech · YOLO startup) · weekly public Autonomy Report benchmark.

License

MIT.

If ctopus merged a PR while you slept, ⭐ the repo so the next tired engineer finds it. The octopus notices. The octopus remembers. 🐙