The problem · What it does · Results · How you use it · Production & roadmap · Technical details

AIWorks is a manager for AI coding agents that runs on your own computer. You agree on a plan once. AIWorks gives each step to an AI agent (Claude, Codex or Cursor), has a second, separate AI check the result, and delivers the finished work to GitHub as a pull request. It keeps going through crashes, restarts and usage limits, and asks you only when a real decision is needed.

AI agents write good code. Keeping them working is a job of its own.

• They stop. An agent finishes one step and waits for someone to type "continue".
• "Done" is not proof. You still have to find out what changed and whether it actually works.
• Limits waste hours. An agent hits its usage limit late at night, and nothing moves until you notice in the morning.
• Projects blur together. With several products going, you lose track of what is finished, what is stuck and what is waiting for you.

You end up as a full-time project manager for your AI helpers instead of working on your product.

flowchart LR
    goal([You describe the goal]) --> plan[You approve<br/>the plan once]
    plan --> build[An AI builder<br/>does the next step]
    build --> check{A fresh AI<br/>checks the result}
    check -- needs work --> build
    check -- passes --> pr[Pull request<br/>with both reports]
    pr --> merge([You merge it, or let<br/>AIWorks merge it once checked])
    pr -. next step .-> build

On 12–13 October 2026, AIWorks spent a day building the next version of itself. The figures below are counted from this repository's pull request and code history.

The owner set the goal and approved the plan once. An AI assistant session wrote the step-by-step plans and merged the checked pull requests on his behalf. He stepped in only a handful of times, for example to update the running copy of AIWorks, and two progress notes posted during the night read "nothing needs you".

Builds and tests run locally for every managed project. AIWorks must not use GitHub Actions or paid GitHub features such as Codespaces, paid runners or billable package/LFS storage. AI usage is allowed through subscriptions or metered APIs, subject to the existing campaign budgets and authority. See the development policy and enforcement limits.

The AI tools report their own usage: a building run typically costs about $5 and a checking run $2–3. In an earlier measurement the average came to about $10 per delivered step, retries and checks included. On a subscription plan this is usage counted against your plan, not an extra bill. The dashboard shows the cost of every project and step, and never shows an unknown cost as zero.

• Your attention. A rough estimate: if keeping one change moving by hand takes 15 minutes of your time (prompting, re-checking, retrying after a limit, merging), the 63 changes above add up to about 16 hours of coordination that nobody had to do.
• Hours that used to be idle. Nights, weekends and usage-limit resets become working time.
• Mistakes caught before you see them. The checker sends weak work back with its findings. AIWorks also refuses a "passed" verdict when one of the checks actually failed.
• No more piecing the story together. One screen answers "what needs me?" across all your projects, in plain words.

Projects with a standing release grant can also continue from an independently verified merge through their own deployment and health checks. The supervisor observes interrupted deployments before acting again and uses the project's rollback command when required. Configure automatic project releases.

Day to day, you don't type commands. You work in the AIWorks dashboard on your computer and in GitHub. Setup is done once (see below).

The screenshots show made-up example projects.

Projects lists everything this computer works on. Projects that need you come first, then those with work running. Each row tells you in one sentence where things stand.

Needs you counts only what needs your own sign-in, credentials or payment, and, if you chose to accept results yourself, the checked versions waiting for you (AW-017). Decisions, stopped steps and results to review are listed with what AIWorks does about them; you can still answer a decision first, accept a result or request changes. Something new to build is planned with Plan different work and starts only when you approve the plan. Usage limits, pauses, routine merge waits and AIWorks's own problems never count here; AIWorks lists what it is handling, so nothing stalls out of sight.

Inside a project, four tabs answer four questions:

• Now: where are we?
• Work: what is running or waiting, and why? You see who is on each step (the builder or the checker), whether it is working normally or may be stuck, and what a waiting step is waiting for.
• Results: what has been delivered? Pull requests waiting for your review, merged work and reports to read.
• Cost: what did each step cost?

Open any step to see its latest result and its history. From the dashboard you can:

• Pause and Resume a piece of work;
• Check again after you have fixed whatever blocked it;
• Cancel work you no longer want;
• Send guidance to the builder or the checker. It reaches them on their next run, without interrupting the current one.

Start work takes a plain description ("what should be true when this is finished?"), a GitHub issue or a pull request, and asks the planning assistant for a plan. The plan appears in the dashboard under Messages. Nothing is posted to GitHub, and nothing in your project changes at this stage.

By default, an approved plan is saved as a private file on your computer and registered there; your AI assistant can do this step for you. Plan and do, which starts exactly the plan you approve from the dashboard, is built and off by default (below).

