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.
Originally written for the storytold craft apps, AutoCraft can also track repositories owned by other GitHub organizations or users via autocraft repos track owner/name without requiring source edits. See Track repos and sync for naming and GitHub App sync limitations.
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 every issue, PR and comment of the tracked repos into the local database each minute, reads the CI state of each default branch every 2 minutes, and makes a vector of each item's title and body for similar-item search. | Local embedding model | no |
| Duplicates | Finds items that describe the same bug or request as another open item, or one closed in the last year, and compares each group. | Jev, Haiku, Opus, Sonnet | yes: duplicate? decision |
| Classify | Gives each open item one type label and two flags (security, needs decision). Jev goes first, Haiku gives a second opinion, and a referee settles disagreements outside the scope labels. | Jev, Haiku, Sonnet, Opus | yes: scope disagreements and labels the referees were unsure of (through Decide) |
| Priority | Gives each open item a level from P0 to P4, then orders the candidates of later stages by a work rank. | Jev, Haiku | no |
| Decide | Asks an operator for scope calls, prepares every open decision with a summary, a pick and drafted answers, and answers questions about an item in its conversation. | Haiku, Opus | yes: an operator answers |
| Label | Writes each settled type label and flag to GitHub. A label a person set is never changed. | none | yes: per-repo approval |
| Review | Opus reviews every wanted PR at its current head, reading the repo, and gives a verdict with the complete fix list. It writes nothing to GitHub until the final review is posted. | Opus | yes: hold, close and merge-outside-rule verdicts |
| Fix | Writes a patch for a bugfix issue where the fix is clear, tests it in the sandbox and opens a PR. | Sonnet, Opus, Haiku | yes: per-repo approval |
| Fix-up | For a take-with-fixes review, applies the listed small fixes to the contributor's branch, or posts them as a comment when the branch cannot be pushed to. For a wanted PR whose gate check fails, runs the formatter, reruns an infrastructure failure once, or has a model patch the code. For a red default branch in an approved repo, reruns a flaky failure once and asks an operator about reporting an infrastructure failure. | Sonnet, Opus, Haiku | yes: per-repo approval |
| Verify | Records upstream CI as the verification of taken PRs in repos that have it. A repo without CI, and a bugfix that changes a test file, get a model-planned build in a build environment; a model summarises failures. With the Screenshots feature on, a UI pull request is also rendered at the base and at the head, and a model compares the images; a clear regression holds the merge. | Sonnet, Haiku, Opus | yes: failures and errors |
| Merge queue | Merges PRs that pass the rules in integration batches (up to 50 PRs, checked by upstream CI on the batch PR) through safe-merge, and asks for a Merge? decision on PRs outside the rules. Before a PR the rule would merge goes into a batch, and before a pre-approved merge is handed over to the queue, Opus reviews its head commit once more, adversarially and independently of the first review; a defect it verifies becomes a fix-up or a Merge? question (for a pre-approved merge, a Merge? question). Approves held CI runs of outside contributors where the repo allows it. | Opus | yes: merge? decision for PRs outside the rules |
| Act | Makes the comments and closes that follow an operator's answer, from fixed templates. | none | yes: per-repo approval |
| Post-merge review | Opus reviews each PR the pipeline merged a second time, reading what landed with the pipeline's own commits and reviews of the PR, and lists defects and minor findings. Each defect that no open item covers becomes one follow-up issue in repos approved for commenting, except on a security fix whose advisory is not published yet (its findings are only shown); minor findings are only shown. | Opus | yes: 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). - Contributors' own agents reach the Inbox through an MCP server on the dashboard (
POST /mcp) with a personal token. They act with their user's role, and what they send back is feedback, the same as the dashboard's Feedback box: an operator still answers. MCP decision answering and undo are currently disabled (answering.enabledinsrc/dash/mcp/index.ts), including when GitHub App sign-in is configured. Answer decisions on the dashboard. - 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/storytold/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.
To sign in through a GitHub App instead, register it from the dashboard's GitHub App page (operators only). The dashboard then adds the github_app_* keys (github_app_id, github_app_slug, github_app_private_key, github_app_client_id, github_app_client_secret, github_app_webhook_secret, github_app_owner) to the same file itself, so the file's directory must be writable by the server user. Then choose "GitHub App" as the GitHub identity on the same page; it is refused unless the app covers every tracked repo. AUTOCRAFT_GITHUB_APP_NAME sets the name the registration form suggests.
| 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_GITHUB_APP_NAME |
App name suggested on the registration form, default AutoCraft |
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 new bare name defaults to storytold
autocraft repos track <owner/name> # a repository owned by another organization or user
autocraft repos list
autocraft sync # first sync of the tracked repos
Repo names are unique across owners and case-sensitive. With the GitHub App identity, the app must also be installed on storytold. See Tracked repos.
Newly tracked repositories start with their pipeline disabled. Sync, Embed, and Rank remain available; operator conversations and explicitly fast-tracked items are exceptions to the pipeline-off restriction. For recurring sync, install and enable the supplied systemd timer (deploy/systemd/autocraft-sync.timer) or use the periodic service in the Docker Compose deployment. Running the initial sync does not schedule future runs. autocraft embed populates vectors. With the default model and an empty cache, the first embedding operation downloads the approximately 34 MB model plus supporting files.
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.
Contributors' agents
Maintainers (and operators) can work the Inbox from their own agent: from the user menu (top right, Connect agent) they make an agent token and get the command that adds the Inbox MCP server to Claude Code (claude mcp add --transport http autocraft-inbox <base URL>/mcp --header "Authorization: Bearer <token>"). Then they ask things like "is there anything open in photocraft I can help with?" or "give me 5 PRs that need a fix-up". The agent lists open decisions and held fix-ups, works one through with them locally, and sends their pick and note back as feedback. MCP decision answering and undo remain disabled, even with GitHub App sign-in configured; use the dashboard for these actions. See Inbox MCP server.
Discord mentions (optional)
AutoCraft can count how often tracked items are mentioned in Discord channels you choose, and answer people who mention the bot or use its /autocraft search form to find matching public issues and draft a new one. It reads new messages only and keeps no text and no names. See Discord mentions, replies and search.
- In the Discord developer portal, create an application and add a bot. Under Bot, turn on the Message Content intent.
- Invite the bot with the
botandapplications.commandsscopes and the View Channels, Send Messages, Send Messages in Threads, Add Reactions and Read Message History permissions. Leave everything else off. Under Installation, allow Guild Install only. - Save the bot token in a file readable by the runner only (mode 600), and make a second file of at least 32 random characters for the key that encrypts stored message references (for example
openssl rand -base64 48). Keep the key file: without it the stored links cannot be opened. - Set
AUTOCRAFT_DISCORD_TOKEN_FILEandAUTOCRAFT_DISCORD_KEY_FILEin the env file that both the dashboard and the runner load. The runner needs both paths. The dashboard needs only the key file path: with it the dashboard shows message links and offers Link Discord in the user menu; without it the dashboard shows counts only and hides Link Discord. - Restart the runner. On the Discord page, switch on the channels to watch and enter the contact for deletion requests. The public notice is at
/privacy.
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 |
A Docker Compose deployment is available in deploy/compose/compose.yaml. This deploys the dashboard, runner, and periodic sync/backup service, while sandbox workers run separately. See Running in a container and VPS with Docker Compose.
Details, including the worker and build environments: docs/operations.md.
Development
pnpm test # node --test
pnpm check # typecheck and verify generated documentation
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. The ArtCraft mark in web/public is not covered; see LICENSE-brand.txt.
