Autonomous development for Claude Code — driven by your Kanban board, or by local plan files.
Warning
Clancy is in early development. Expect bugs, breaking changes, and rough edges. If you hit an issue, please open a bug report.
npx chief-clancyWorks on Mac, Linux, and Windows.
What it does · Install · Commands · Supported boards · Comparison · Contributing
Named after Chief Clancy Wiggum (The Simpsons) — built on the Ralph technique by Geoffrey Huntley. See credits →
Clancy does six things:
- Scaffolds itself into a project — scripts, docs, CLAUDE.md, .clancy/.env
- Scans your codebase with 5 parallel specialist agents and writes structured docs that Claude reads before every run
- Writes strategy briefs — interviews you (or runs a devil's advocate AI-grill in AFK mode), decomposes work into vertical slices with HITL/AFK classification, and creates board tickets with blocking dependencies
- Plans tickets — fetches backlog tickets, explores the codebase, and generates structured implementation plans posted as comments for human review
- Runs autonomously — picking one ticket per loop from your Kanban board (skipping blocked candidates), implementing it, committing, and creating a PR (targeting an epic branch for parented tickets, or the base branch for standalone tickets). Also supports local plan execution via
--from— no board needed, just plan files - Verifies before delivery — runs lint, test, and typecheck via verification gates with self-healing retry, guards against force push and destructive resets, and recovers from crashes via lock file detection
Brief → approve → plan → implement. Pipeline labels (clancy:brief → clancy:plan → clancy:build) move tickets between stages automatically. One ticket per run. Fresh context window every iteration. No context rot.
Clancy is for developers who:
- Use a Kanban board (Jira, GitHub Issues, Linear, Shortcut, Notion, or Azure DevOps) and want Claude to work through their backlog unattended — or work solo without a board and want Claude to execute local plan files (
.clancy/plans/*.md) instead - Are comfortable with Claude Code and want to extend it for team workflows — not just solo hacking
- Have a codebase with enough structure that an AI agent can make meaningful progress on a unit of work without constant hand-holding
- Want to go AFK and come back to committed, merged work
Clancy is not for you if:
- You want to supervise every change — use Claude Code directly instead
- Your tickets or plans are large, vague, or span multiple sessions — Clancy works best with small, well-scoped units
- You don't want any structure — Clancy assumes either a board or an approved plan file; it won't invent the target itself
Evaluating other tools? See COMPARISON.md for a side-by-side with GSD and PAUL.
Clancy is powerful but not magic. Here's what to expect:
It will get things wrong sometimes. Claude can misread a ticket, make the wrong architectural choice, or produce code that doesn't compile. This is normal. Use /clancy:implement to watch the first few runs, then review the output before going fully AFK. Over time you'll learn which ticket types Clancy handles well on your codebase.
Ticket quality matters more than you think. A vague ticket produces vague implementation. Clancy works best when tickets have a clear summary, a description that explains the why, and concrete acceptance criteria. Use /clancy:review to score a ticket before running — it'll tell you exactly what's missing.
You still own the code. Clancy pushes a feature branch and creates a pull request for every ticket — targeting an epic branch for parented tickets, or the base branch for standalone ones. When all children of an epic are done, Clancy creates a final PR from the epic branch to your base branch. Either way, treat it like code from a junior developer who works very fast — it needs a sanity check, not a full rewrite.
Some tickets will need a retry. If Claude gets stuck or produces something obviously wrong, delete the branch and run /clancy:implement again. Fresh context, fresh attempt. If it fails twice on the same ticket, the ticket probably needs more detail.
Clancy is token-heavy. Each ticket starts a fresh Claude session that reads your codebase docs, CLAUDE.md, and then implements the ticket — before writing a single line of code, it has already consumed significant context. Rough estimates per ticket:
| Ticket complexity | Approximate total tokens | Approximate cost (Sonnet) |
|---|---|---|
| Simple (small change, clear scope) | 50,000–100,000 | $0.25–$0.75 |
| Medium (feature, 5–15 files touched) | 100,000–250,000 | $0.75–$2.00 |
| Complex (large feature, many files) | 250,000–500,000+ | $2.00–$5.00+ |
These are rough estimates — actual usage depends on your codebase doc size, how many files Claude reads during implementation, and how much code it writes. Check Claude Code's usage dashboard after your first /clancy:implement run to see real numbers for your codebase.
A few ways to manage costs:
- Use a lighter model — set
CLANCY_MODEL=claude-haiku-4-5in.clancy/.envfor simpler tickets (significantly cheaper, less capable) - Keep
.clancy/docs/files concise — they're read in full on every ticket - Use small, well-scoped tickets — fewer files read, less output generated
- Jira — via REST API v3, JQL, ADF description parsing
- GitHub Issues — via REST API with PR filtering
- Linear — via GraphQL,
viewer.assignedIssues,state.type: unstarted - Shortcut — via REST API v3, workflow state resolution, epic stories
- Notion — via REST API, database rows as tickets, property name overrides
- Azure DevOps — via REST API, work items, org + project scoping
Community can add boards — see CONTRIBUTING.md.
npx chief-clancyYou'll be asked: global install (~/.claude) or local (./.claude). Either works. Global makes commands available in all projects. Runtime bundles and project state always go to .clancy/ at project root — see Two Directory Trees for the full layout.
Prerequisites:
- Claude Code CLI installed
- Node.js 24+ (
node -v) gitinstalled (comes with most development environments)
Clancy is designed to run Claude with --dangerously-skip-permissions:
claude --dangerously-skip-permissionsTip
This is how Clancy is intended to be used — stopping to approve git commit and node 50 times defeats the purpose. Only use it on codebases you own and trust.
With a Kanban board:
# 1. Install Clancy commands
npx chief-clancy
# 2. Open a project in Claude Code, then:
/clancy:init
# 3. Scan your codebase (or say yes during init)
/clancy:map-codebase
# 4. Preview the first ticket (no changes made)
/clancy:dry-run
# 5. Watch your first ticket
/clancy:implement
# 6. Go AFK
/clancy:autopilot
# Fully autonomous (no prompts at any step):
# /clancy:brief --afk #42 → /clancy:approve-brief --afk → /clancy:autopilotWithout a board — local plan-driven flow:
# 1. Install Clancy commands (same as above)
npx chief-clancy
# 2. Open a project in Claude Code, then answer "No" when asked about a board.
# When /clancy:init asks about optional roles, enable BOTH Strategist and
# Planner — the local flow uses /clancy:brief (Strategist) and /clancy:plan
# (Planner). Without them, those commands won't be installed.
/clancy:init
# 3. Scan your codebase
/clancy:map-codebase
# 4. Draft a strategy brief from an outline file, then decompose into plans:
/clancy:brief --from outline.md
/clancy:plan --from .clancy/briefs/<brief>.md
# 5. Approve the plan (writes a .approved marker file):
/clancy:approve-plan .clancy/plans/<plan>.md
# 6. Implement one plan, or all approved plans in the directory AFK:
/clancy:implement --from .clancy/plans/<plan>.md
/clancy:implement --from .clancy/plans/ --afk| Command | Description |
|---|---|
/clancy:brief ² |
Grill phase → strategy brief → vertical slice decomposition → tickets |
/clancy:approve-brief ² |
Review and approve a strategy brief, then create board tickets |
/clancy:plan ¹ |
Refine backlog tickets into structured implementation plans |
/clancy:plan 3 ¹ |
Plan up to 3 tickets in batch mode |
/clancy:approve-plan ¹ |
Board: promote the approved plan to the ticket description. Local: write a sibling .approved marker (SHA-256 + timestamp) — a write-side contract today; runtime gate enforcement is deferred |
/clancy:init |
Wizard — optionally connect a board (or skip for local plan-driven mode), collect config, scaffold everything |
/clancy:autopilot |
Loop mode — processes board tickets until queue is empty or MAX_ITERATIONS hit (requires a board) |
/clancy:autopilot 20 |
Same, override MAX_ITERATIONS to 20 for this session |
/clancy:implement |
Pick up one ticket and stop |
/clancy:implement --from <plan.md> |
Implement a single local plan — no board needed. Approval is enforced manually or by convention today (runtime .approved marker gate is deferred) |
/clancy:implement --from <dir> --afk |
Local batch (wired via runImplementBatch): naturally sorts .md plans in the directory, skips any without a sibling .approved marker, executes approved plans sequentially. Marker SHA-256 verification is not yet wired — only marker existence is checked |
/clancy:dry-run |
Preview next ticket without making changes — no git ops, no Claude call |
/clancy:status |
Show next tickets without running — read-only |
/clancy:review |
Score next ticket (0–100%) with actionable recommendations |
/clancy:logs |
Format and display .clancy/progress.txt |
/clancy:map-codebase |
Full 5-agent parallel codebase scan, writes structured docs |
/clancy:update-docs |
Incremental refresh — re-runs agents for changed areas |
/clancy:settings |
View and change configuration — model, iterations, board, and more |
/clancy:doctor |
Diagnose your setup — test every integration, report what's broken |
/clancy:update-terminal |
Update the full Clancy pipeline to latest version |
/clancy:update-brief ³ |
Update brief commands only (--afk skips confirmation) |
/clancy:update-plan ³ |
Update plan commands only (--afk skips confirmation) |
/clancy:update-dev ³ |
Update dev commands and bundles (--afk skips confirmation) |
/clancy:uninstall-terminal |
Remove the full Clancy pipeline — detects standalone packages and warns before removing |
/clancy:uninstall-brief ³ |
Remove brief commands only (installed via npx @chief-clancy/brief) |
/clancy:uninstall-plan ³ |
Remove plan commands only (installed via npx @chief-clancy/plan) |
/clancy:uninstall-dev ³ |
Remove dev commands; project-scoped also removes bundles (npx @chief-clancy/dev) |
/clancy:help |
Command reference |
¹ Planner is an optional role — see Roles below. ² Strategist is an optional role — see Roles below. ³ Standalone uninstall commands are available when the corresponding package is installed.
Clancy organises its commands into roles — each role handles a different stage of the development workflow.
| Role | Purpose | Commands |
|---|---|---|
| Implementer | Plan → code. Picks up tickets, implements, commits, creates PRs | /clancy:implement, /clancy:autopilot, /clancy:dry-run |
| Reviewer | Score ticket readiness and track progress | /clancy:review, /clancy:status, /clancy:logs |
| Setup | Configure and maintain Clancy | /clancy:init, /clancy:settings, /clancy:doctor, etc. |
| Planner (optional) | Refine backlog tickets into structured implementation plans | /clancy:plan, /clancy:approve-plan |
| Strategist (optional) | Grill → brief → vertical slices → board tickets | /clancy:brief, /clancy:approve-brief |
Core roles (Implementer, Reviewer, Setup) are always installed. Optional roles (Planner, Strategist) are opt-in — add them to CLANCY_ROLES in .clancy/.env and re-run the installer:
# Enable optional roles
echo 'CLANCY_ROLES="planner,strategist"' >> .clancy/.env
npx chief-clancy@latest --local # or --globalYou can also toggle roles from within Claude Code using /clancy:settings.
Each role has detailed documentation:
- Implementer — picks up tickets, implements, commits, creates PRs (AFK loop support)
- Reviewer — scores ticket readiness, tracks progress
- Setup & Maintenance — init wizard, settings, diagnostics, codebase mapping
- Planner — refines backlog tickets into structured implementation plans
- Strategist — grill phase, strategy briefs, vertical slice decomposition, board ticket creation
For a visual overview of how roles, commands, and flows connect, see the Visual Architecture diagrams.
The whole .clancy/ tree is gitignored — Clancy never commits anything inside it. Entries below are local-only.
.clancy/
clancy-implement.js — picks up one ticket, implements, commits, creates PR
clancy-autopilot.js — loop runner (board-agnostic)
docs/ — structured docs read before every run
STACK.md
INTEGRATIONS.md
ARCHITECTURE.md
CONVENTIONS.md
TESTING.md
GIT.md
DESIGN-SYSTEM.md
ACCESSIBILITY.md
DEFINITION-OF-DONE.md
CONCERNS.md
progress.txt — append-only log of completed tickets
.env — your board credentials
.env.example — credential template for your board
Clancy also merges a section into your CLAUDE.md (or creates one) that tells Claude to read all these docs before every run.
This is a monorepo with eight packages:
| Package | Purpose |
|---|---|
chief-clancy |
CLI wrapper — npx chief-clancy delegates to terminal |
@chief-clancy/terminal |
Installer, slash commands, hooks, runners, agents |
@chief-clancy/core |
Board integrations, pipeline phases, lifecycle modules, schemas |
@chief-clancy/scan |
Shared codebase scanning agents and workflows (map-codebase, update-docs) |
@chief-clancy/brief |
Standalone brief generator — npx @chief-clancy/brief (no board required) |
@chief-clancy/plan |
Standalone implementation planner — npx @chief-clancy/plan |
@chief-clancy/dev |
Standalone ticket executor — npx @chief-clancy/dev |
@chief-clancy/design |
Standalone AI-design tool — clancy-design bin (Phase F in-progress; not yet published) |
Dependency direction: core ← dev ← terminal ← chief-clancy. Brief, plan, scan, and design are standalone (no core/terminal deps). See ARCHITECTURE.md for the full module map.
Clancy supports optional enhancements — Figma design specs, Playwright visual checks, status transitions, and Slack/Teams notifications. All are configured via .clancy/.env or /clancy:settings.
See Configuration guide for full details and all environment variables.
Clancy is built on the Ralph technique coined by Geoffrey Huntley (ghuntley.com/ralph).
Ralph in its purest form:
while :; do cat PROMPT.md | claude-code; doneClancy is what happens when you take that idea seriously for team development. See CREDITS.md for the full story.
Clancy runs Claude with --dangerously-skip-permissions for unattended operation. It includes a credential guard hook, branch guard hook, recommended permission deny lists, and token scope guidance.
See Security guide for full details — permissions model, credential protection, token scopes, and webhook security.
Start here: run /clancy:doctor — it tests every integration and tells you exactly what's broken and how to fix it.
See Troubleshooting guide for common issues and solutions.
| Document | What it covers |
|---|---|
| Architecture | Package hierarchy, directory structure, pipeline phases, board abstraction |
| Visual Architecture | Mermaid diagrams — flows, roles, hooks, delivery paths |
| Technical Reference | Implementation details, board gotchas, env var behaviour |
| Testing | Vitest configs, test patterns, E2E setup, CI schedule |
| Lifecycle | End-to-end ticket journey from idea to merged code |
| Configuration | All env vars, queue filters, pipeline labels |
| Security | Permissions, credential guard, token scopes |
| Troubleshooting | Common issues and solutions |
| Comparison | Clancy vs GSD vs PAUL |
| Credits | The Ralph technique and Geoffrey Huntley |
See CONTRIBUTING.md. The most useful contribution is adding a new board — it's a TypeScript module + a JSON entry.
MIT — see LICENSE.