AutoCraft
AutoCraft is a model harness for maintaining GitHub repositories with a large backlog. It mirrors every issue and PR into a local database and runs a pipeline of model steps over them. Jev classifiers and Claude Haiku, Sonnet and Opus classify, prioritise, find duplicates, ask maintainers for decisions, review, write fixes, verify and merge.
The models' tools are a fixed set of GitHub actions (comments, labels, branches, PRs, merges), all behind one write module and safe-merge-style checks. Actions run automatically where the rules say they are safe. Otherwise a model proposes and a person accepts. Each issue and PR has its own conversation between Opus and a maintainer, with action cards the maintainer can run. The pipeline is built around maintainers' judgement, which is the limited resource, not around token cost.
It was written for the storytold craft apps. The organization name is a constant (ORG in src/mirror.ts and src/act/templates.ts); tracking another organization means changing it.
How it works
Stages run in this order. Details, limits and rules for each are in docs/pipeline.md.
| Stage | What it does | Model | Stops for a person |
|---|---|---|---|
| Sync | Mirrors issues, PRs and comments every minute | none | no |
| Embed | Vectors from title and body, for similar-item search | local embedding model | no |
| Duplicates | Finds items that describe the same bug or request, compares each group | Jev, Haiku, Sonnet, Opus | yes: Duplicate? decision |
| Classify | One type label and two flags (security, needs decision) per item | Jev, Haiku, Sonnet referee | labels the models disagree on |
| Priority | P0 to P4 per item | Jev, Haiku | no |
| Decide | Scope questions with a summary and a recommendation | Sonnet, Opus | yes: an operator answers |
| Label | Writes settled labels to GitHub | none | per-repo approval |
| Review | Opus review of every wanted PR; reads the repo | Opus | hold, close and merge-outside-rule verdicts |
| Fix | Writes a patch for clear bugs, opens a PR | Sonnet, Opus check | per-repo approval |
| Fix-up | Pushes fixes to a PR branch | Sonnet, Opus check | per-repo approval |
| Verify | Builds and tests the PR in a build environment | Sonnet plans | failures and errors |
| Merge queue | Merges PRs that pass the rules, through safe-merge |
none | Merge? decision for PRs outside the rules |
| Act | Applies answered decisions: comments, closes | none | per-repo approval |
The image is the dashboard's home page (mock data). Each column is a stage with its counts, and the chips above it list what waits for a person.
Trust boundaries
- Untrusted code runs only in a separate build environment (a worker as another OS user, with rootless Podman), never where GitHub or Claude credentials are.
- Model calls that use tools run inside a bubblewrap sandbox. They get
Read,GrepandGlobon read-only checkouts of the public tracked repos, a Haiku explorer subagent, and read-only item tools (search, item, similar items, PR diff) over a snapshot of the public items. Other calls run without tools. - Only
src/github/write.tswrites to GitHub. Every write is recorded in an audit table, and a test fails if another file writes. - Every GitHub write needs an operator's approval for that repo. Approvals are given on the dashboard and cannot be set from the CLI.
- The dashboard needs GitHub sign-in. Roles are
operator(answers, approvals, switches, accounts),maintainer(read and comment) andviewer(read only). - A pipeline switch (on/off) turns the whole pipeline off, a per-repo pipeline switch limits it to chosen repos, and each step has a daily limit.
See Trust boundary.
Setup
Requirements
| Needed | Used for |
|---|---|
Node 24 or later (engines in package.json), pnpm |
Runs the TypeScript directly; SQLite through the built-in node:sqlite |
gh, logged in |
Sync (gh api graphql) and every GitHub write |
git |
Clones, diffs and pushes |
claude (Claude Code CLI) |
All Claude calls |
bwrap (bubblewrap, /usr/bin/bwrap) |
Sandbox for tool-using calls. Without it, those calls run without tools; AUTOCRAFT_NO_SANDBOX=1 forces that |
jev (optional) |
CLI for TypeSafe's Jev model, used by the classify, priority and duplicate steps (jev --compact ask). Without it, switched off (autocraft accounts jev off), or when its account is out of credit or its key is rejected, Haiku does Jev's work through the Claude accounts (more Claude usage) |
| Podman and a second OS user | Build environments for Verify and Fix (optional) |
sqlite3, curl |
deploy/backup.sh and deploy/hook.sh |
Install
git clone https://github.com/aiongg/autocraft.git
cd autocraft
pnpm install
pnpm -C web install && pnpm -C web build # writes web/dist
node src/cli.ts # lists every command
autocraft is the bin of package.json; node src/cli.ts <command> runs the same program. The database is $AUTOCRAFT_DB, default ~/.local/share/autocraft/mirror.db.
GitHub access
gh needs an account with read access to the tracked repos for Sync. The same account writes (labels, comments, closes, pushes, merges) in the repos an operator approves, so it needs write access there.
Dashboard sign-in (GitHub OAuth App)
Create an OAuth App on GitHub:
- Homepage URL: your dashboard origin, for example
https://autocraft.example.com. - Authorization callback URL:
https://autocraft.example.com/auth/callback. It must equal<AUTOCRAFT_BASE_URL>/auth/callbackexactly. - No scopes are requested. Expiring user tokens are supported.
Write the client ID, client secret and a random session key (at least 32 characters) to a JSON file with mode 0600:
{ "github_client_id": "...", "github_client_secret": "...", "session_key": "..." }
Point AUTOCRAFT_SECRETS_FILE at it. The server refuses to start if the file is missing, incomplete, or readable by group or others.
| Variable | Meaning |
|---|---|
AUTOCRAFT_BASE_URL |
Public origin of the dashboard, no path |
AUTOCRAFT_LISTEN |
host:port, default 127.0.0.1:8993 |
AUTOCRAFT_DB |
Database path |
AUTOCRAFT_SECRETS_FILE |
The secrets file above |
AUTOCRAFT_WEB_DIST |
Built frontend, default web/dist |
AUTOCRAFT_TRUST_PROXY |
1 behind a proxy that sets X-Forwarded-For |
The server speaks plain HTTP; put a reverse proxy with HTTPS in front. More variables are in docs/operations.md.
Claude accounts
Claude calls run under accounts that an operator enables. Each account is a Claude Code config directory that is logged in. Describe them in a JSON file and set AUTOCRAFT_ACCOUNTS to its path:
[{ "id": "a", "configDir": "/srv/autocraft/config/claude/a" }]
configDir becomes CLAUDE_CONFIG_DIR of the claude child process. Related variables:
| Variable | Meaning |
|---|---|
AUTOCRAFT_ACCOUNTS_ROOT |
Directory for accounts added on the dashboard's Accounts page, which runs claude auth login for you |
AUTOCRAFT_USAGE_DIR |
One <id>.json per account with its rate-limit readings |
AUTOCRAFT_CLAUDE_BIN |
The claude command, default from PATH |
New accounts start disabled. Enable and size them:
autocraft accounts list
autocraft accounts set a --label main --enabled yes --max-concurrent 3
autocraft accounts jev 4 # parallel Jev calls
autocraft accounts jev off # Haiku does Jev's work; `on` switches Jev back on
See Claude accounts and agent runs.
Track repos and sync
autocraft repos track <name> # a repo of the organization, without the owner
autocraft repos list
autocraft sync # first sync of the tracked repos
A newly tracked repo has its pipeline off: only Sync, Embed and Rank run for it. After the first sync, autocraft sync runs every minute from a timer (deploy/systemd/autocraft-sync.timer). autocraft embed fills the vectors; the first run downloads a 34 MB embedding model.
Start the dashboard and add the first operator
autocraft access add <github-login> --operator
autocraft dash serve
Sign in at the base URL. Further users are added on the Access page or with autocraft access add <login> [--maintainer]. Then, on the dashboard:
- Repos page: approve each repo for the writes you want (labels, comments, fixing, pushing, merging) and switch its pipeline on.
- Run the runner:
autocraft runner serve. It is the only process that runs steps. - Pipeline page: turn the pipeline on, or
autocraft pipeline on. Set daily limits withautocraft pipeline limit <step> --per-day N.
AUTOCRAFT_DEV_AUTH=1 autocraft dash serve starts a local server with a fake GitHub sign-in on 127.0.0.1:8994, with no secrets file.
Deployment
deploy/ holds a production layout that runs the dashboard, runner, sync timer and a daily backup as systemd units of one unprivileged user. It deploys by git push to a bare repository.
| File | Use |
|---|---|
autocraft.env.example |
Settings file, for example /srv/autocraft/config/autocraft.env |
systemd/ |
Dashboard, runner, sync and backup units (@ROOT@, @USER@ placeholders) |
post-receive, hook.sh, push.sh |
Push-to-deploy: builds a release directory and switches the app symlink |
backup.sh |
Consistent SQLite snapshots |
craft-runner.service, craft-worker.service |
User units for the runner and the sandbox worker |
Details, including the worker and build environments: docs/operations.md.
Development
pnpm test # node --test
pnpm check # tsc --noEmit
pnpm -C web dev # frontend on http://127.0.0.1:5173 with mock data
VITE_MOCK=1 pnpm -C web build # static mockup build, no server needed
The mock API serves fixture data; pick the role with ?as=operator|maintainer|viewer. See web/README.md and docs/ui-design.md.
| Path | Contents |
|---|---|
src/cli.ts |
Entry point; commands come from modules listed in MODULES |
src/mirror.ts, src/db.ts, src/schema.sql |
Sync and the SQLite schema |
src/classify, src/priority, src/dupes, src/embed, src/rank |
Classification, priority, duplicates, embeddings, work rank |
src/decide, src/conversations, src/act |
Decisions, Opus conversations and cards, applying answers |
src/review, src/fixissue, src/fixup, src/verify, src/merge |
Review, fix, fix-up, verify, merge queue |
src/agents, src/prompts, src/sandbox, src/itemtools |
Claude accounts and calls, prompts, bubblewrap, read-only item tools |
src/github |
write.ts, the only module that writes to GitHub |
src/runner, src/worker, src/build |
Job runner, sandbox worker, build environments |
src/dash, src/flow |
Dashboard server, API and flowchart counts |
web/ |
React frontend |
test/ |
Tests |
docs/ |
pipeline.md, dashboard-spec.md, ui-design.md, operations.md |
License
AutoCraft is dual-licensed under MIT or Apache-2.0, at your option.
