Skip to main content
Glama

Avoozl

Avoozl turns a goal into a reviewed task graph and delivers it through Kiro Crew sessions. It runs as a Kiro Crew app: a page, a loopback backend, an MCP server, and a one-minute tick. Its work is described in Kiro spec folders, called specs on the page. Execution state lives in a local SQLite workspace. GitHub is optional.

Avoozl is for epics: approved goals that need many changes in a set order. Maintenance, triage and one-off pull request handling belong to Issue Radar crews or to your team's coder. Avoozl can hand each task of an epic to any coder. If the work fits in one pull request, it is not an Avoozl job. If it needs a plan with an order, it is.

Install

You need Kiro Crew 0.12.2.3 or later, as installed (no custom build), Node 22.13 or later (for built-in SQLite; Node 26 is tested), and Git. The GitHub features also need gh signed in, or a token. Avoozl was tested on Kiro Crew 0.12.2.3; earlier versions were not tried.

git clone https://github.com/mtdowling/avoozl.git
cd avoozl
npm ci
npm run build:kirocrew-app
kirocrew app install "$PWD/kirocrew-app"

The build writes the page bundle and copies the CLI into kirocrew-app/bin/lib, so the installed app does not depend on this checkout. Then open Kiro Crew's App Store, review Avoozl's trust request, and enable it. The trust request asks for these API grants:

Grant

Used for

