ai-agentmanager 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 1.1.0 (2026-10-30)
+
+- **Teams:** give one problem to a team of agents in roles. An analyst writes the analysis and critics challenge it until they agree; an implementer builds it, a tester tests it, and a reviewer approves it or sends it back to the implementer. They hand off through files with a verdict line, which you can read in the team view. The team asks you only at the end (open a PR, keep the branch, or send it back) or when they can't agree within the round limits. **+ New agents → Team**, or `agentmgr team start`.
+- **One lead session by default:** a team is one agent whose Claude Code sub-agents play the roles, so your list shows one agent instead of five. **Separate agents** (one per role, any engine) is still available: the form's "How the team runs", or `--separate`.
+- **The lead decides:** it runs a whole request without asking you between steps, records its decisions in the handoff files, and stops only when the reviewer approves or it needs something only you can give. Sub-agents return their work as text and the lead saves it (Claude Code doesn't let sub-agents write report files).
+- **The lead stays:** after a request is done, ask the lead for more in its terminal (or **New request** in the team view, `agentmgr team ask`), and it runs the same team flow again as the next quest. Earlier quests stay in the team view.
+- **Gap rounds:** the reviewer also checks the work against the whole request and lists what isn't built yet. When good work still has gaps, the team shows them to you and asks: **Run a gap round** (`agentmgr team fix-gaps`) builds them in another round, from analysis to review. To let it run some rounds without asking: **Gap rounds without asking** in the form, `--gap-rounds`, `teams.gapRounds`. The form also sets the analysis and build round limits.
+- **Clean up old agents:** close agents with no activity for a while (14 days by default) and delete ones that stayed closed long after that (14 more days), with their worktrees. Pick the strategy in **Clean up** (top bar) or `agentmgr cleanup --strategy`: close then delete automatically, close automatically and delete when you say (the default), manual, or off. Agents marked **Keep**, working agents, members of a running team, and agents with an open pull request or work found only in their worktree are left alone.
+- **Only recent agents:** **Created in the last N days** above the agent list hides older agents (the open one stays). The list says how many it hides, with **Show all**. Remembered in this browser.
+- **Agent counts per project:** each project in the list shows how many agents it has ("2 of 5 agents" while some are hidden), and how many are running.
+- **Jira names:** an agent whose request starts with a Jira link is named after the issue (`OPS-7`), not the link.
+- **Teams on a new project:** with no repository or folder, a team starts a new project: a folder with a git repository and an empty first commit, so it still gets its own branch. At the end, merge the branch into the local `main`, publish to a new private GitHub repository with a pull request, or keep the branch.
+
+## 1.0.2 (2026-10-28)
+
+- **Resize and expand:** drag the edge of the agent list, or the line between the brief and the terminal; double-click a line to reset it. **Expand** (Ctrl+Shift+E) fills the window with the terminal, shell or browser tab, and **Full screen** fills the screen.
+- **Active agents first:** agents that did real work or got your input in the last day sort to the top, and projects with active agents come before idle ones. Idle agents are dimmed and show how long they've been idle. A restart that resumes an agent doesn't count as activity.
+- **`agentmgr doctor`:** checks Node.js, Claude Code and its sign-in, git, `gh`, the data folder, the daemon's port and Chrome, and says how to fix what's missing.
+- **Clearer first run:** when Claude Code (or another engine) isn't installed or isn't on the daemon's PATH, the agent says so and how to fix it, instead of `spawn claude ENOENT`. Running from a git checkout without `npm install` says to run it, instead of `Cannot find package`.
+- **AI judge:** no longer reads Claude Code's status bar ("accept edits on", "shift+tab to cycle", "update available") as a question, which raised false "waiting on you" items.
+- **Install as an app:** Chrome and Edge can install AI Agent Manager as an app (the install icon in the address bar), so it opens in its own window with a Dock or taskbar icon.
+
 ## 1.0.1 (2026-10-26)
 
 - **Name:** the product is now called **AI Agent Manager**, matching the `ai-agentmanager` package. The command is still `agentmgr`.

package/README.md

@@ -4,7 +4,7 @@ Run one background [Claude Code](https://claude.com/claude-code) agent per inten
 
 ![Agents grouped by project, with an agent's brief: results, problem, solution, a flow diagram and checks](docs/images/agents.jpg)
 
-![The conflict radar: two agents changed the same lines of README.md, with a suggested order to land them](docs/images/conflict-radar.jpg)
+![The conflict radar: two agents changed the same lines of README.md; the AI judge rates it a collision and suggests which lands first](docs/images/conflict-radar.jpg)
 
 - **Intents in, agents out.** Give one intent or a list (one per line). Each becomes its own `claude` process.
 - **Repo or folder.** Give a git URL (cloned once, then each agent gets its own worktree and branch) or a local folder.
@@ -41,6 +41,8 @@ Run one background [Claude Code](https://claude.com/claude-code) agent per inten
 - **Live browser.** Browser tabs run a real Chrome on this machine and stream it into the tab: you see its screen and your clicks, scrolling, typing and paste go back to it, from the laptop or the phone. Because the page runs here, `localhost` is this machine, sites that refuse to be framed load normally, and popups (a sign-in window) open as tabs of their own and come back when they close. Chrome (or Chromium, Brave, Edge; `browserBin` in config.json picks one) runs headless with its own profile in `~/.agentmanager/browser-profile`, so sign-ins are remembered; it starts on the first view and stops after 15 minutes with nobody watching. Downloads go to `~/Downloads/agentmanager`. A site that still refuses it as a bot may accept `"browserHeadless": false`, which runs Chrome with a real window on this machine's screen. On Linux where Chrome's sandbox can't start (containers, Ubuntu 23.10+ user-namespace restrictions) the tab says so; `"browserNoSandbox": true` runs it without the sandbox, at your own risk. **Lite** on the bar switches a tab to the frame mode (the page loads in your own browser; quicker for a dev server).
 - **CLI sign-in links.** When a terminal prints a sign-in link that returns to a port on this machine (`railway login`, `gh auth login --web`, `gcloud auth login`...), a bar above the terminal offers **Open sign-in**: the link opens in a live browser tab here, so the provider's redirect to `http://127.0.0.1:PORT/callback` reaches the waiting CLI by itself, from any device. It opens on its own if you just typed the command. Without a live browser, it opens a window on your device; from another device you then paste the address you land on (`127.0.0.1:PORT/callback…`) into the bar and AI Agent Manager delivers it to the CLI, only on the port the link named.
 - **Attach files and screenshots.** Drop files on the terminal, paste a screenshot, or use **📎 Attach**. The file is saved on the daemon's machine and its path is pasted into the terminal, which is how Claude Code picks up images and files.
+- **Your layout.** Drag the edge of the agent list, or the line between the brief and the terminal, to resize them; double-click a line to reset it. **Expand** (Ctrl+Shift+E) fills the window with the terminal, shell or browser tab; **Full screen** fills the screen. Agents active in the last day sort to the top; idle ones are dimmed.
+- **As an app.** In Chrome or Edge, click the install icon in the address bar (or ⋮ → Cast, save and share → Install page as app). AI Agent Manager then opens in its own window with its own Dock or taskbar icon, and the daemon keeps running as before.
 - **About.** The version next to the title opens the About box: release date, author, license, links, and how this daemon runs (data folder, port, Node.js, which `claude`). **Check for updates** asks npm for the newest version. In a terminal: `agentmgr about` (`--check` for updates).
 - **General sessions.** **Ask Claude** starts a session with no repo, folder or intent, for questions. It is tracked and resumable like any other agent.
 
@@ -51,8 +53,21 @@ New in 0.2, for running many agents at once:
 - **Stuck detection.** Spots an agent going in circles (the same failure again and again, undoing its own edits, a long stretch with no file changed) and offers a ready-made nudge to send.
 - **AI judge.** Rules only decide *when* to look; a fast model decides *what is going on*: whether a stuck-looking agent is really stuck (and a nudge specific to its problem), what an idle agent is asking when no known prompt matched, whether "done" work actually meets the intent, whether two agents' work will collide, what the backlog should start next, and which alerts are worth interrupting you for. It learns from how you react.
 - **Checkpoints and forks.** The code (uncommitted work included) and the conversation are saved at the end of every turn. **Fork** starts a new agent from now or from any checkpoint, in its own worktree, to try another direction without losing the first.
+- **Teams.** Give one problem to a team of agents in roles: an analyst writes the analysis, critics challenge it until they agree, then an implementer builds it, a tester tests it and a reviewer approves it or sends it back. You step in at the end, or when they can't agree.
 - **Races.** Send one intent to several agents with different models or approaches. Compare their outcome, checks, size of change, cost and a test command run in each worktree, read their diffs side by side, then pick a winner and delete the rest.
 
+## When to use it
+
+Claude Code on its own, including its built-in ways to run work in parallel, is enough for one repo in one sitting. AI Agent Manager is for when that stops being enough:
+
+- **Many sessions across several repos,** running for hours, where you lose track of which one is waiting on you.
+- **Agents that must survive** a closed terminal, a restart or a reboot, and pick up where they left off.
+- **Several agents in one repo,** each on its own worktree and branch, with a warning when two touch the same code.
+- **Keeping up without reading transcripts:** a brief per agent (result, problem, fix, checks) and one inbox for every prompt and question.
+- **From anywhere:** your phone, another computer, or several machines through the hub.
+
+**Trying it costs little.** It runs the same `claude` you already use, with your plan and your repo's `CLAUDE.md` and skills. Sessions you started with `claude` in a terminal can be continued in it (**Import** above the agent list), and you can go back to a plain terminal any time with `claude --resume`.
+
 ## Install
 
 Runs on macOS and Linux; on Windows, use WSL2. Requires Node 20+, `git`, and the `claude` CLI, signed in (run `claude` once). Optional: `gh` (authenticated) for PR discovery by branch and PR state, Chrome (or Chromium, Brave, Edge) for live browser tabs, and Codex (`npm i -g @openai/codex`) as a second engine.
@@ -61,13 +76,13 @@ Runs on macOS and Linux; on Windows, use WSL2. Requires Node 20+, `git`, and the
 
 ```sh
 npm install -g ai-agentmanager          # the latest release
-npm install -g ai-agentmanager@1.0.1    # or a specific one
+npm install -g ai-agentmanager@1.1.0    # or a specific one
 ```
 
 Or from the repository, at a release tag:
 
 ```sh
-git clone --branch v1.0.1 --depth 1 https://github.com/jdmunta/ai-agentmanager-core.git
+git clone --branch v1.1.0 --depth 1 https://github.com/jdmunta/ai-agentmanager-core.git
 cd ai-agentmanager-core
 npm install
 npm link            # optional: puts `agentmgr` on your PATH
@@ -87,9 +102,11 @@ npm link
 | Installed with | Update |
 | --- | --- |
 | npm | `npm install -g ai-agentmanager@latest` |
-| A clone at a release tag | `git fetch --tags && git checkout v1.0.1 && npm install` (the tag you want) |
+| A clone at a release tag | `git fetch --tags && git checkout v1.1.0 && npm install` (the tag you want) |
 | A clone of `main` | `git pull && npm install` |
 
+**Check your setup.** `agentmgr doctor` checks Node.js, Claude Code and its sign-in, git, `gh`, the data folder, the daemon's port and Chrome, and says how to fix anything missing.
+
 ## Quick start on a new computer
 
 **A computer that runs agents.** After installing:
@@ -126,6 +143,7 @@ The hub listens on port 4720, on this Mac and on its Tailscale address (`--host`
 ```sh
 agentmgr ui                                   # start the daemon and open http://127.0.0.1:4717
 agentmgr service install                      # start the daemon at login (launchd / systemd --user)
+agentmgr doctor                               # check Node.js, Claude Code, git, gh, the port; says how to fix
 
 agentmgr add "Fix the flaky login test" -d ~/src/app
 agentmgr add -r https://github.com/org/repo.git \
@@ -154,6 +172,8 @@ agentmgr answer <agent> <question-id> "…"     # answer a question from the inb
 agentmgr tell <agent> "…"                     # send a message into the session (when it's idle)
 agentmgr fork <agent> [-c 3] [-m "…"]         # new agent from now (or checkpoint 3), its own worktree
 agentmgr checkpoints <agent>                  # snapshots saved at the end of each turn
+agentmgr team start "problem" [-r <repo> | -d <folder>] [-c 2] [--separate] [-t "npm test"] [--role-model reviewer=opus]
+agentmgr team show [team] | ask <team> "…" | finalize <team> [--merge | --publish | --keep] | send-back <team> "…" | continue <team> ["note"] | skip <team> | stop <team>
 agentmgr race start "intent" -v opus -v "sonnet|keep it small" -r <repo> -t "npm test"
 agentmgr race show [race] | test <race> | pick <race> <agent> [--cleanup]
 agentmgr flush                                # save session IDs, scrollback, usage and state now
@@ -520,6 +540,35 @@ At the end of each turn, AI Agent Manager snapshots the agent's working tree as
 
 The source agent keeps running untouched.
 
+## Teams
+
+**+ New agents → Team** (or `agentmgr team start`) gives one problem to a team. By default the team is **one lead session**: one agent in your list, with one terminal, whose sub-agents (Claude Code's `--agents`) play the roles. The lead runs the steps and delegates each one to the right sub-agent. **Separate agents** (`--separate`) gives each role an agent of its own instead, with its own terminal, model and engine (for example a reviewer on Codex), and AI Agent Manager hands the work from one to the next.
+
+```
+ Analyze ──► Discuss ──► Implement ──► Test ──► Review ──► you: PR, keep, or send back
+ analyst     critics      implementer   tester   reviewer
+             agree / changes / questions  ▲  fail   │ changes
+             (up to 3 rounds)             └─────────┴─ (up to 3 rounds)
+```
+
+- **Analyst** studies the problem and the code and writes the analysis: findings, approach, files, risks, how to test. It doesn't change code.
+- **Critics** (0–2, default 1) challenge the analysis, marking points *must*, *should* or *question*. The analyst answers every point, changing the analysis or saying why not, until the critics agree.
+- **Implementer** builds the agreed analysis and commits on the team's branch.
+- **Tester** runs the tests and tries the change; it may add tests, but failures go back to the implementer.
+- **Reviewer** reviews the diff against the analysis and the test report, and approves it or sends it back. It also checks coverage: what the request asks for that isn't built yet goes in its review's **Gaps** section, with a `coverage: complete` or `coverage: partial` line.
+
+**Gap rounds.** A big request rarely gets built in one pass. When the reviewer approves good work but lists gaps, the team stops and shows you the gaps. **Run a gap round** (`agentmgr team fix-gaps <team> ["note"]`) starts the next quest (`quest-2/`, …), from a new analysis, for just what is missing, on the same branch; or take the work as it is. You can run a gap round after merging too. Each round shows up under **Earlier requests**. To let the team run some gap rounds without asking, set **Gap rounds without asking** in the form (`--gap-rounds 2`); it asks you once those are used up.
+
+Either way, the roles hand off through Markdown files in the team's folder (`~/.agentmanager/teams/<id>/`: `analysis-1.md`, `critique-1-1.md`, `test-1.md`, `review-1.md`, …), each ending with a `verdict:` line. AI Agent Manager reads each verdict to show where the team stands, and you can read every handoff in the team view. With separate agents it also tells the next agent what to read. The team works in one worktree and branch.
+
+**You step in only at the end:** when the reviewer approves, the team shows up in your inbox. **Open a pull request** (the implementer pushes and opens it), **Keep the branch**, or **Send back** with what to change (it goes through test and review again).
+
+**The lead stays.** When a quest ends, the lead keeps its session. Ask it for more work in its terminal (or in the team view's **New request**, or `agentmgr team ask <team> "…"`), and it runs that request through the team as the next quest, on the same branch, with its own folder (`quest-2/`, …) and its own stop for you at the end. A question about the work just gets an answer. Earlier quests and their handoffs stay in the team view.
+
+**A new project, with no repository yet:** leave the repository and folder empty (or give a folder that doesn't exist yet). The team creates the folder (under `~/.agentmanager/projects/` by default; `teams.newProjectsDir` in config.json), starts a git repository with an empty first commit on `main`, and works on its own branch. At the end you choose **Merge into main** (a fast-forward of the local `main`), **Publish to GitHub** (the implementer creates a private repository with `gh`, pushes, and opens a pull request), or **Keep the branch**. If the analyst and the critics don't agree within 3 rounds, or the tester and reviewer still send the work back after 3, the team stops and asks you: one more round (with a note), or move on.
+
+**Cost:** a team is up to six sessions on one problem, so expect several times the tokens of a single agent. Pick the model per role, for example a stronger model for the analyst and the reviewer: `analyst=opus reviewer=opus` in the form, or `--role-model` on the command line. Defaults go in config.json under `teams`: `critics`, `maxRounds`, `maxLoops`, `gapRounds`, `models`, `engines` (a critic or reviewer on another engine sees different things).
+
 ## Races
 
 **+ New agents → Race variants** (or `agentmgr race start`) creates one agent per variant. Each runs in its own worktree. A variant is a model, an approach, or both: `opus`, `sonnet | keep the change minimal`, `| use a cache`. **Compare** opens the scoreboard:
@@ -672,6 +721,27 @@ agentmgr leave           # the hub forgets this Mac
 
 **On Railway.** `hub/Dockerfile` builds the hub alone, with no node-pty and no Claude. Set `RAILWAY_DOCKERFILE_PATH=hub/Dockerfile`, `AGENTMGR_HUB_TOKEN`, `AGENTMGR_HUB_URL` (its https address) and, for Google sign-in, the three variables above; add a volume at `/data` so enrollments survive redeploys, and join with the `https://…up.railway.app` address.
 
+## Cleaning up old agents
+
+Agents you no longer use keep a session open and a worktree on disk. **Clean up** (in the top bar, or `agentmgr cleanup`) closes agents with no activity for a while and deletes agents that stayed closed long after that. Pick a strategy:
+
+| Strategy | What happens on its own (checked every few hours) |
+|---|---|
+| **Close, then delete** (`close-delete`) | Closes agents idle 14 days, and deletes agents closed for 14 more days. |
+| **Close; delete when I say** (`close`, the default) | Closes idle agents. Deleting waits for **Close and delete due now** or `agentmgr cleanup --run`. |
+| **Manual** (`manual`) | Nothing. Run it when you want. |
+| **Off** (`off`) | Nothing. |
+
+Both numbers of days are adjustable. Closing ends the session; resume the agent any time. Deleting removes the agent from your list along with the worktree AI Agent Manager created (Claude's own transcripts stay in `~/.claude`). Clean up never touches an agent marked **Keep** (the button on an agent), one that is working or still setting up, or a member of a team that is still going. It doesn't delete an agent with an open pull request, uncommitted changes, or commits that aren't on any other branch or remote: merge or push the work first. The dialog lists what is due, what is left alone and why, and the last run.
+
+```bash
+agentmgr cleanup                                  # what is due, and what is left alone
+agentmgr cleanup --run                            # close and delete what is due now (--close-only: just close)
+agentmgr cleanup --strategy close-delete --close-after 14 --delete-after 14
+```
+
+Agents closed before clean up was turned on count as closed from the first check, so nothing is deleted the day you turn it on.
+
 ## Saving state: flush and restart
 
 - **What's saved immediately.** Agent records (session IDs, settings, links) are written to `state.json` on every change, fsynced, then atomically replaced. Claude writes each conversation to its own transcript as it goes.
@@ -729,9 +799,11 @@ State lives in `~/.agentmanager/` (`state.json`, `daemon.log`, `repos/` for shar
   "inbox": true,
   "maxCheckpoints": 40,
   "raceTestTimeoutSec": 900,
+  "teams": { "mode": "lead", "critics": 1, "maxRounds": 3, "maxLoops": 3, "gapRounds": 0, "newProjectsDir": "~/projects", "models": { "analyst": "opus", "reviewer": "opus" } },
   "conflictRefreshSec": 60,
   "stuck": { "repeatFailures": 3, "thrashReverts": 2, "thrashEdits": 10, "driftMinutes": 20, "driftActions": 25 },
   "judge": { "enabled": true, "model": "haiku", "dailyCalls": 300 },
+  "cleanup": { "strategy": "close", "closeAfterDays": 14, "deleteAfterDays": 14 },
   "hub": { "allow": ["view"], "projects": ["*"] }
 }
 ```

package/bin/agentmgr.js

@@ -1,4 +1,11 @@
 #!/usr/bin/env node
-import { main } from '../src/cli.js';
-
-main(process.argv);
+// Dependencies are loaded behind a check, so a git checkout without `npm install` says so.
+try {
+  const { main } = await import('../src/cli.js');
+  await main(process.argv);
+} catch (err) {
+  if (err?.code !== 'ERR_MODULE_NOT_FOUND' || !/Cannot find package/.test(err.message)) throw err;
+  const dir = new URL('..', import.meta.url).pathname;
+  console.error(`agentmgr: dependencies are missing (${err.message.match(/'([^']+)'/)?.[1] ?? 'a package'}).\nRun \`npm install\` in ${dir} and try again.`);
+  process.exit(1);
+}

package/docs/architecture.md

@@ -27,6 +27,7 @@ No build step: Node ES modules on the server, plain ES modules in the browser. S
 | `src/inbox.js`, `src/stuck.js`, `src/conflicts.js` | The decision inbox (prompts and questions), stuck detection and the conflict radar: the rules that decide *when* to look. |
 | `src/judge.js` | The AI judge: one-shot, tool-less model calls that decide *what is going on* (stuck, waiting, done, collisions, backlog order, alert triage), with a daily cap and feedback examples. Falls back to the rules. |
 | `src/backlog.js`, `src/races.js` | Work orders picked up per project; several agents on one intent, compared. |
+| `src/teams.js` | Agents in roles on one problem: handoff files with a verdict line move the team from analysis to review. |
 | `src/notify.js` | Slack alerts, triaged by the judge. |
 | `src/preview.js`, `src/livebrowser.js` | Browser tabs: HTTPS relays for remote devices, and a headless Chrome streamed over the Chrome DevTools Protocol (frames, input, sound). |
 | `src/sessions.js` | Finds Claude Code sessions started in a terminal so they can be continued as agents. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-agentmanager",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Run background coding agents (Claude Code, Codex) per intent, and keep track of them from a web UI, your phone or the CLI",
   "keywords": [
     "claude",