What it does
Implements
Reads gspec feature files. Writes code. Pushes to CI. Fixes lint and test failures automatically until the pipeline goes green.
Reviews
Watches PR webhooks. Reads diffs as a principal engineer. Leaves inline comments, pushes fixes, and approves when the code is clean.
Ships
Audits for spec drift after each feature. On ratchet approval, merges the PR and advances to the next feature in the queue.
Pipeline
From spec to merge
crank reads spec,
writes & pushes code
tests run,
lint checks pass
crank checks drift
against spec
pull request
created
ratchet reads diff,
fixes & approves
merged, next
feature starts
Live output
What a run looks like
Get started
Three commands
pip install crank-cliInstalls the CLI. Requires Python 3.11+ and a Claude API key in the environment.
crank initScaffolds config.json and gspec/ in your project. Prompts for repo path and GitHub token.
crank runPicks up feature specs from gspec/features/*.md alphabetically, implements each one, and stops when the queue is empty or a circuit breaker trips.
Built on gspec by @gballer77
Origin
Why this exists
crank is built on gspec — a structured spec format for AI-assisted development, built by @gballer77. Writing specs was fast. Getting Claude to implement them was fast. But the workflow was still manual: copy spec, paste into Claude, review output, commit, repeat. Each feature was four context switches and a clipboard paste away from shipping.
So the first version of crank was a shell script. It read a spec file, invoked Claude with the right flags, committed the output, and moved to the next file. Crude, but it cut the overhead to near zero.
The script grew into a state machine. CI integration, audit phases, circuit breakers, token budgets. It could implement a feature autonomously — but it still needed a human to review the PR.
That's where ratchet came in. A GitHub App wired to the same Claude backend, watching PR webhooks, reading diffs as a principal-level engineer. It leaves inline comments, pushes fixes directly, and approves when the code is clean. Max five review iterations before it escalates.
The names are mechanical on purpose. A crank converts energy into work — repetitive, reliable, no judgment required. A ratchet locks each tooth of progress in place: you can only move forward. Together they close the loop: spec in, merged feature out, no humans in the critical path.