/apps/avoozl/api/*

The app's own backend

/api/chat/slots/avoozl_*

Status of the sessions the tick opened, and no others

/api/usage/turns

Token and credit counts per flow stage, for those sessions

/api/models

The model lists in Settings

/api/apps/spec-builder/specs

Handing a new spec to Spec Builder

/api/reveal

Showing a spec file in the file browser

An update that adds a grant waits until you approve it. The Avoozl page appears in the sidebar.

To update, pull, rebuild, and run kirocrew app update avoozl. A second kirocrew app install is refused once the app is installed.

Related MCP server: workspace-mcp

Create a workspace

On the Avoozl page, under Add or initialize a workspace, enter an ID and an absolute directory, then choose Initialize new. Choose Add existing for a directory that already holds a workspace. The CLI does the same:

node cli.mjs init ~/plans --name "My plans"

A workspace is a directory you own, separate from this checkout:

my-plans/
  .avoozl.json                     portable, reviewable policy
  .avoozl/local/workspace.sqlite   execution state (not committed)
  .kiro/specs/<name>/              plans

A new workspace has no tasks, no repositories, and no trigger rules. To add a fictional example, run node cli.mjs seed --workspace ~/plans --example product-launch. Loading examples never approves a plan, starts a session, or configures a repository.

Demo mode

To show Avoozl to someone without touching your work, choose Start demo in the empty In flight box on the Dashboard. It shows only while nothing is in flight and the workspace has never run a task. It is also on the empty page when you have no workspace yet. It opens a made-up workspace, Recipe Box, to look around in. Exit demo returns to your own workspace.

While the demo is on, a Demo badge shows in the header. Reads work. Every change only says what it would do, no agent or chat starts, and GitHub is a fake that writes nothing. Exit demo returns to your own workspace, which the demo never opens. The sample is built once in a folder under your system temp folder and kept, with any edits, for the next demo. Screenshots are in docs/evidence/demo/.

Where tasks live

Settings > Where tasks live picks one of three modes (github.mode in .avoozl.json):

Mode

github.mode

Tasks live in

Pull requests

Who closes issues

Local only

local

The workspace database

None; local merge

No issues

Plans repository

plans-repo

Issues in a planning repository

Code repositories

Avoozl

Single repository

single-repo

Issues in the code repository

The same repo

Closes #N

Local only is the default. Switching to Local only keeps your GitHub settings in the file, unused, so switching back restores them. In plans-repo mode a leak screen keeps the planning repository's name out of branches, pull requests, and comments in the code repositories.

Specs

Every spec is a Kiro spec folder. Inside Avoozl and in its interfaces (plan.* operations, plans_* MCP tools, CLI commands) a spec is stored as a plan, so those names stay.

.kiro/specs/<name>/
  requirements.md (or bugfix.md)
  design.md
  tasks.md
  avoozl/manifest.json

Each checkbox in tasks.md has a task ID, and avoozl/manifest.json gives each ID its kind, summary, acceptance, dependencies (requires), checks, and completion level. Avoozl refuses a folder that is missing a file, or a tasks.md with a missing or repeated ID.

On the Specs page, choose New spec (or Plan a goal in the header). Fill in the name, the repositories in scope and what you want, then choose Open in Spec Builder. Avoozl offers to add .kiro/steering/avoozl-specs.md to the repository first, showing its text; it holds Avoozl's spec rules, and it is never written over a changed copy. Kiro Crew's Spec Builder then drafts requirements, design and tasks, one phase at a time for you to review. Once tasks.md holds still, Avoozl writes avoozl/manifest.json from it and stores the folder as a draft spec. Nothing is approved or started. Spec Builder must be turned on in Kiro Crew's Apps; when it is off, the drawer says so and offers an avoozl-planner chat instead. Select the spec, review the lint results and the graph, then choose Approve revision. Approval records the exact revision hash, so a later edit reads as unapproved until you approve again.

For dependencies across specs, load each referenced spec as a stored draft first. Preview distinguishes a declared task from an existing approved task. You approve each spec separately; approval creates only that spec's tasks. A dependency on a draft owner stays pending and blocks delivery and GitHub projection until the owning spec is actually approved. An unrelated newer draft does not erase its last real approval. Retiring an owner restores the hold; if a dependent is already projected, revise its links before invalidating the owner so an old ready label cannot authorize work.

Deliver locally

Register the Git checkout the work changes, with its base branch, a worktree directory, and the check commands:

node cli.mjs project configure code --workspace ~/plans \
  --json '{"root":"/path/to/code","baseBranch":"main","worktreeRoot":"/path/to/worktrees","checks":[["npm","test"]]}'

Checkout paths are per machine, so they are kept out of .avoozl.json. Then turn on Autopilot, Avoozl's name for delivery, with the delivery block in .avoozl.json:

{ "delivery": { "concurrency": 1 } }

Two Kiro Crew steps only you can do, once:

  1. Let Kiro Crew tell Avoozl which chat is calling, so a worker can report. Kiro Crew passes this only to MCP servers it shares. Open MCP Management, find avoozl:avoozl, turn on sharing, and press Approve sharing. Then restart the gateway (Settings › About › Restart gateway). Without this, a worker can do the work but plans_report refuses it. A shared server runs outside the chat sandbox, with your access.

  2. After the first tick, open the chat folder Avoozl › repository ID in the sidebar and set its project directory to the checkout. Only a person can set it, and the tick opens no session there until it is set.

Each minute the tick starts a Kiro Crew session for each ready leaf, in its own worktree. When a session reports done, Avoozl runs the checks itself on the exact commit in a clean worktree, with no model call, then rebases, fast-forwards the base branch, and releases the leaf's dependents. A verifier session opens only when a task's bar needs judgment: prose acceptance with no checks, or verify: "agent". Avoozl never pushes. Implementation, integration, and acceptance stay separate steps, each with its own record.

To let a Crew Mode conductor claim leaves instead, set "delivery": {"runner": "crew-mode"} and follow the app package notes.

Avoozl never replaces a worker only because its activity went quiet. It checks durable session and delivery records first.

Deliver through GitHub

Pick a GitHub mode under Settings > Where tasks live, then use Set up GitHub there, or Settings > Repositories > Onboard for a new folder. Both read GitHub first and preview every write (labels, Project fields, issue types); nothing is written until you confirm. Approved specs become issues, sub-issues, and blocked-by links, with a Project board as the view. Public and private repositories both work.

For a mirror, private specs live on its orphan plans branch. Approval pull requests target that branch and the issue marker carries ref=<branch>. avoozl verify-issue checks that the approved commit is reachable from the ref and that the ref shares no history with the default code branch. A ref, like the rest of the marker, is not a signature. On success, --json also returns source.repository, source.fetch and one source.show command per spec file. The fetch command names the spec repository explicitly, even when the crew works in a separate code repository.

Avoozl ships with no trigger rule, so no label starts any work until you add one. Each rule names an action, a match line in GitHub's issue-search syntax (for example label:agent:go -label:hold), and is checked against Who counts: who may give orders with a label, a board drag, or a close. With nobody named, that is anyone with write permission. See trigger rules and example policies.

Other delivery routes, task trackers, intake sources, content rules, and settings packs plug in as separate packages that you approve on each machine. See writing a plugin.

One driver per spec

Only one Avoozl drives each approved spec: it alone starts work, writes GitHub, and merges for it. Every other workspace reads only for that spec and says why.

  • In a GitHub mode, the spec's plan issue names the driver. Its one assignee says which person, and a machine claim in Avoozl's marker says which of that person's machines. With no assignee, the epic issue's assignee counts. With none or several, every workspace reads only and one decision opens.

  • Hand off driver on the spec's page stops new work, lets running chats finish, writes an export file to a folder you pick, and links the plan issue for you to reassign. Avoozl never reassigns it. The file may hold private notes; Avoozl never uploads, commits, or pushes it.

  • Take over on the other machine takes the export, or rebuilds from GitHub when the old machine is gone, and lists what a rebuild loses first. Force take over assigns the plan issue to you, and asks you to type the spec name first. An old driver that comes back reads only.

  • Nothing moves the role because a machine went quiet. A task that was running on the old driver is "away": it completes from GitHub when its pull request merges, or waits for you to start it here.

  • Plugin approvals, terms files, the routing prompt, retro instructions, crews and SSH host keys stay on each machine. After a take-over the page lists what to set up again.

Limits: assignment is not atomic, so work the old driver started after its last check, at most one tick's worth, can overlap; it shows as away on the new driver. In Local only mode the lock is a row in the workspace database: it guards only instances that open that file or a copy, cannot see another machine, and has no forced take-over. CLI: avoozl driver status, avoozl driver handoff, avoozl driver takeover --file PATH or --rebuild, and --force --confirm SPEC.

Flow

Settings > Flow holds these, in .avoozl.json under flow (a repository can override them). The Flow view shows where the time went.

  • Timing is always on. It records each task's time per stage, and token and credit counts per stage. It keeps no prompts or text.

  • Stop the line (stopTheLine.scope, default dependents; or repo, all): when a check that passed on the base branch fails on a later commit and again on one rerun, new dispatch in scope waits and a fix task goes first. Running sessions keep going. It resumes when the check passes, or when a person presses Run anyway.

  • Local checks first (localChecksFirst, default true): a session that pushes runs the declared checks in its worktree before each push.

  • Batching (batch.max, default 3; batch.by, epic or files): ready leaves the plan marks size: "small" that share an epic (or files) run in one session and one worktree, one commit per task. A failing batch splits. 1 turns it off.

  • Retro (retro.everyTasks, default 10; retro.slowFactor, default 3): a tool-less avoozl-retro session names the biggest slowdown and proposes up to three changes. You approve or reject each, and an approved change is measured afterward.

Settings > Models picks the model of each of Avoozl's own chats: the planner, the driver, the retro and review drafts. It is saved as models in .avoozl.json, for example {"models": {"retro": "<model>"}}; a role left out, or auto, runs on its agent's own model. Issue Radar crews pick their own model, and Avoozl moves no running chat to another one.

The red Stop the line pause icon, in the page header's … menu on every tab, is the Andon cord: a person, or an agent through MCP, stops new work for everything, one repository, one spec, or one task, with a one-line reason. Running sessions keep going. Only a person presses Resume.

Routing

Settings > Routing decides which crew and model run each worker. It is off by default: every session runs on this machine with the agent and model from Settings > Delivery, as before.

  • Routing prompt (routing.prompt in this machine's settings, never in .avoozl.json): turn it on and write how to choose, or insert one of the examples (Tests go remote, Private repos stay local, Spread the load, Prefer Kiro models when Claude is low, 70% Claude, 30% Kiro) and edit it. Each tick, one tool-less avoozl-router session ranks every ready task at once and picks a crew and a model for each. An answer is used in one tick only, after the checks run again. A task with only one option left takes it with no routing call, and Activity says "only one choice".

  • Checks come first. A crew must be online, approve tools on its own (so a chat cannot stall on an approval), reach the repository, and have the tags a task needs (such as os:windows). A model whose provider is out is never offered. The agent only picks among what passed; task text in its brief is marked as untrusted data.

  • No fallback. With routing on, a failed router (an error, no reply in 90 seconds, a bad reply, a pick outside the options, a content rule on its brief, or its model out) never runs a task on this machine. The task stays Ready, marked "routing failed" with the reason, and is asked again after 1, 2, 4, 8, then every 15 minutes. After 3 failures in a row, Needs you offers Retry now and Turn routing off. The Routing page shows the last success, the last error, and the failures in a row; each failure and recovery is an Activity row. Only routing off runs tasks here.

  • Pins win. A manifest task's session may pin agent, model, or crew.

  • Providers shows each provider's health and usage in the last 5 hours, with one Low at setting (80% by default) and an optional credits limit per provider. Low is a fact the prompt can weigh, for new tasks only. A running chat switches model on its own only when its provider is out.

  • Preview is a dry run on the ready tasks: each one's options, what ruled the rest out, and the brief one routing call would get. It calls no agent.

  • Pick again makes a task's next attempt choose its model afresh.

  • Hand-back: a remote crew's work comes back either by push to the repository remote or by handback, where this machine fetches the branch from the crew's folder over SSH, pinning the host key on first use. Avoozl never pushes either way.

Old routing.rules, routing.pick and routing.router keys are refused; node scripts/migrate-routing.mjs <file> turns them into prompt lines once.

Remote crews are not live yet. Until Kiro Crew can open a session on another instance (Kiro Crew issue #36335), remote crews fail the checks and every session runs on this machine. Hand-back over SSH is tested only with a fake ssh command.

Remote relay (stopgap)

routing.remoteRelay: "on" in the workspace's .avoozl.json (off by default) places remote worker picks before Kiro Crew can. Press Open relay chat on the Routing page. That opens one chat on the avoozl-relay agent. The tick queues each remote pick for that chat instead of running it here. Each time you send the chat a message, it opens the queued workers on their crews, sends their briefs unchanged, and hands their replies back. Avoozl reads only the report line at the end of a reply. The relay has four tools and cannot approve, merge, or push.

Two catches, also shown on the Routing page:

  • Kiro Crew lets a chat open a remote chat only during a turn you sent. A remote task waits, listed in Needs you, until you send any message to the relay chat. It never falls back to this machine.

  • Each relay turn costs one model turn. The Routing page shows the count per day.

Only worker sessions go through the relay; checks and review run here. Once Kiro Crew can open remote sessions itself, Avoozl uses that and ignores the setting. The relay is built and tested with a fake relay chat and fake crews only (P47). It has not been run against a real remote crew.

The Avoozl worker is frozen

The worker coder gets upkeep only: security fixes, bug fixes, and keeping the tests green on all three systems. It gets no new features. Pick issue-radar for new work. A repository that changes coder keeps each handed-over task with its old coder until that task's issue closes. New tasks use the new coder, and the next projection shows the split once.

Pull request feedback

For each leaf an Avoozl worker codes on a linked branch, the tick reads its open pull request and sends what is new to the worker that wrote it: failed checks, changes requested, comments by people Who counts allows, merge conflicts, and auto-merge turned off. One message per pull request per tick. Avoozl writes nothing to GitHub here. It is on by default, for at most 5 rounds per leaf; set delivery.prFeedback and delivery.feedbackRounds, or use Settings > Delivery. Issue Radar's leaves are skipped.

When a pull request's base branch moves and the pull request then conflicts with it, or falls behind a base that requires branches to be up to date, the writer gets one message to merge the base branch in with a merge commit. Avoozl never asks for a force push, and drops any brief or message that does.

Issue Radar crews do not resolve conflicts inside source code; they hand the pull request back. With conflicts.onSourceConflict: fix (the default) Avoozl then starts one resolver chat. It merges the base branch into the same pull request branch, keeps both sides, runs the checks, and must pass a drop check (every line the base added in a file both sides changed is still there, or is explained) before it pushes one merge commit. Avoozl then arms auto-merge again, clears the conflict and needs-human labels, and posts one comment listing the files. When the chat cannot keep both sides, it pushes nothing and the pull request waits in Needs you with Resolve myself and Dismiss. It makes conflicts.maxAttempts tries per conflict (default 1), never touches a branch a person committed to after the crew, and pauses while the line is stopped. ask only opens the Needs you row. merge.method (squash, the default, or merge) sets how Avoozl arms auto-merge on crew pull requests; Set up refuses a method the repository does not allow. Built and tested with fakes only; no live run has used it yet.

Investigate first, evidence, and who merges

These are built and tested with fakes only; no live run has used them yet.

  • Investigate first (delivery.investigate): before it changes a file, a worker reports what it read, the cause it believes, the change it plans, how it will check it, and how sure it is. A second, read-only chat tries to prove that wrong. Coding starts only when both are sure enough (minConfidence, default high) and the findings stand; otherwise the task waits in Needs you with Go ahead, Investigate again and Stop. mode is not-small (default), all or off; a manifest task may set investigate: true or false.

  • Evidence: each task keeps one bundle under .avoozl/local/evidence/ with its findings, decisions, review verdicts, check results and the images or videos (at most 20 MB) the worker attaches. The task drawer shows it, and one comment on the pull request holds its text summary.

  • Who merges (delivery.ship): auto-merge (default) has the writer turn on GitHub auto-merge. manual keeps it off and shows Ready to merge in Needs you when checks and reviews pass; you merge on GitHub, or press Integrate for a local task. A repository, spec manifest (ship) or task may set its own. Avoozl never merges a pull request itself.

  • Rules from corrections: changes requested, work sent back with a reason, a revert of an agent's commit, and Pick again with a reason are recorded. When the retro sees the same correction on two tasks it may propose a rule; once you approve it, it lands as one task that edits .kiro/steering/avoozl-rules.md in that repository and makes AGENTS.md point to it, so every chat and Issue Radar crew reads the rules. Avoozl keeps no lessons store of its own. Lessons an older version stored on this computer are appended once to the workspace's .kiro/steering/avoozl-rules.md under a dated heading, and then deleted.

  • Flow shows the share of finished tasks that were bug fixes, and corrections per week.

Agents and the CLI

Agent sessions in Kiro Crew reach Avoozl through the app's avoozl MCP server. Any other stdio MCP client can run it directly:

{
  "mcpServers": {
    "avoozl": {
      "command": "node",
      "args": [
        "/path/to/avoozl/cli.mjs",
        "mcp",
        "--workspace",
        "/path/to/my-plans"
      ]
    }
  }
}

The page, the CLI, and MCP call the same operations, so each one sees the same state. node cli.mjs help lists the commands.

MCP tools

MCP has one tool per thing, each with an action field that names one operation: plans_workspace (read only), plans_maintain, plans_view, plans_plan, plans_review, plans_task, plans_session, plans_conflicts, plans_intake, plans_document, plans_github, plans_repos (read only), plans_plugins (read only), plans_content, and plans_run. Each tool's description lists its actions. A call looks like {"action": "get", "input": {"id": "TASK_ID"}}.

Some actions belong to a person and are refused over MCP under any tool name, old or new: approving or starting a spec, deletes, plugin changes, Allow once and content-rule terms, choosing a conflict winner, GitHub setup writes and settings (including Who counts), adding or removing repositories or intake sources, workspace, flow, delivery, and routing settings, Pick again, Run anyway, resuming a pulled stop, starting or deciding a retro, Deliver this and Plan this on an incoming item, sending issues to Issue Radar, and opening a code review chat. Do these in the Avoozl app. An agent may pull the Andon cord (plans_session, action stop_line), but not resume it.

The older one-tool-per-operation plans_* names stay listed and keep working. Each description starts with Deprecated: and names its replacement. They stay listed because a Kiro Crew session can call only the tools its client was shown.

node cli.mjs query --workspace ~/plans --q 'ready:true'
node cli.mjs show TASK_ID --workspace ~/plans
node cli.mjs tick --workspace ~/plans

Choose a workspace with --workspace PATH or AVOOZL_WORKSPACE.

What is tested

Receipts are in docs/evidence/. "Fakes" means automated tests with a fake GitHub, fake sessions, or fake crews, run by npm test.

Feature

Tested

Local delivery with real Kiro Crew sessions

Live (P4, P5, P6)

Single-repo mode end to end

Live, in a test repository (P19, P20)

Cross-repository edges and rebuild from GitHub

Live, in test repositories (P9)

Plans-repo mode and its leak screen

Fakes, plus read-only live queries

Intake list

Fakes, plus a read-only live count (P31)

Plugins, packs, plugin and MCP intake sources

Fakes only (P26, P32, P35)

Flow: timing, stop the line, batching, retros

Fakes only (P30)

Andon cord

Fakes only

Routing prompt, checks, and pins

Fakes only (P29); remote crews wait on Kiro Crew

Remote relay

Fakes only (P47); not run on a real remote crew

Provider health

Fakes only (P44)

One driver per spec, hand off and take over

Fakes only (P40)

Pull request feedback

Fakes only (P34)

Spec Builder hand-off

Fakes only

Stacked pull requests, comment steering, Discussions

Fakes only

Demo mode

Fakes only, plus headless Chrome on the harness page

Configuration and secrets

.avoozl.json holds portable policy: repositories, GitHub mode and rules, delivery limits, and agent instructions. It is meant to be committed. Paths in it are relative to the file. The loader rejects absolute paths and fields that look like secrets. Keep GitHub credentials in gh or your credential store.

The app backend binds 127.0.0.1 and accepts only requests that the Kiro Crew gateway signed. Do not expose it.

Back up

node cli.mjs backup --workspace ~/plans --output ~/plans-backup.sqlite

Back up the spec folders and .avoozl.json with it. Use the backup command rather than copying the database file: SQLite also keeps a WAL file.

Compatibility

Avoozl was first released as AICommander. These names keep working:

  • MCP tool names that start with plans_.

  • AVOOZL_* variables, and the older AICOMMANDER_* and NUPP_WORKSPACE_* names, including NUPP_WORKSPACE for the workspace.

  • The aicommander command, the same CLI as avoozl.

  • Older fenced-task plan files, which stay readable so their work can move to spec folders.

Develop

Application operations and SQLite storage live in src/app/, shared models in src/, and the Kiro Crew page in kirocrew-app/ui/. Run npm test before sharing a change. Tests use disposable workspaces and make no network or paid agent calls. node scripts/release-scan.mjs checks what the npm and app packages would contain.

License

MIT. Bundled third-party code and its licenses are listed in THIRD_PARTY_NOTICES.md.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      Enables MCP clients to safely read, write, edit, search, and optionally run commands within one or more named project workspaces, while maintaining a work journal and tracking changes.
      19
      MIT
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables external agents to inspect and interact with a local single-project workbench via MCP, providing read-only tools for state, audit, resume, readiness, comparison, impact preview, and repair candidates, while proposals are saved for manual confirmation in the workbench.
      MIT
    • A
      license
      A
      quality
      C
      maintenance
      Lets MCP clients read a delivery route planning and driver dispatch team's plans, stops, routes, drivers, depots, and optimization operations, and when writes are enabled, create plans, import stops, optimize routes, and distribute them.
      12
      MIT