handarbeit/fabrik

Automated Claude Code SDLC driver powered by GitHub Issues and Projects.
Fabrik watches a GitHub Project board and drives Claude Code through configurable
workflow stages. Issues are the unit of work — the issue body is the spec, comments
are user input, and the board columns define the workflow.
📖 Documentation, guides, and examples → fabrik.handarbeit.io
## Quick Start
Requires Go 1.27.3+, the Claude Code CLI, and a GitHub token with repo and project scopes.
bash
# Install
go install github.com/handarbeit/fabrik@latest
# Initialize stage configs, plugin, and project config template
# Pass your GitHub Project URL to auto-populate owner, project, and ownertype:
fabrik init --user you https://github.com/orgs/your-org/projects/5
# Or run without a URL for full interactive prompts (TTY) / blank template (non-TTY)
fabrik init
# Creates .fabrik/stages/, .fabrik/plugin/, and .fabrik/config.yaml
# Edit .fabrik/config.yaml with your project settings (commit this file)
# Add your GitHub token to a gitignored .env:
echo 'FABRIKTOKEN=ghp...' >> .env
echo '.env' >> .gitignore
# Run (settings come from .fabrik/config.yaml)
fabrik
# Or override specific values with flags
fabrik --stages ./.fabrik/stages --yolo
Configuration summary:
.fabrik/config.yaml — non-secret project settings (commit to git)
.env — secrets only (FABRIKTOKEN / GITHUBTOKEN; must be gitignored)
Precedence: CLI flag > env var > .env > config.yaml > defaults
### Auto-upgrade
Use --auto-upgrade to have Fabrik self-upgrade at startup and when idle:
bash
fabrik --auto-upgrade ...
At startup and after 2 idle polls, Fabrik upgrades itself automatically and re-execs:
Release binaries: checks GitHub Releases for a newer version and downloads it.
Dev builds (built from source via go build): detects local or remote commits
ahead of the running binary and rebuilds in place from origin/main.
When Fabrik is upgraded, it also compares your .fabrik/stages/.yaml files against the embedded defaults and prints a startup warning for any stage file that is missing fields added in the newer binary. Run fabrik refresh-stages --apply to add the missing keys, then review with git diff and commit. See Stage YAML Drift Warning in the User Guide for details.
## Fabrik PM Plugin (Claude Code Companion)
Install the Fabrik PM plugin in your interactive Claude Code session and Claude answers "what's the status of #42?", "what needs me?" and "is the pipeline healthy?" from your running Fabrik daemon — column, time in column, worker, PR and CI, blockers and what the engine will do next — instead of scraping GitHub.
Run these in any Claude Code session (the fabrik binary must be on your PATH):
/plugin marketplace add handarbeit/fabrik
/plugin install fabrik@fabrik
fabrik init prints the same two commands. After install you get:
Daemon-backed tools — the plugin starts fabrik mcp: fabrikstatus, fabrikboard, fabrikhealth and the rolled-up fabriksituation for state, plus audited overseer actions (promote, advance, set autonomy, re-run Validate, clear a Claude usage-limit hold). No action lifts a pause; a human comment does.
Pushed events — with a subscriber name from --subscriber, FABRIKSUBSCRIBER or CLAUDETOPIC set (the OS-username default names audit comments but starts no push stream), fabriksubscribe / fabrikunsubscribe have the daemon push events into your session as they happen (a settled Validate, a pause, a stalled poll loop, a merge) instead of you polling.