Skip to main content

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.

GitHub repository

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

  1. Open Claude Code or Codex in the host checkout, often with auto permissions.
  2. Work out a plan with the chat agent.
  3. Ask it to turn the plan into tickets. It runs clutch new, fills each ticket, and repeats clutch lint and clutch review until each is clean.
  4. Ask it to drain the queue with uv run clutch drain, or leave uv run clutch serve running to pick up new tickets live. clutch coordinates CLI agents through authoring, implementation, checking, review, and merge.
  5. Ask the chat agent to supervise: watch clutch status and clutch watch, diagnose rejected or blocked tickets from their tickets/<stem>/ artifacts, fix small ticket problems, and stop with clutch stop or clutch kill and restart the drain as needed.
  6. Use the Suggestion Box as an escape valve. An implementing agent reports second problems in its second_problems reply, and the engine files them to the box so the ticket can complete its own goal. Runs that exhaust attempt caps, retros, and clutch suggest from a chat session also file there. Triage resolves each message as declined, tombstone (already covered), or authored into a ticket; an authored ticket can start as a draft awaiting a person.
  7. Keep the judgment calls: ask the chat agent for a plain-English summary of each draft or held ticket, then run clutch confirm or clutch reject on 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

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)

Source distribution for clutchwork 0.2.4
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)

Table of built distributions (wheels) for clutchwork 0.2.4
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page