Detroit

an autonomous code factory — tasks in, pull requests out

Drop a markdown task in tasks/, and Detroit drives a coding agent through the whole pipeline — triage → plan → build → test → ship — running your tests and opening a PR with screenshots. It's a shell script you own, not a hosted black box, and it runs on Grok (default), Claude, dotbot, or opencode (a local model).

Tip

One factory.md runs the whole line. A single file at your repo root declares the pipeline and the standards every change must meet — style, build, testing, security — in named sections. Edit it to control exactly what the agent does. Clone a factory, run it anywhere.

How It Works

1. Picks the next task file from tasks/
2. Routes to the repo (local, GitHub, or creates a new one)
3. Agent codes it, runs tests, commits, opens a PR
4. Gates + CI + verify must pass — success → tasks/done/; quality fail after ship → tasks/failed/ (never green on soft failure)

Setup

Detroit expects your repos to live in the parent directory:

projects/
  detroit/        # this repo
  my-app/          # a repo detroit can work on
  another-app/     # another repo

If a repo isn't local, Detroit searches your GitHub account and clones it automatically.

Or set DETROIT_PROJECTS to point elsewhere:

export DETROIT_PROJECTS="$HOME/code"

Usage

./factory.sh                              # run one task (Grok by default)
./factory.sh --dry-run                    # preview what it would pick
./factory.sh --parallel 3                 # run 3 tasks in parallel
./factory.sh --shift                      # keep running tasks until the usage window hits 80%
./factory.sh --issues owner/repo          # pull GitHub issues into tasks/
./factory.sh --verify owner/repo          # re-verify all open PRs
./factory.sh --verify owner/repo 42       # re-verify a specific PR

DETROIT_AGENT=claude ./factory.sh        # use Claude Code instead of Grok
DETROIT_AGENT=dotbot ./factory.sh        # use dotbot instead of Grok
DETROIT_AGENT=dotbot DETROIT_PROVIDER=anthropic ./factory.sh  # dotbot + Anthropic
DETROIT_AGENT=opencode ./factory.sh      # use opencode on a local model (no API key)
DETROIT_MODEL=grok-4.7-build ./factory.sh  # pin the model for every agent call

Run in its own terminal — not inside another tool. Monitor progress in a second terminal:

