Reading the repo
Opening the box…
Reading the repo
Opening the box…
How to install on Windows
Saved setup from 17 h ago
Will it work on Windows?
CONTRIBUTING.mdAutoCraft uses a TypeScript backend with a SQLite database and a separate web frontend. Refer to the README for setup, pipeline documentation for stage details, and operations for running the service.
Key directories:
src/cli.ts: CLI entry point.src/runner/: Pipeline execution.src/stages/registry.ts: Stage definitions.src/github/write.ts: GitHub API writes.src/dash/ and web/: Dashboard and frontend.test/: Test suite.package.json declares Node >=24 and the project’s pnpm version. These commands are available:
pnpm test # Run the test suite
pnpm check # TypeScript and generated-document checks
pnpm docs # Regenerate marked documentation blocks
pnpm -C web dev # Frontend development server with mock data; no backend integration
To test backend integration, build the frontend without VITE_MOCK=1 and follow the dashboard setup. The operations guide explains how the backend serves the frontend build.
The documentation generator updates marked blocks in the README and docs/pipeline.md; it does not validate the surrounding prose.
Then run powershell -ExecutionPolicy Bypass -File .\setup.ps1. It stops at the first error and is safe to run again. Servers and tests aren't started; it lists them at the end. Read it first.
Needs Git: winget install Git.Git
git clone https://github.com/storytold/autocraft.git cd autocraft
Node.js >=24
winget install CoreyButler.NVMforWindows nvm install lts nvm use lts
corepack enable pnpm install
pnpm test
| 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 |
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.
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.
Create an OAuth App on GitHub:
https://autocraft.example.com.https://autocraft.example.com/auth/callback. It must equal <AUTOCRAFT_BASE_URL>/auth/callback exactly.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 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.
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
…
No reports for Windows yet.
GitManual AI Agent reads the 6 key files and writes a step-by-step guide for Windows. Once written, it's saved for everyone.