ait-native

Local Quickstart

Run one small Task from request to acceptance.

Try a dependency-free task-list example, then bring the same workflow to your own repository.

Try the exampleUse your own repository

Recommended cross-platform route

Install from PyPI

The wheel supports macOS, Linux, and Windows. Python installs the package; the ait workflow itself is native.

python -m pip install ait-native
Use Homebrew, npm, apt, or a release archive instead

Homebrew · macOS and Linux

brew tap weita2026/ait-native
brew install ait-native

Installs ait and an inactive ait-server.

npm · direct Node.js API

npm install --global @wa120/ait-native

Installs the JS/TS API, Node-API addon, and in-process ait command. No server.

apt · Debian and Ubuntu

# after adding the signed stable repository
sudo apt install ait-native

1.1.1 supports amd64 and arm64. Set up the repository.

Checksum-bound archives

Download the exact files for all supported platforms from the 1.1.1 GitHub Release.

AIT · 1.1.1

Your first Task, with a result you can check.

Install AIT above, then use a new folder for this example. You need Node.js 22 or newer and your own coding agent. Node.js is only a requirement of this example; the agent may use your model-provider account.

Download the example ZIPCheck the SHA-256

  1. 1. Extract and check the starting point

    Extract the ZIP with your file manager. Open a terminal in the extracted ait-first-task directory. These three baseline tests should pass. No npm install is needed.

    node --version
node --test tests/baseline.test.mjs

  2. 2. Initialize the example

    Run ait init here, then open this directory in your coding agent. Ask it to read the generated AGENTS.md before working.

    Replace your-name with the name you want recorded for local Task review. The initial Snapshot below records this unchanged example before any Task starts; use this preparation only in the fresh example directory.

    ait init
ait config set --user-name "your-name"
ait snapshot create --message "Start the AIT example"
    See exactly what initialization changes →

  3. 3. Give your agent this request

    Read AGENTS.md and follow this repository’s AIT workflow. Add openTasks(tasks) to src/tasks.mjs: return a new array of tasks whose done property is not true, in the original order, preserving the task objects and input data. Keep taskTitles working. Add focused tests. Do not edit checks/, remove existing tests, or add dependencies. Run the existing tests and node checks/first-task.mjs before finishing the Task.

  4. 4. Verify the result in the original folder

    After the agent reports Task finish, return to the original extracted directory and run both checks. The feature check is expected to fail before implementation.

    node --test tests/*.test.mjs
node checks/first-task.mjs

    The feature check prints FIRST_TASK_ACCEPTED when its cases pass. Also review the actual Task finish result: the Task is complete, its worktree is cleaned, and the bound sprint item is closed where applicable. Feature acceptance and workflow completion are separate checks.

If you get stuck

If node or ait is unavailable, complete the corresponding installation first. If the agent ignores AGENTS.md, start a fresh conversation in the initialized directory and ask it to read the file. If a check fails, give the failure to the same Task; preserve the check and repair the feature. A conflict remains unfinished until resolved and checked.

Next: try three compatible Tasks in parallel

Use a fresh extraction and initialize it. Open three separate agent sessions in that repository. Give each its own request and require it to follow AGENTS.md, bind a sprint item, work only in its returned edit_root, and preserve checks/ and existing tests. Use separate test files. Request A is the first request above.

Repeat the complete initialization step above, including the initial Snapshot, before opening the three sessions.

Request B: In src/labels.mjs, add taskCountLabel(count) for non-negative integers. Return "1 task" for 1, otherwise "N tasks". Preserve boardTitle. Add tests in a separate file, run the existing tests, and finish the Task.
Request C: In src/priority.mjs, add priorityRank(value). high, normal, and low return 0, 1, and 2; unknown or absent input returns 3. Preserve priorityOrder. Add tests in a separate file, run the existing tests, and finish the Task.

After all three Tasks finish, run these commands in the original directory. Expect PARALLEL_TASKS_ACCEPTED. This exercise covers compatible changes; it does not force a conflict or measure throughput. Keep a record of any real conflicts, failed checks, and intervention.

node --test tests/*.test.mjs
node checks/parallel-tasks.mjs

The repository trust boundary

See exactly what ait init changes.

Run it from the repository your coding agent will modify.

cd <your-repository>
ait init
  • Creates repository-local .ait/ state and docs/sprints/.
  • Creates or refreshes one clearly marked workflow block in AGENTS.md.
  • Preserves all AGENTS.md content outside that block; rerunning init does not duplicate it.
  • When CLAUDE.md is absent, creates a minimal pointer to AGENTS.md; an existing file is never overwritten.
  • Starts no server and sends no repository data anywhere.
If you later remove the repository integration

AIT 1.1.1 deliberately has no one-command repository uninstall. Preserve .ait/ first if its history matters, remove only the marked block from AGENTS.md, and remove a generated CLAUDE.md only when it still contains nothing except the AIT pointer. Sprint Markdown may be user-authored, so never delete docs/sprints/ blindly.

For an existing project, first follow the getting-started guide to import its existing state and configure a review identity. An already governed AIT repository should keep using its current AGENTS.md.

Choose a small, reviewable change in your own project once the example works.

Ask your coding agent the way you normally would

Add an accessible password-visibility control.
Leave the login API alone, and add the tests.

The generated repository instructions tell the agent to record the request, start an isolated Task, run the checks, and finish the verified result. You do not need to translate the request into AIT commands.

Check the local state

ait --version
ait status --json
{
  "ok": true,
  "line_name": "main",
  "workspace": { "status": "clean" },
  "next_action": null
}

Now give the agent one real task.

Review the finished change, then choose another small task in your own project.

Watch the complete workflow Review Release Status