tail -f logs/*.log

Cancel anytime with Ctrl+C — Detroit cleans up the branch and returns to the default branch.

Web UI

A local dashboard for the factory floor — the task queue, live agent status and stage, streaming logs, and shipped PRs — plus controls to create a task, trigger a run, and approve a plan at the gate.

rustc -O web.rs -o detroit-web    # one-time build (needs Rust)
./detroit-web                     # http://127.0.0.1:4600  (DETROIT_UI_PORT to override)

Run it in a second terminal alongside the factory. Std-only Rust — no crates, one rustc build, no database. It reads and writes the same files factory.sh uses.

Local-only by design: it binds 127.0.0.1 and can start runs, so don't expose it. Runs triggered from the UI approve their plan in the browser (DETROIT_APPROVE_PLAN=web) — the agent pauses at the plan gate until you click Approve or Reject.

Skill

Use Detroit from inside an agent session without leaving it. The skill is a thin router over factory.sh — the agent performs triage/plan/code inline, bash keeps owning locks, worktrees, gates, CI, and ship detection.

detroit run                    # run the next task from tasks/
detroit dry-run                # resolve task/repo/branch, print prompt, run nothing
detroit parallel 3             # spawn 3 factory agents (worktree-isolated)
detroit shift                  # run tasks until the usage window hits 80%
detroit for my-app             # only run tasks whose repo: matches my-app
detroit sync issues owner/repo # pull open issues labeled detroit into tasks/
detroit verify owner/repo      # screenshot open PRs

Full trigger table, gate reference, and prompt fragments live in skills/detroit/SKILL.md. Install it where your agent looks for skills, then call factory.sh flags from the detroit repo root.

Task Format

Each task is a markdown file in tasks/. The filename becomes the task name. The file body is the full prompt sent to the agent — write as much or as little as you need.

Existing repo — add repo: in frontmatter:

---
repo: my-app
---

Add a dark mode toggle to the settings page. Should respect system
preference by default. Use the existing ThemeProvider context.

Screenshot verification — if agent-browser is installed and the project has a dev/start/preview script, Detroit starts the dev server after shipping, reads the git diff to figure out which pages were affected, and uses the agent + agent-browser to take targeted screenshots of the changes. Screenshots are committed to the branch and commented on the PR.

New repo — omit repo: and Detroit creates one (named from the filename):

Build a weather dashboard that shows 5-day forecast.
Use OpenWeatherMap API. Include a search bar for city lookup.

Tasks run in alphabetical order by filename. Prefix with numbers to control priority:

tasks/
  01-fix-auth.md           ← runs first
  02-add-dashboard.md
  03-refactor-api.md

Completed tasks move to tasks/done/.

GitHub Issues

Pull issues from any repo into your task queue:

./factory.sh --issues owner/repo

This fetches open issues labeled detroit and creates task files from them. After the factory completes a task, it comments the PR link on the issue and closes it.

Schedule

Detroit is designed to run unattended. Point cron at it and your issues get solved while you sleep.

Every hour — process one task from the queue:

0 * * * * /path/to/detroit/factory.sh >> /path/to/detroit/detroit.log 2>&1

Every hour — pull new GitHub issues, then process them:

0 * * * * /path/to/detroit/factory.sh --issues owner/repo >> /path/to/detroit/detroit.log 2>&1

Budget shift — one worker runs task after task while the resetting usage window has room, then stops:

0 * * * * /path/to/detroit/factory.sh --shift >> /path/to/detroit/detroit.log 2>&1

A shift reads Omarchy's usage record (~/.local/state/omarchy/agents/usage/$DETROIT_AGENT.json) and stops when the 5-hour session or the weekly window reaches DETROIT_BUDGET_STOP (default 0.80). Only one shift runs at a time, so an hourly cron is safe. A task that fails or stops before SHIP runs once per shift and the rest of the queue keeps going. It sleeps while a focused Herdr workspace has the same agent working, never starts on stale usage, never replays tasks/failed/, and never starts on a prepaid balance. Its log is logs/*-shift.log. Tune with DETROIT_SHIFT_PAUSE (default 30s) and DETROIT_USAGE_MAX_AGE (default 900s). Spec: docs/budget-shift.md.

Night shift — at 01:00 Detroit clocks in: first it spends what your subscription window has left, then a local model takes the rest of the queue:

bash scheduling/install.sh    # systemd user timer: every night at 01:00

The timer runs scheduling/night-shift.sh: one --shift per agent in DETROIT_NIGHT_AGENTS (default grok opencode), in order. The Grok shift stops at DETROIT_BUDGET_STOP like any budget shift, and steps aside while you are using Grok. With opencode the shift skips the usage record and keeps going until the queue is empty or DETROIT_SHIFT_MAX_HOURS (default 6) have passed. Before each task it checks that gh is signed in and that the model endpoint (DETROIT_MODEL_ENDPOINT, default http://127.0.0.1:8090/v1) answers and serves the model, and stops cleanly if not. The service pins opencode to the installed version so it can't upgrade mid-shift. DETROIT_MODEL picks the opencode model as provider/model (default studio/mlx-community/Qwen3-Coder-Next-4bit). Output goes to logs/nightly.log, which nothing rotates. Details: docs/scheduling.md.

Nightly batch — run 5 tasks in parallel at 2am:

0 2 * * * /path/to/detroit/factory.sh --parallel 5 >> /path/to/detroit/detroit.log 2>&1

Label a GitHub issue detroit, go to bed, wake up to a PR with screenshots. That's the workflow.

Factory Features

Based on patterns from Ramp Inspect and Stripe Minions:

1. Task queue — tasks/ folder, one markdown file per task
2. Task routing — finds repo locally, clones from GitHub, or creates new
3. Branch isolation — agents work on feature branches, never the default branch
4. Autonomous coding — agent runs non-interactively (Grok by default, Claude, dotbot, or opencode)
5. Test verification — run tests, fail fast if broken
6. PR creation — open a PR via gh CLI for every task
7. CI gate — auto-generates GitHub Actions workflow, watches CI, fixes failures
8. Task completion — move task file to tasks/done/
9. Visual verification — targeted screenshots of changes via agent-browser
10. Streaming output — real-time agent session output via streaming JSON
11. Parallel execution — run multiple tasks concurrently with --parallel N
12. Budget shift — --shift keeps one worker busy until the usage window is nearly spent
13. Logging — timestamped logs per run for debugging
14. Scheduling — cron or trigger to run without you

Configuration

A single file controls the factory: factory.md at the repo root. A Dockerfile for code factories — all the standards an autonomous agent needs to ship code in a repo, in one file you can clone and run anywhere. See the factory.md spec for the full format.

factory.md has 8 reserved sections. Each section is a bullet list of rules.

#	Section	Covers
1	## style	Formatting, naming, function size, imports, changelog hygiene
2	## build	Runtime, package manager, CI workflow, version bumping
3	## testing	Test framework, pass/fail gates, new-code test requirements
4	## documentation	Doc comments, README, AGENTS.md updates
5	## environment	Dev tools, branching rules, worktrees
6	## quality	File size, function size, TODO/FIXME, complexity
7	## observability	Logging, error reporting, tracing
8	## security	Hardcoded credentials, dangerous patterns, dependencies

Every bullet is one rule. The framework reads each bullet and either:

• Runs it as a gate if it recognizes the rule (e.g. "no secrets in diff", "tests pass")
• Forwards it to the agent as an additional rule to honor if it doesn't recognize it

Prefix a bullet with ! to mark it strict — the framework must verify it deterministically or the pipeline fails. Use strict for security, correctness, and release-critical rules you refuse to trust a model on:

## security
- ! No hardcoded credentials
- ! No eval
- Dependency audit clean

Edit any section to match your preferences. factory.md is framework-agnostic — the same file can drive any autonomous agent pipeline, not just Detroit.

Pipeline

Detroit's pipeline is an implementation detail of factory.sh:

1. Pick the next task from tasks/
2. Route it to a repo (local, GitHub, or new)
3. Prepare a feature branch (worktree)
4. Scaffold a CI workflow if missing
5. Run the agent with every factory.md rule injected into the prompt
6. Dispatch every rule bullet through check_gate; recognized gates run as checks, unrecognized gates are forwarded
7. Fix gate failures by re-engaging the agent (max 2 attempts)
8. Confirm the PR, watch CI, fix failures (max 2 attempts)
9. Screenshot affected pages via agent-browser
10. Move the task file to tasks/done/, close the issue, return to the default branch

Requirements

• The Grok CLI (default; signed in with a SuperGrok subscription or XAI_API_KEY), Claude Code, dotbot, or opencode (any provider it is configured for, local models included)
• gh CLI (authenticated)
• agent-browser (optional, for screenshot verification)
• Rust (optional, only to build the web UI)

Why Detroit

Detroit does the same thing as GitHub Copilot Coding Agent and Claude for GitHub — task in, PR out, automated. The difference is it's a shell script you own.

What Detroit has that they don't

• Task queue with priority — file-based, numbered for order, not one-off prompts
• Configurable standards and workflow — edit factory.md (a portable, framework-agnostic spec) to control exactly what the agent does
• Screenshot verification — starts the dev server, reads the diff, screenshots the actual pages that changed
• Runs locally — no data leaves your machine except API calls
• Swappable agent — the xAI Grok CLI (default), Claude Code, dotbot (any provider: xAI, Anthropic, OpenAI, Ollama), or opencode on a local model
• GitHub issues integration — pull labeled issues into the queue, close them on completion
• No vendor lock-in — swap Claude for another model, change the pipeline, fork it

What they have that Detroit doesn't

• Hosted infrastructure (no local machine needed)
• Web UI
• No setup

Who is Detroit for

Developers who want to own their code factory. Same idea as self-hosting vs SaaS — you trade convenience for control.

Contributing

git clone https://github.com/stevederico/detroit
cd detroit

Edit factory.sh or factory.md. Open a PR.

License

MIT — see LICENSE.