ClutchWork
CLI Lifecycle for Unattended Ticket-Chewing Hatchlings
ClutchWork is an engine that runs CLI coding agents through the ticket lifecycle against a git repository. Each ticket lives in tickets/<stem>/; its markdown and JSON files, including ticket.md, run.md, review.md, diagnosis.json, and others, pass work between stages. Reviewed work merges to local main. See the ticket lifecycle diagram.
Install
Add clutch to your host project and sync its environment:
uv add --dev clutch
uv sync
Install the provider CLIs you route with uv run clutch install claude codex (pnpm dev dependencies under node_modules/.bin; a CLI already on PATH works without it).
Run its verbs as uv run clutch <verb>. Your host also needs config.yaml; start with the copyable configuration, or create one with uv run clutch init-config --write from the CLIs you installed.
Set up a host
Run uv run clutch doctor, then uv run clutch core to write the managed conduct block into CLAUDE.md for Claude and Qwen Code or AGENTS.md for other CLIs. Commit the files. The block gives a chat agent rules for authoring and editing tickets with clutch new, clutch lint, and clutch review, and for supervising a drain. Re-run core after upgrading clutch: drain, serve, and run refuse to start while the block is stale.
The working loop
- Open Claude Code or Codex in the host checkout, often with auto permissions.
- Work out a plan with the chat agent.
- Ask it to turn the plan into tickets. It runs
clutch new, fills each ticket, and repeatsclutch lintandclutch reviewuntil each is clean. - Ask it to drain the queue with
uv run clutch drain, or leaveuv run clutch serverunning to pick up new tickets live. clutch coordinates CLI agents through authoring, implementation, checking, review, and merge. - Ask the chat agent to supervise: watch
clutch statusandclutch watch, diagnose rejected or blocked tickets from theirtickets/<stem>/artifacts, fix small ticket problems, and stop withclutch stoporclutch killand restart the drain as needed. - Use the Suggestion Box as an escape valve. An implementing agent reports second problems in its
second_problemsreply, and the engine files them to the box so the ticket can complete its own goal. Runs that exhaust attempt caps, retros, andclutch suggestfrom a chat session also file there. Triage resolves each message asdeclined,tombstone(already covered), or authored into a ticket; an authored ticket can start as adraftawaiting a person. - Keep the judgment calls: ask the chat agent for a plain-English summary of each draft or held ticket, then run
clutch confirmorclutch rejecton each.
In clutch's own repository history, measured on 2026-11-09 from .clutch/state/box/ and the journal, 32 of 389 Suggestion Box messages (about 8%) became tickets, all as drafts. Of the 31 drafts decided, 24 were confirmed (about 77%) and 7 rejected.
One unattended drain ran about 30 tickets in about 4 hours, many of them triage-authored bug fixes and small features. The practical limit is how fast a person can plan enough work to fill the queue, so planning sessions with the chat agent are where the person spends their time.
For example, ask your chat agent:
- “Help me plan this feature and turn the plan into clutch tickets.”
- “Drain the queue and supervise any held tickets.”
- “Summarize the drafts in plain English so I can decide which to confirm.”
Commands
# Setup
uv run clutch init-config # print a suggested config.yaml
uv run clutch install # install provider CLIs into the host
uv run clutch update-config # list current model names per provider
uv run clutch doctor # inspect host setup
uv run clutch core # refresh managed conduct files
# Authoring
uv run clutch new # create and lint a ticket skeleton
uv run clutch lint # validate tickets without writing
uv run clutch review # review a committed ticket
uv run clutch order # edit ticket priority or ordering
uv run clutch suggest # file an idea into the Suggestion Box
# Running
uv run clutch drain # run eligible tickets to quiescence
uv run clutch serve # run the continuous daemon
uv run clutch run # run one ticket through the pipeline
uv run clutch stop # finish active work and exit
uv run clutch kill # stop the engine at a safe point
uv run clutch pause # ask the engine to pause admission
uv run clutch resume # ask the engine to release its current hold
# Observing
uv run clutch status # show the journal projection
uv run clutch watch # show the live text view
uv run clutch stats # show health and efficiency figures
# Decisions
uv run clutch confirm # confirm a draft or Reject item
uv run clutch reject # reject a draft or Reject item
Stop serve before drain or run: each takes the writer lock. See the host run guide for every verb.
VS Code extension
The clutch tickets extension (chunkydragon.vscode-clutchwork) shows the ticket graph, details, recent steps, Suggestion Box, and stats. Set clutch.command when the engine command differs from the default host .venv/bin/clutch.
Docs
- Host run guide: invocation and operation on a host.
- Host ticket authoring: what to write in a ticket.
- Host contract: the config schema and host-facing contract.
- How clutch works: how clutch behaves today. Tickets keep it current.
Developing clutch
This section is for working on clutch itself. In this repo, run engine verbs with uv run clutch and tests with ./dev.py:
uv run clutch new STEM [--kind feature|bug|chore] [--evidence FILE...] # write a ticket skeleton
uv run clutch lint [STEM...] # check tickets
uv run clutch review STEM... # review tickets against merged code
uv run clutch drain # run every eligible ticket to quiescence
uv run clutch status # what ran, what is held, total spend
uv run clutch confirm STEM / uv run clutch reject STEM # keep or kill a held ticket
uv run clutch kill # stop a running drain
./dev.py test [args] # run the test suite
CLUTCH_PLAN.md is the frozen record of how clutch was first built. It is history, not a reference.
Every clutch verb is listed in how clutch works, section 2.
Metadata
Release files for clutchwork 0.2.4
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| clutchwork-0.2.4.tar.gz | 260.7 kB | Without provenance | Details for clutchwork-0.2.4.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| clutchwork-0.2.4-py3-none-any.whl | Python 3 | none | any | Details for clutchwork-0.2.4-py3-none-any.whl |
Total release size: 564.0 kB
Release files / clutchwork-0.2.4.tar.gz
| Download URL | clutchwork-0.2.4.tar.gz |
|---|---|
| Size | 260.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
10d65218bfe647f8970a6e8071a1d75805c09b2b0577f0478d44a350c183e04f
|
|
BLAKE2b-256 checksum How to use checksums |
841478b4c01ca31aefe072a590b7fe4c486cc7923a628afbe154dfd51ff15ab3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.32 {"installer":{"name":"uv","version":"0.11.32","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / clutchwork-0.2.4-py3-none-any.whl
| Download URL | clutchwork-0.2.4-py3-none-any.whl |
|---|---|
| Size | 303.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
177128799ef230b0e28e8dbb3407812ce5fa1d612c94156973f1179d09920193
|
|
BLAKE2b-256 checksum How to use checksums |
aacc67375ce57c79276b120ff7a31e1a4715f7469c92691309c873e977a591d9
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.11.32 {"installer":{"name":"uv","version":"0.11.32","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for clutchwork 0.2.4
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.