How to set up, build, run, and test Agent Orchestrator locally.
| Tool | Minimum version | Notes |
|---|---|---|
| Go | 1.27.4 | go version to check; install via go.dev |
| Node.js | 24 | node --version; install via nodejs.org |
| npm | 10 | Ships with Node.js |
| Nix (opt.) | - | nix develop drops you into a shell with all deps; see ../flake.nix |
Additional runtime dependencies for the daemon:
- git (for worktree creation and agent integration)
- A running agent CLI (Claude Code, Codex, Aider, etc.). See the installation guide.
For source terminal runs on macOS, install/configure tmux; packaged builds
bundle it. New macOS/Linux sessions use detached native PTY hosts, while old
handles and host-start fallback use tmux. ao doctor still checks tmux on both.
agent-orchestrator/
backend/ # Go daemon (Cobra CLI, HTTP API, services, storage)
cmd/ao/ # CLI entry point
internal/ # All library code
cli/ # CLI command implementations
httpd/ # HTTP controllers, apispec, middleware
service/ # Business logic layer
domain/ # Domain types
ports/ # Port interfaces (contracts)
storage/ # SQLite migrations, queries, generated code
frontend/ # Electron + React desktop app
src/ # Renderer, main, preload
e2e/ # Playwright end-to-end tests
packages/
mobile/ # React Native (Expo) mobile companion app
ao/ # Legacy npm CLI package (frozen)
docs/ # Architecture, ADRs, CLI docs, status
CONTRIBUTING.md # Contribution guide
git clone https://github.com/Untrivial-ai/agent-orchestrator.git
cd agent-orchestrator
npm cigit checkout -b ao/my-feature-branch origin/mainKeep your branch up to date by rebasing on main:
git fetch origin
git rebase origin/mainKeep commits atomic. Use one logical change per commit. Stage related changes and commit with a conventional message:
git add <files>Commit message tags:
| Tag | When to use |
|---|---|
feat |
New feature |
fix |
Bug fix |
docs |
Documentation only |
test |
Adding or fixing tests |
refactor |
Code change with no functional change |
chore |
Maintenance, tooling, dependencies |
Use trailers to provide additional context:
git commit -m "fix: handle nil pointer in session lookup
The session resolver panicked when the store returned a nil session
without an error. Return ErrNotFound instead.
Signed-off-by: Your Name <your.email@example.com>
Co-authored-by: Contributor Name <contributor@example.com>"cd backend
go build ./...cd backend
# Start the daemon (loopback HTTP server on 127.0.0.1)
go run ./cmd/ao daemonThe CLI is built with Cobra. From backend/, run go run ./cmd/ao --help for
available commands.
cd backend
go test ./... # all tests
go test -race ./... # with race detection
go test -v ./internal/cli/ # a specific packagenpm run lintCreate new SQLite migrations from the repository root:
npm run migration:create -- add_reportsThe command creates a Goose SQL template with a UTC YYYYMMDDHHMMSSsss ID.
Fill in its SQL and append the generated ID and filename to shippedMigrations
in backend/internal/storage/sqlite/migrate_burned_versions_test.go.
Keep existing migration IDs, filenames, and SQL unchanged.
# Regenerate sqlc code after editing queries or schema
npm run sqlc
# Regenerate OpenAPI spec and frontend TypeScript types
npm run apicd frontend
npm installcd frontend
npm run dev # Electron dev mode
npm run dev:web # Web-only (no Electron, for quick UI iteration)cd frontend
npm run package # Package for current platform
npm run make # Create distributables when platform packaging deps are installedOn a fresh Linux machine, treat npm run package as the default local build
path. npm run make also needs Linux packaging tools that are not provided by a
minimal setup or by nix develop today:
rpm/rpmbuildfor the RPM target- the usual distro packaging toolchain required by Electron Forge makers
CI installs rpm explicitly before running npm run make. Do the same locally
if you need Linux distributables, or skip npm run make on a fresh setup.
cd frontend
npm run test # Vitest unit tests in a simulated renderer environment
npm run test:e2e # Playwright browser-based renderer E2E tests
npx playwright show-report # View Playwright reportcd frontend
npm run typecheckOr from repo root:
npm run frontend:typecheckThe mobile companion app is still being wired into the contributor docs. Do not
assume packages/mobile/README.md is a complete setup guide on this branch.
Until a tracked guide lands, use the desktop/backend workflow above and check
open issues/PRs for current mobile-specific setup notes.
- Start the desktop app with
npm run devfromfrontend/. - The Electron main process starts and supervises the loopback daemon for you.
- Use
npm run dev:webonly for renderer-only development; it does not launch Electron.
For CLI-only usage, open two terminals:
Terminal 1: start the daemon.
cd backend
go run ./cmd/ao daemonTerminal 2: interact while the daemon is running.
cd backend
go run ./cmd/ao status
go run ./cmd/ao --help- Backend tests use
httptest.Serverand injected fakes. They do not require a real daemon. - Run the narrowest relevant test suite first (e.g.
go test ./internal/cli/), then the full suite.
- Unit tests use Vitest and run in a simulated renderer environment.
- E2E tests use Playwright against the web renderer started by
npm run dev:web; they do not launch the full Electron app. - After changing API types, run
npm run apifrom root to regeneratefrontend/src/api/schema.ts.
| Symptom | Likely cause | Fix |
|---|---|---|
go: go.mod requires go >= 1.27 |
Wrong Go version | go version; install Go 1.27.4+ from go.dev |
sqlc generate produces errors |
Query SQL syntax or schema migration issue | Check backend/internal/storage/sqlite/queries/ for SQL syntax, placeholder counts, and referenced columns/tables; if you changed the schema, add a new migration in backend/internal/storage/sqlite/migrations/ instead of editing an existing one, then rerun npm run sqlc |
openapi.yaml is stale |
Changed DTOs without regenerating | Run npm run api from repo root |
golangci-lint failures |
Linter version mismatch | Install v2.14.0 or use npm run lint from root |
| Tests fail with "connection refused" | Test tries real daemon | Tests should use httptest; check for go test ./... without a live daemon |
| Symptom | Likely cause | Fix |
|---|---|---|
npm run typecheck has type errors |
API types out of sync | Run npm run api from repo root to regenerate |
npm run dev fails on native modules |
Missing build tools | Install Python + C++ build tools for node-gyp |
npm install or npm ci fails |
Node.js version too old | node --version; must be 24+ (see prerequisites above) |
| Blank window or crash on Linux | Broken GPU driver stack | Start with AO_DISABLE_GPU=1 to skip hardware acceleration |
If CI fails on the storage drift step of codegen-drift, run the pinned generator from the repository root
and commit the generated storage changes together with their SQL/config source:
npm run sqlc
git diff --exit-code -- backend/internal/storage/sqlite/genThe diff check should pass after committing the regenerated files. Do not edit
gen/ by hand or use a different sqlc version; the version in package.json is
authoritative. Review any unexpected query or generated type changes before
committing. The storage tests also check that the config is valid YAML and keeps
the boolean override for app_settings.cloud_offering.
If CI fails on the schema.ts drift step of codegen-drift, the OpenAPI-generated files are out of sync with source. Regenerate them locally and commit the updated files:
npm run apiIf regeneration introduces unexpected diffs beyond your changes, check that your local tool versions match CI (Go 1.27.4+, Node 24, npm 10+).
The API is defined in Go controller DTOs and operation registrations. Edit these source files, then regenerate:
npm run apiThe generated artifacts are:
backend/internal/httpd/apispec/openapi.yamlfrontend/src/api/schema.ts
Both must be committed together with the Go changes. CI verifies they are in sync.