Everything ends up in GitHub, next to the rest of your project:

• Each piece of work has a tracking issue, and each step has its own issue. AIWorks posts progress notes and blockers there.
• Each code change is a pull request that contains the builder's report and the independent check.
• Reports and research are posted as comments on the step's issue.
• AIWorks merges only if you switch it on. By default you merge, or you hand merging of checked pull requests to an assistant you trust. You can instead let AIWorks merge them itself, one project at a time. It then merges a pull request only when the result on your main branch is exactly the version the checker approved. If main moved in the meantime, it brings the change up to date and has it checked again first. Deployment additionally requires the project's standing release grant.

"In production" means built, switched on by default, and used every day to build AIWorks itself.

• Approve an outcome once, and let AIWorks split it into steps and add steps as it learns.
• Phone notifications you can act on: Telegram alerts are built (above); answering from the phone needs remote access, which is not designed yet.
• Automatic model choice by cost and quality for every plan, once a measured comparison supports it.
• An AI-assisted setup guide for newcomers: a first version is in docs/guides.
• Instant reaction to GitHub events, instead of checking every minute.
• A public demo page, once the dashboard passes its own usability review. Its static source is in site/: a walk through the synthetic owner journey, not yet published anywhere.

• Early preview, one setup. AIWorks is built and used on one Windows PC with GitHub and Claude Code. On other operating systems it refuses to start workers, on purpose.
• A checker can miss things. A second AI makes it much less likely that a problem reaches you, not impossible. You remain the judge of what gets merged.
• Checks run on your PC. If your project's online tests run on another operating system, a change can pass here and fail there. This happened during the run above and is being addressed.
• The dashboard is new. It has just had its first usability review, and some screens still have rough edges.

Everything below is for setting up, running and changing AIWorks.

• Windows 10 or 11. Workers run inside Windows process containment; other platforms fail closed.
• Node.js 22.5 or newer, and Git (2.38 or newer for conflict repair).
• GitHub CLI (gh), signed in.
• At least one AI worker CLI, installed and signed in: Claude Code (main), Codex, or Cursor Agent.
• A local governance folder: run npm run setup:local for the bundled starter, then register the owner's approved projects under ignored .local/governance. It supplies the project registry contract and policies (registry/projects, policies/catalog.json and the project-contract schema). AIWorks only reads it, and new work must target a project registered there (Governance checkout).
• Optional, for website checks: AGY or Claude with headless Chrome 149 or newer.

Open Claude Code or Codex on the Windows PC, in a session that can run commands, and paste:

Set up AIWorks on this Windows computer from <https://github.com/netbka/aiworks>.
Follow docs/guides/ASSISTANT_SETUP.md, the "Technical details"
section of its README and docs/SUPERVISOR.md.
Check what is already installed, create the data folder and config.json,
register the two background tasks and open the dashboard.
Ask me only for sign-ins or approvals you cannot do yourself.
Do not change any of my project files.

The assistant runs the commands below. You handle any sign-in it cannot do for you.

The getting-started guides explain the same setup step by step, then your first task, a manual installation, every command and what to do when something stops.

The life of one step:

1. Prepare. The supervisor creates an isolated worktree and a task packet: the goal, the acceptance criteria, the files the step may change and the target project's rules. It records the run before launching it.
2. Build. The worker runs inside a Windows Job Object, with heartbeats and a time limit. For a code change, its result counts only if it is valid JSON naming a clean new commit.
3. Check. A different fresh session checks that exact commit, read-only, and runs the project's tests again.
4. Repair. A rejection sends the findings into the next packet. Repair rounds are limited only if the plan sets a limit.
5. Publish. The supervisor pushes exactly the checked commit and opens one pull request, or posts one report. It looks for an existing pull request or comment first, so a retry never creates a duplicate.
6. Wait and recover. A usage limit is recorded per AI account with its reset time (30 minutes if the reset is unknown). After a crash, the replacement supervisor adopts the running worker through its heartbeat instead of starting a second one.

Safety rules. These are accepted decisions, recorded in docs/DECISIONS.md:

• External writes follow the authority the owner registered. Merging is off by default. The supervisor merges a pull request only under the merge gate, and only in a repository the owner lists in config.json (merges.delegatedTo: "supervisor", decision AW-001, #138): the pull request is its own, its head is the checked commit, and what lands on the base branch is exactly the checked version. Project deployment requires an AW-010 grant and exact verification; the supervisor never deploys its own runtime or creates provider resources.
• AIWorks runs only from its own merged code; a supervisor running unmerged code starts no new work. Plans are private files on your computer, registered explicitly, and their scope can only change with a higher authorization version.
• The dashboard listens on 127.0.0.1 only and needs the same origin plus a per-session token for every action. Text that looks like a secret is refused. The one exception is the optional external campaign API (below), off by default: a static bearer token instead, for a local system that is not a browser.
• There are no budget caps by default. A plan can set run, retry, repair and cost limits.
• A denied command, a sandbox refusal or a failed check is never routed around to another provider.
• config.json holds executable and repository paths, never credentials.

Create .local/supervisor/config.json with absolute paths for your machine. The names and paths below are made-up examples:

{
  "governanceRoot": "C:/work/aiworks/.local/governance",
  "repositories": {
    "example-org/sampleapp": {
      "path": "C:/work/sampleapp",
      "worktreeRoot": "C:/work/aiworks/.local/worktrees/sampleapp"
    }
  },
  "commands": {
    "claude": ["C:/tools/claude.exe"],
    "codex": ["C:/tools/codex.exe"],
    "gh": ["C:/tools/gh.exe"]
  }
}

• governanceRoot: the read-only governance checkout. Without it, anything that needs it fails closed.
• repositories: each target repository, with its local checkout and a folder for worktrees.
• commands: each tool as an absolute path to a native executable, in an array. cursor, agy and chrome are optional (§8, §11).
• coordinator: optional. Without it, owner messages are stored but nobody reads them (§9).
• Optional, off by default: integrationRepair, ciRepair, scheduler and ownerIntervention. See docs/SUPERVISOR.md.

Write your plan as a private JSON file under .local/campaigns/, following the contract in src/supervisor/campaign.mjs. The files in tests/fixtures/campaigns/ are made-up examples to copy from. Plans are never committed.

npm install

node src/supervisor/cli.mjs start .local/campaigns/work.json --data .local/supervisor   # register a plan
node src/supervisor/cli.mjs keep --data .local/supervisor                               # run, and restart after any exit
node src/supervisor/cli.mjs status <campaignId> --data .local/supervisor
npm run dashboard -- --data .local/supervisor

AIWORKS_DATA can stand in for --data. The other commands (pause, cancel, recheck, stop, message, messages, coordinator-clear, baseline) are described in docs/SUPERVISOR.md §5.

powershell -NoProfile -File scripts\supervisor\install-windows-task.ps1   -Checkout <runtime checkout> -DataDir <data dir>
powershell -NoProfile -File scripts\supervisor\install-dashboard-task.ps1 -Checkout <runtime checkout> -DataDir <data dir>

These register the per-user tasks AIWorks Supervisor and AIWorks Dashboard. Both start at sign-in and every 5 minutes, and do nothing if they are already running. Add -DefinitionOnly to see the task definition without changing anything. cli.mjs stop keeps the supervisor stopped until its STOP file is removed. The live copy runs from a separate checkout of a reviewed commit and changes only through the upgrade procedure.

To update it, run npm run rebuild from a clean checkout at the trusted commit (add -- --root <installation root> when the installation is elsewhere). It pauses running work, lets open runs finish and be recorded, stops and backs up, installs the trusted commit with npm ci, restarts, and resumes only the work it paused. Run it again after a failure and it continues where it stopped (Rebuild).

npm install
node tests/dashboard/fixtures/review-store.mjs --port 4319

This opens the dashboard at http://127.0.0.1:4319 with three example projects covering every state. It refuses the live port 4318 and deletes its temporary data when you press Ctrl+C. The screenshots above come from it. The static showcase shows the owner journey instead, captured from its synthetic runtime; open it straight from the checkout.

After changing code, schemas, fixtures or documentation, run npm install once and then npm run check. It checks that no private installation files are in the commit, validates the example plans and runs the test suite. npm run test:affected runs only the test files your changes can reach and npm run test:quick the unit and service tiers only, for a fast pass while you work; the gate is the full check.

The reading list for contributors and AI agents.

1. Product Constitution: what AIWorks is, for whom, and how success is measured
2. Agent rules: what agents may and may not do here
3. Delivery Supervisor: the runbook — boundary, lifecycle, failures, commands, installation and upgrades
4. Operations Dashboard: what the owner sees and the local access boundary
5. Decisions: accepted product boundaries
6. Worker Context Lifecycle: task packets, leases and fresh sessions
7. Development status, the Project Workspace Plan and the designs: what the code does and where it is going
8. Publication preparation: what stays private and how public commits are checked
9. Glossary: terms and IDs

Bug reports, documentation fixes and focused pull requests are welcome: see Contributing and Security. AIWorks is released under the MIT License.