From ee266d9d82bfb7435ec313664f1bb712f5d6e029 Mon Sep 17 00:00:00 2001 From: codeaholicguy Date: Sun, 18 Oct 2026 07:50:36 +0000 Subject: [PATCH] docs: address 0.70.1 audit (orchestration, troubleshooting, README) - Add multi-agent orchestration, troubleshooting, and permissions docs - Expand agent-management, getting started, runtime, and capacity docs - Fix README setup/init, built-in skills count, harness table, CONTRIBUTING link - Document send flags, known limitations, Linux lsof, Node ABI, devkitd - Sitemap: canonical trailing slashes for doc URLs --- README.md | 70 ++++--- web/app/sitemap.ts | 2 +- web/content/docs/0-what-is-ai-devkit.md | 2 +- web/content/docs/1-getting-started.md | 16 +- web/content/docs/15-capacity.md | 4 +- web/content/docs/16-runtime.md | 19 +- .../docs/17-multi-agent-orchestration.md | 177 ++++++++++++++++++ web/content/docs/18-troubleshooting-agents.md | 108 +++++++++++ web/content/docs/19-permissions.md | 126 +++++++++++++ web/content/docs/2-supported-agents.md | 2 +- web/content/docs/6-memory.md | 2 + web/content/docs/8-agent-management.md | 52 ++++- 12 files changed, 533 insertions(+), 47 deletions(-) create mode 100644 web/content/docs/17-multi-agent-orchestration.md create mode 100644 web/content/docs/18-troubleshooting-agents.md create mode 100644 web/content/docs/19-permissions.md diff --git a/README.md b/README.md index 2e46598e0..3f2170b2a 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,15 @@ AI DevKit gives Claude Code, Codex CLI, Gemini CLI, opencode, Pi, Cursor, GitHub The future is many AI coding agents. AI DevKit is the layer that makes them manageable. -Run `npx ai-devkit@latest init` and your project gets: +Run machine setup once, then `init` in each project: + +```bash +npx ai-devkit@latest setup +cd your-project +npx ai-devkit@latest init +``` + +`setup` installs built-in skills globally, session hooks, and the memory MCP wiring. `init` writes project-local config. Your project gets: | What you need | What AI DevKit installs | |---------------|-------------------------| @@ -56,10 +64,14 @@ Before AI DevKit, your agents are powerful but scattered. After AI DevKit, they ## Start in 30 seconds ```bash +npx ai-devkit@latest setup +cd your-project npx ai-devkit@latest init ``` -One wizard. Pick your agents, install the control-plane pieces you need, and give every tool the same operating model. It writes project-local files you can review and commit. Re-run it whenever your agent list or workflow changes. +Run `setup` once per machine, then `init` per project. Pick your agents, install the control-plane pieces you need, and give every tool the same operating model. Re-run `init` whenever your agent list or workflow changes. + +Multi-agent orchestration (lead plus workers): **[docs guide](https://ai-devkit.com/docs/17-multi-agent-orchestration/)**. Here's what lands in your repo: @@ -68,7 +80,7 @@ your-project/ ├── .ai-devkit.json # single source of truth (re-run init anytime) ├── .claude/ # or .cursor/, .codex/, etc. per agent you picked │ ├── skills/ # dev-lifecycle, verify, memory, tdd, ... -│ └── settings.json # MCP servers wired up (incl. @ai-devkit/memory) +│ └── … # Claude: project MCP in `.mcp.json`; memory MCP wired globally by `setup` └── docs/ai/ ├── requirements/ # phase 1 — what to build, why ├── design/ # phase 2 — how it'll be built @@ -79,7 +91,7 @@ your-project/ ## Operate agents like infrastructure -AI DevKit ships a agent control plane for everyday multi-agent work: +AI DevKit ships an agent control plane for everyday multi-agent work: ```bash # List running sessions across providers @@ -171,7 +183,7 @@ Agent: Audits the diff against the design doc — scope creep, ## What changes in agent behavior -The flow above is powered by nine built-in skills, each addressing a failure mode developers see in real AI coding sessions: +The flow above is powered by **24 built-in skills** (installed globally by `setup`), including these core workflow skills: | Failure mode | AI DevKit behavior | |--------------|--------------------| @@ -183,39 +195,41 @@ The flow above is powered by nine built-in skills, each addressing a failure mod | Debugging becomes guess-and-patch | `structured-debug` makes it reproduce, hypothesize, fix, and verify | | Existing code is opaque | `document-code` maps entry points, dependencies, and behavior | | Implementation gets bloated | `simplify-implementation` reduces complexity before code ships | -| Documentation is hard to follow | `technical-writer` audits docs for novice-user clarity | +| Documentation is hard to follow | `document-code` maps code; add community `technical-writer` via `skill add` if needed | -Need more? `ai-devkit skill add ` pulls from 30+ publishers — Anthropic, Vercel, Supabase, Microsoft, Google. +Need more? `ai-devkit skill add ` pulls from 30+ publishers — Anthropic, Vercel, Supabase, Microsoft, Google. See the full built-in list in [Skills docs](https://ai-devkit.com/docs/7-skills/). ## Works across coding agents One `.ai-devkit.json` configures all of them. Add a new agent to your team without rewriting your rules. -| Agent | Setup | Remote control | +| Agent / environment | Project `init` setup | `agent start` / `send` control plane | |-------|-------|----------------| -| [Claude Code](https://www.anthropic.com/claude-code) | yes | yes | -| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | yes | yes | -| [Codex CLI](https://github.com/openai/codex) | yes | yes | -| [Grok Build CLI](https://x.ai/cli) | yes | yes | -| [Junie](https://www.jetbrains.com/junie/) | yes | — | -| [Cline](https://cline.bot/) | yes | — | -| [Devin](https://devin.ai/) | yes | — | -| [opencode](https://opencode.ai/) | yes | testing | -| [Pi](https://pi.dev) | yes | yes | -| [Kiro CLI](https://kiro.dev/cli/) | yes | yes | +| [Claude Code](https://www.anthropic.com/claude-code) | yes | yes (`claude`) | +| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | yes | yes (`gemini_cli`) | +| [Codex CLI](https://github.com/openai/codex) | yes | yes (`codex`) | +| [Grok Build CLI](https://x.ai/cli) | yes | yes (`grok_cli`) | +| [opencode](https://opencode.ai/) | yes | yes (`opencode`) | +| [Pi](https://pi.dev) | yes | yes (`pi`) | +| [GitHub Copilot](https://github.com/features/copilot) | yes | yes (`copilot`) | +| [Kiro CLI](https://kiro.dev/cli/) | yes | yes (`kiro`) | +| [Devin](https://devin.ai/) | yes | yes (`devin`) | +| [Muse Code](https://dev.meta.ai/products/muse-code/) | yes | yes (`muse`) | +| [Antigravity CLI](https://antigravity.google/) | yes | yes (`antigravity_cli`) | | [Cursor](https://cursor.sh/) | yes | — | -| [GitHub Copilot](https://code.visualstudio.com/) | yes | — | -| [Antigravity](https://antigravity.google/) | yes | yes | -| [Amp](https://ampcode.com/) | yes | — | -| [Kilo Code](https://github.com/Kilo-Org/kilocode) | yes | — | -| [Roo Code](https://roocode.com/) | testing | — | +| [Junie](https://www.jetbrains.com/junie/) | yes | setup/skills only | +| [Cline](https://cline.bot/) | yes | setup/skills only | +| [Antigravity IDE](https://antigravity.google/) | yes | setup/skills only | +| [Amp](https://ampcode.com/) | yes | setup/skills only | +| [Kilo Code](https://github.com/Kilo-Org/kilocode) | yes | setup/skills only | +| [Roo Code](https://roocode.com/) | testing | setup/skills only | -**Setup** — `ai-devkit init` writes the agent's config (rules, MCP servers, and skills) so it joins the same operating layer. -**Remote control** — drive running sessions from `ai-devkit agent send` and route them through external channels. +**Setup** — `ai-devkit setup` (machine) plus `ai-devkit init` (project) writes each agent's config (rules, MCP, skills). +**Control plane** — `agent list`, `agent send`, and managed `agent start` target tmux-backed CLI sessions on **macOS/Linux** (experimental console; requires tmux). Use [channels](https://ai-devkit.com/docs/12-channel/) to message a running agent from Telegram or Slack. Not supported on Windows console. ## How is this different from `CLAUDE.md`, `.cursor/rules`, or `AGENTS.md`? -Those files are static instructions the agent re-reads. AI DevKit gives agents a **operating layer**: generated setup, a control console, cross-agent messaging, local searchable memory, phase docs, skills loaded on demand, and verification gates. The rules still matter, but AI DevKit makes them operational across tools. +Those files are static instructions the agent re-reads. AI DevKit gives agents an **operating layer**: generated setup, a control console, cross-agent messaging, local searchable memory, phase docs, skills loaded on demand, and verification gates. The rules still matter, but AI DevKit makes them operational across tools. | Static rules files | AI DevKit | |--------------------|-----------| @@ -230,13 +244,13 @@ Those files are static instructions the agent re-reads. AI DevKit gives agents a - **Not a smarter LLM.** Bad models stay bad — this raises the floor on process, not on raw capability. - **Not a replacement for Claude Code, Codex, Cursor, Gemini CLI, or opencode.** AI DevKit configures, supervises, and coordinates the agents you already use. - **Not a magic "write the feature for me" button.** You still review the requirements doc, accept the design, and read the diff. The workflow makes that review possible because you have artifacts to point at instead of only chat scrollback. -- **Not a hosted service.** Apache-2.0-licensed, runs locally, no telemetry. Memory is a SQLite file on your disk. The agent control plane talks to the agent SDKs you already use. +- **Not a hosted service.** Apache-2.0-licensed, runs locally, no telemetry. Memory is a SQLite file on your disk. The control plane detects CLI sessions, types into tmux panes, and reads session files — it does not run a remote cloud agent for you. ## Documentation & community - Full guides, workflow patterns, skill authoring → **[ai-devkit.com/docs](https://ai-devkit.com/docs/)** - Release notes → **[CHANGELOG.md](./CHANGELOG.md)** -- Contributing → **[CONTRIBUTING.md](./CONTRIBUTING.md)** +- Contributing → open an issue or PR on **[GitHub](https://github.com/Codeaholicguy/ai-devkit)** ```bash git clone https://github.com/Codeaholicguy/ai-devkit.git diff --git a/web/app/sitemap.ts b/web/app/sitemap.ts index 6bdbc725c..2ddcd32ca 100644 --- a/web/app/sitemap.ts +++ b/web/app/sitemap.ts @@ -50,7 +50,7 @@ export default function sitemap(): MetadataRoute.Sitemap { const docs = getAllDocPages(); const docRoutes = docs.map((doc) => ({ - url: `${baseUrl}/docs/${doc.metadata.slug}`, + url: `${baseUrl}/docs/${doc.metadata.slug}/`, lastModified: new Date(), changeFrequency: 'weekly' as const, priority: 0.7, diff --git a/web/content/docs/0-what-is-ai-devkit.md b/web/content/docs/0-what-is-ai-devkit.md index 9e67f1be9..fec8e6d3c 100644 --- a/web/content/docs/0-what-is-ai-devkit.md +++ b/web/content/docs/0-what-is-ai-devkit.md @@ -79,7 +79,7 @@ The [Memory](/docs/6-memory) service gives your coding agents persistent, local ### Multi-Agent Support -AI DevKit isn't tied to a single tool. It supports [many AI coding environments](/docs/2-supported-agents) and sets up the right configuration files, skills, and instructions for each one. Switch between agents or use multiple at the same time. Your workflows, memory, skills, and operating model carry across supported environments. +AI DevKit isn't tied to a single tool. It supports [many AI coding environments](/docs/2-supported-agents) and sets up the right configuration files, skills, and instructions for each one. Switch between agents or use multiple at the same time. Your workflows, memory, skills, and operating model carry across supported environments. Managed `agent start` and `agent send` apply to the CLI harness types listed in [Agent Management](/docs/8-agent-management). ### Observe And Operate diff --git a/web/content/docs/1-getting-started.md b/web/content/docs/1-getting-started.md index e13fd9d0e..b09db8de7 100644 --- a/web/content/docs/1-getting-started.md +++ b/web/content/docs/1-getting-started.md @@ -21,8 +21,16 @@ Before you begin, make sure you have: - **Node.js 20.20.0 or newer** - **npm** or **npx**, which comes with Node.js - **tmux** for interactive managed agents (provisional compatibility floor: tmux 2.6+; setup reports but does not reject older versions) +- **`lsof` on Linux** for reliable agent session detection (strongly recommended; see [Agent Management](/docs/8-agent-management#linux-session-detection)) - At least one [supported AI coding agent or environment](/docs/2-supported-agents) +### Node.js and native modules + +The CLI bundles native SQLite support (`better-sqlite3`) compiled for the **Node version used when you installed** `ai-devkit`. If agents run under a different Node (common when tmux inherits another `PATH`), memory and related commands can fail with a `NODE_MODULE_VERSION` error. + +- Reinstall `ai-devkit` with the same Node your agents use, or align the tmux server environment: `tmux set-environment -g PATH '/path/to/node/bin:…'`. +- Pin one Node version for `npm test` and for agent shells so verification matches CI. + Install and launch your coding agent at least once before running `setup`. AI DevKit detects an agent from its home directory, so a newly installed agent that has never started may be reported as skipped. ## Choose How to Run AI DevKit @@ -174,9 +182,11 @@ The installed workflow skills guide requirements, design, planning, implementati 1. [Check environment-specific project support](/docs/2-supported-agents) 2. [Learn how project init and install work](/docs/9-agent-setup) 3. [Operate running agents](/docs/13-agent-console) -4. [Give agents long-term memory](/docs/6-memory) -5. [Manage skills](/docs/7-skills) -6. [Install plugins](/docs/14-plugins) +4. [Multi-agent orchestration](/docs/17-multi-agent-orchestration) (lead plus workers) +5. [Give agents long-term memory](/docs/6-memory) +6. [Manage skills](/docs/7-skills) +7. [Install plugins](/docs/14-plugins) +8. [Troubleshooting agents](/docs/18-troubleshooting-agents) ## Need Help? diff --git a/web/content/docs/15-capacity.md b/web/content/docs/15-capacity.md index f5f65c481..dbb9d1f2e 100644 --- a/web/content/docs/15-capacity.md +++ b/web/content/docs/15-capacity.md @@ -17,7 +17,9 @@ ai-devkit status ai-devkit status --json ``` -The report covers the CLI version (and whether npm has a newer one), the project config, per-agent readiness (executable found, authentication, skills installed), tmux, skill registries, channels, and per-agent memory MCP wiring. Run it first when something feels off — it is the fastest way to tell a missing login from a missing binary. +The report covers the CLI version (and whether npm has a newer one), the project config, per-agent readiness (executable found, authentication, skills installed), tmux, skill registries, channels, and per-agent memory MCP wiring. Run it first when something feels off. + +Treat auth and readiness rows as hints: some harnesses show `ready` without a successful login probe, and others show `auth fail` when a login-free model path still works. For orchestration, prefer a real `agent start` plus `send` handshake (see [Multi-agent orchestration](/docs/17-multi-agent-orchestration)). ## Capacity diff --git a/web/content/docs/16-runtime.md b/web/content/docs/16-runtime.md index 6450b16e1..2a6ea77b8 100644 --- a/web/content/docs/16-runtime.md +++ b/web/content/docs/16-runtime.md @@ -24,19 +24,28 @@ ai-devkit daemon install # install a systemd --user unit for boot persistence `daemon install` writes a `systemd --user` unit so the daemon survives logout and reboot; it is available on Linux only. To remove persistence, disable the unit with `systemctl --user` and run `ai-devkit daemon stop`. +### Environment variables + +| Variable | Purpose | +|----------|---------| +| `DEVKITD_BIN` | Path to a custom `devkitd` binary (documented above) | +| `AI_DEVKIT_NO_DAEMON` | When set, skip auto-spawning `devkitd` and use in-process behavior (useful when debugging stale daemon issues) | + ## Troubleshooting - **"binary not found"**: the daemon binary is resolved from `DEVKITD_BIN`, the platform package, or a cargo build — set `DEVKITD_BIN` to a valid `devkitd` binary if you run from a source checkout. - **Stale socket**: if the daemon crashed, delete `~/.ai-devkit/daemon.sock` and let the next command respawn it. -- **Logs**: `ai-devkit daemon logs -n 200` shows recent daemon activity, including auto-spawn failures. +- **Logs**: `ai-devkit daemon logs -n 200` (or `daemon logs --lines 200`) shows recent daemon activity, including auto-spawn failures. +- **Stale daemon after upgrade**: an old `devkitd` can keep serving until you run `ai-devkit daemon stop`, then retry your command. Use `AI_DEVKIT_NO_DAEMON=1` to compare behavior without the daemon. -## Upgrading to 0.69 +## Upgrading to 0.69+ 0.69 is the first release that distributes a platform binary and runs the daemon. On upgrade: -1. No manual step is needed — the daemon auto-spawns on the next `ai-devkit agent` command. -2. Everything lives under `~/.ai-devkit/` (`daemon.sock`, `daemon.log`); nothing is written to your project. -3. To stop it entirely, run `ai-devkit daemon stop`. To keep it running across reboots, run `ai-devkit daemon install` on Linux. +1. Run `ai-devkit daemon stop` after upgrading the CLI so a new `devkitd` binary is not mixed with an old long-running process. +2. The next `ai-devkit agent` command auto-spawns the daemon if needed. +3. Everything lives under `~/.ai-devkit/` (`daemon.sock`, `daemon.log`); nothing is written to your project. +4. To stop it entirely, run `ai-devkit daemon stop`. To keep it running across reboots, run `ai-devkit daemon install` on Linux. ## Next Steps diff --git a/web/content/docs/17-multi-agent-orchestration.md b/web/content/docs/17-multi-agent-orchestration.md new file mode 100644 index 000000000..068fb1c2f --- /dev/null +++ b/web/content/docs/17-multi-agent-orchestration.md @@ -0,0 +1,177 @@ +--- +title: Multi-Agent Orchestration +description: Run a lead coding agent with Codex, OpenCode, and other workers using ai-devkit agent start and agent send, with worktree isolation and cross-review. +slug: multi-agent-orchestration +section: workflows +order: 5 +--- + +Use this guide when one coding agent (the **lead**) supervises other **workers** through `ai-devkit agent start` and `ai-devkit agent send`. You stay in your shell (or inside the lead's session); workers run in separate tmux sessions that AI DevKit can address by name. + +For day-to-day monitoring without a lead agent, use [Agent Console](/docs/13-agent-console) instead. + +## When to use a lead agent vs the console + +| Approach | Best for | +|----------|----------| +| **Lead agent + workers** | Scripted delegation, cross-harness review (for example Claude lead with Codex and OpenCode workers), CI-style loops | +| **`agent console`** | Human supervision, quick messages, starting one agent at a time with harness CLI args | +| **Channels** | Operating a single running agent from Telegram or Slack | + +Managed `agent start` uses **tmux** on macOS and Linux. The console is experimental on those platforms and is not supported on Windows. See [Agent Console](/docs/13-agent-console) and [Getting Started](/docs/1-getting-started). + +## Layout: one directory per agent + +Give every worker its own working directory. Session matching uses project path and start time; two agents in the same folder can show each other's conversations in `agent list`, `agent console`, or `send --wait`. + +Use a **git worktree** per worker when they touch the same repository: + +```bash +git -C my-repo worktree add ../my-repo-impl -b feature/impl +git -C my-repo worktree add ../my-repo-tests -b feature/tests +``` + +Typical layout: + +```text +team/ +├── lead/ # lead agent cwd (integration, merges) +├── impl/ # worker: implementation +└── tests/ # worker: test fixes +``` + +Point each `agent start --cwd` at the correct tree. See [Troubleshooting: Agents & Orchestration](/docs/18-troubleshooting-agents) if names or sessions look wrong. + +## Install skills for the lead + +Built-in skills cover single-agent management: + +- `agent-management` — start, assign, kill +- `agent-communication` — `send`, `--wait`, `--stdin` + +`agent-orchestration` is **not** in the default built-in set. Add it when the lead should run a long supervision loop: + +```bash +ai-devkit skill add ai-devkit agent-orchestration +``` + +## Version notes (0.70.1 vs newer) + +| Behavior | On 0.70.1 and earlier | After session-wait fix ships (merged on `main`, not yet in npm `latest` at 0.70.1) | +|----------|----------------------|-------------------------------------------------------------------------------------| +| First `send --wait` right after `start` | Fails with `No session file found for agent …` until the harness creates a session file | `send --wait` can wait for the session file to appear | +| Recommended handshake | Plain `ready?` first, then `send --wait` | Plain `ready?` is still a good readiness check | + +Always follow the **start-then-assign** sequence below on 0.70.1. + +## Start-then-assign sequence (robust on 0.70.1) + +Start workers **one at a time**. Do not run `agent list`, `agent console`, or tight list loops while a worker is still starting — a concurrent list can register an auto name and **drop your `--name`** (see [Known limitations](/docs/8-agent-management#known-limitations)). + +For each worker: + +1. **Start** (example): + + ```bash + ai-devkit agent start --type codex --name impl --cwd ../my-repo-impl + ``` + +2. **Wait for the tmux session** (do not poll `agent list` during this window): + + ```bash + sleep 15 + tmux has-session -t impl 2>/dev/null + ``` + +3. **First message without `--wait`** (creates or wakes the session file on most harnesses): + + ```bash + ai-devkit agent send --id impl "ready?" + ``` + +4. **Confirm with wait** (up to 3 retries if needed): + + ```bash + ai-devkit agent send --id impl --wait --timeout 180000 "ready?" + ``` + +5. **Re-list once** if `send` cannot find the name, then use the exact name from `agent list --json`. Prefer exact `--id` values; partial matches can hit the wrong agent. + +Dispatch long tasks with the harness's own background mechanism (for example Claude Code `run_in_background`), not shell `&` in a single command, so approval rules stay predictable. + +## Lead rules template + +Copy into the lead's `AGENTS.md` or `CLAUDE.md` (adjust paths and worker names): + +```markdown +# Multi-agent lead rules + +## Workers +- impl: Codex, cwd ../my-repo-impl +- tests: OpenCode, cwd ../my-repo-tests + +## Starting workers +1. Start one worker at a time with `ai-devkit agent start --type --name --cwd `. +2. Never run `ai-devkit agent list` or `agent console` while a start is in progress. +3. After each start: `sleep 15`, then `ai-devkit agent send --id "ready?"` (no --wait). +4. Then `ai-devkit agent send --id --wait --timeout 180000 "ready?"` up to 3 times. +5. Use exact agent names from `ai-devkit agent list --json`. + +## Commands +- Use `git -C ` and absolute paths; do not `cd` in shell commands. +- Do not use `&` in shell; use the harness background tool when needed. +- Do not call `tmux` from the lead. + +## Work assignment +- Give each worker a self-contained task, scope, and validation command. +- After workers finish, have worker A review B's diff against SPEC.md (LGTM or numbered findings). +- Integrate with `git -C team/lead merge …` and run tests before claiming done. +``` + +Configure harness permissions so workers do not stall on approval prompts — see [Per-harness permission setup](/docs/19-permissions). + +## Worked example: Claude lead, Codex + OpenCode workers + +Prerequisites: `ai-devkit setup`, project `init`, `tmux`, and `lsof` on Linux (see [Getting Started](/docs/1-getting-started)). + +```bash +# Machine setup once +npm install -g ai-devkit +ai-devkit setup + +# Project +cd my-repo && ai-devkit init + +# Worktrees +git worktree add ../my-repo-impl -b demo/impl +git worktree add ../my-repo-tests -b demo/tests + +# Start workers (one at a time; run the ready? handshake after each) +ai-devkit agent start --type codex --name impl --cwd ../my-repo-impl +# … sleep 15, send ready? twice as above … + +ai-devkit agent start --type opencode --name tests --cwd ../my-repo-tests +# … ready? handshake … + +# Lead (human or Claude Code in team/lead) assigns tasks with send --wait +ai-devkit agent send --id impl --wait --timeout 300000 "Implement TODO in SPEC.md; run npm test in this directory." +``` + +Cross-review step (lead or a worker): + +```bash +ai-devkit agent send --id impl --wait --timeout 300000 "Review the diff in ../my-repo-tests against SPEC.md. Reply LGTM or a numbered list of issues." +``` + +## Console-only harness flags + +`ai-devkit agent start` accepts `--type`, `--mode`, `--name`, `--cwd`, and `--debug`. It does **not** pass an initial prompt or harness CLI flags (for example Codex `--ask-for-approval never` or Gemini `--approval-mode=yolo`). + +To pass those at start time, use **Agent Console** (`s` → **task** and **args** fields) or start the harness manually in tmux and let AI DevKit detect it. See [Agent Console — Start an agent](/docs/13-agent-console). + +## Related docs + +- [Agent Management](/docs/8-agent-management) — command reference and known limitations +- [Troubleshooting: Agents & Orchestration](/docs/18-troubleshooting-agents) +- [Per-harness permission setup](/docs/19-permissions) +- [Skills](/docs/7-skills) — installing `agent-orchestration` diff --git a/web/content/docs/18-troubleshooting-agents.md b/web/content/docs/18-troubleshooting-agents.md new file mode 100644 index 000000000..6c312f5ee --- /dev/null +++ b/web/content/docs/18-troubleshooting-agents.md @@ -0,0 +1,108 @@ +--- +title: Troubleshooting Agents & Orchestration +description: Symptom, cause, and fix for common ai-devkit agent start, send, list, and multi-agent orchestration errors on macOS and Linux. +slug: troubleshooting-agents +section: reference +order: 4 +--- + +Use this page when `agent start`, `agent send`, `agent list`, or multi-agent orchestration fails. Format matches the [Channel](/docs/12-channel) troubleshooting style: **symptom → cause → fix**. + +For permission and hook stalls, see [Per-harness permission setup](/docs/19-permissions). For the full orchestration recipe, see [Multi-agent orchestration](/docs/17-multi-agent-orchestration). + +## `No session file found for agent "X"; cannot wait for response.` + +**Cause:** On 0.70.1 and earlier, `send --wait` requires a session file. Most harnesses create that file only after the first user message. + +**Fix:** + +1. Send a plain message first: `ai-devkit agent send --id X "ready?"` (no `--wait`). +2. Then: `ai-devkit agent send --id X --wait --timeout 180000 "ready?"`. +3. On releases after 0.70.1, `send --wait` waits for the session file to appear; the two-step handshake is still recommended for booting TUIs. + +## `No agent found matching "X"` right after start, or list shows `{folder}-{pid}` + +**Cause:** While `agent start` waits for a stable PID, `agent list` or `agent console` can register the process under an auto name. When start finishes, the requested `--name` is dropped silently. + +**Fix:** + +- Do not run `agent list` or open `agent console` while a start is in progress. Wait with `tmux has-session -t ` or `sleep 15`. +- Rename: `ai-devkit agent rename `. +- Re-list once and use exact names from `agent list --json`. + +## Codex shows `-`; `agent kill impl` says no agents found + +**Cause:** For Codex, the registry may store the `codex app-server` child PID instead of the TUI process, so names and kill targets disagree. + +**Fix:** + +- Send using the exact name from `agent list --json` (avoid short partial `--id` like `impl` if another agent matches). +- To stop: kill using the listed name, then if the tmux session remains: `tmux kill-session -t ` and optionally `pkill -f "codex app-server"`. + +## Two agents show each other's conversation + +**Cause:** Session matching uses working directory and start time. Two agents of the same type in one directory within a few minutes can be swapped. + +**Fix:** One git worktree or directory per agent. See [Multi-agent orchestration](/docs/17-multi-agent-orchestration). + +## Status always `process running` or empty on Linux; `--wait` never completes + +**Cause:** Process cwd detection needs `lsof` on Linux. Without it, a `pwdx` fallback in 0.70.1 can fail to parse output, leaving cwd empty so no session matches. + +**Fix:** + +- Install `lsof` and ensure it is on `PATH` for the shell that runs `ai-devkit` and for the **tmux server** (agents inherit that environment). +- If `agent list` hangs with `lsof`, try lowering open-file limits for that command (for example `ulimit -n 1024`). + +## Pi session never appears; `--wait` fails after a slow first reply + +**Cause:** Pi writes its session file on first reply. Matching uses a short time window from process start; a first reply more than ~3 minutes after start may never match. + +**Fix:** Start the Pi worker alone, send `ready?` immediately after start, or use a faster model. Consider `@ai-devkit/pi-session-tracker` (see [Agent Management](/docs/8-agent-management)). + +## Message to OpenCode (or lead) vanished right after start + +**Cause:** `agent send` types into the tmux pane. If the TUI has not finished drawing its input area, keystrokes are lost while `send` still reports success. + +**Fix:** Wait ~15 seconds after start (or until the pane stops changing), send `ready?` without `--wait`, then retry with `--wait`. If status stays `process running` after 60 seconds, resend. + +## `not waiting for input (status: running). Sending anyway.` + +**Cause:** `send` does not block when the harness is busy. Claude Code may report `running` while idle at a prompt. Messages can queue, mix, or pair with the wrong `--wait` reply. + +**Fix:** Treat `send` in scripts as best-effort unless the agent is waiting. For orchestration, use explicit handshakes and avoid back-to-back `--wait` calls without reading `agent detail`. Do not rely on `--wait` immediately after a busy send. + +## List "Working On" shows `…` or stale `ready?` + +**Cause:** Known display limitations in 0.70.x when summarizing some harness outputs. + +**Fix:** Use `ai-devkit agent detail --id --tail 20` for ground truth before acting. + +## Codex worker stuck on "1 hook needs review" + +**Cause:** Codex SessionStart hook from the curated ai-devkit plugin expects `~/.codex/hooks/codex-session-mapping.cjs`. If missing, the first `send` is swallowed. + +**Fix:** Run `ai-devkit setup --agent codex`, or set `[features] hooks = false` in `~/.codex/config.toml`. See [Codex integration FAQ](/faq/ai-devkit-codex-integration) and [Per-harness permission setup](/docs/19-permissions). + +## `NODE_MODULE_VERSION … compiled against a different Node.js version` + +**Cause:** The CLI bundles native `better-sqlite3` built for the Node version used at `npm install -g`. Agents started in tmux with a different Node on `PATH` hit memory and other native paths. + +**Fix:** Reinstall `ai-devkit` with the same Node your agents use, or set the tmux server `PATH` to that Node (`tmux set-environment -g PATH '…'`). See [Getting Started — Node.js and native modules](/docs/1-getting-started#nodejs-and-native-modules). + +## `agent list` empty or stale after upgrading AI DevKit + +**Cause:** An old `devkitd` can keep serving after a CLI upgrade. + +**Fix:** + +```bash +ai-devkit daemon stop +# retry your command +``` + +For debugging without the daemon: `AI_DEVKIT_NO_DAEMON=1 ai-devkit agent list` (see [Runtime (devkitd)](/docs/16-runtime)). + +## `agent open` cannot focus the terminal + +See [Agent Management — Troubleshooting](/docs/8-agent-management#troubleshooting) (macOS-focused terminal focus; tmux attach is the portable fallback on Linux). diff --git a/web/content/docs/19-permissions.md b/web/content/docs/19-permissions.md new file mode 100644 index 000000000..ede94c488 --- /dev/null +++ b/web/content/docs/19-permissions.md @@ -0,0 +1,126 @@ +--- +title: Per-Harness Permission Setup +description: Minimum allow-lists and config files so Claude Code, Codex, OpenCode, and Gemini CLI workers accept ai-devkit orchestration without stalling on prompts. +slug: permissions +section: workflows +order: 6 +--- + +Unattended multi-agent runs fail when a worker stops for tool approval, hook review, or trust dialogs. This page lists settings that worked for **ai-devkit 0.70.1 on Linux** in real orchestration demos. Other harnesses need community verification — contribute notes via [GitHub issues](https://github.com/Codeaholicguy/ai-devkit/issues). + +> **Safety:** These presets grant broad shell and file access. Use isolated git worktrees, avoid secrets in the environment, and run `verify` (or your test suite) before merging. See [Multi-agent orchestration](/docs/17-multi-agent-orchestration). + +## Summary matrix + +| Harness | Config location | Login-free option on demo box | Doc status | +|---------|-----------------|------------------------------|------------| +| Claude Code | `.claude/settings.json` | Local endpoint possible; slow on small models | Verified | +| Codex | `.codex/config.toml` + `~/.codex/config.toml` trust | Local endpoint; tool use needs a capable model | Verified | +| OpenCode | `opencode.json` / `~/.config/opencode/opencode.jsonc` | Free cloud models (pick one that responds) | Verified | +| Gemini CLI | `.gemini/settings.json` + trusted folders | Requires Google API key / login | Verified | +| Pi, Copilot, Grok, Kiro, Devin, Muse, Antigravity CLI | Varies | Mostly requires provider login | Needs contribution | + +## Claude Code (lead or worker) + +**Project** `.claude/settings.json` (example): + +```json +{ + "permissions": { + "allow": [ + "Bash(ai-devkit:*)", + "Bash(git:*)", + "Bash(npm:*)", + "Bash(node:*)", + "Bash(sleep:*)", + "Read", + "Edit", + "Write" + ] + }, + "defaultMode": "acceptEdits", + "additionalDirectories": ["/absolute/path/to/sibling-worktrees"] +} +``` + +**Trust:** Accept the workspace trust dialog once, or set `hasTrustDialogAccepted` under `projects` in `~/.claude.json`. + +**Gotchas (demo-tested):** + +- Allow rules do **not** cover `cd dir && git …` (VCS-after-cd check), commands with `&`, or `tmux capture-pane`. Lead rules should use `git -C`, harness background tools instead of `&`, and no tmux from the lead. +- Project `defaultMode: "bypassPermissions"` was not observed to apply in demos; do not rely on it for orchestration. +- Long `send --wait` calls may need higher `BASH_DEFAULT_TIMEOUT_MS` / `BASH_MAX_TIMEOUT_MS` in the environment. + +## Codex (worker or lead) + +**Project** `.codex/config.toml`: + +```toml +approval_policy = "never" +sandbox_mode = "workspace-write" +``` + +A **lead** that runs `ai-devkit` against sibling worktrees and the tmux socket may need `sandbox_mode = "danger-full-access"` so the sandbox can reach `~/.ai-devkit` and system paths. + +**Trust:** In `~/.codex/config.toml`: + +```toml +[projects."/absolute/path/to/project"] +trust_level = "trusted" +``` + +**SessionStart hook:** The curated ai-devkit Codex plugin registers a hook that expects `~/.codex/hooks/codex-session-mapping.cjs`. If that file is missing, Codex 0.163+ can block on **"1 hook needs review"** and swallow the first `send`. + +- Run `ai-devkit setup --agent codex` to install hook assets. +- Or disable hooks: `[features] hooks = false` in `~/.codex/config.toml`. + +See [Codex integration FAQ](/faq/ai-devkit-codex-integration). + +## OpenCode (worker) + +**`opencode.json`** (project) or user config: + +```json +{ + "permission": { + "bash": "allow", + "edit": "allow", + "external_directory": "allow" + } +} +``` + +Pick a model that answers reliably; free tiers can rate-limit or hang. Demo used a responsive free model rather than one that stalled. + +## Gemini CLI (worker) + +**Project** `.gemini/settings.json`: + +```json +{ + "general": { + "defaultApprovalMode": "auto_edit" + }, + "tools": { + "allowed": [ + "run_shell_command(ai-devkit)", + "run_shell_command(git)", + "run_shell_command(npm)" + ] + } +} +``` + +Add the project directory to `~/.gemini/trustedFolders.json` or workspace settings are ignored. + +**YOLO mode:** `--approval-mode=yolo` is a **CLI flag only**. `ai-devkit agent start` does not pass harness args; use [Agent Console](/docs/13-agent-console) **args**, a PATH shim on the tmux server, or start Gemini manually in tmux. + +## Harnesses not covered here + +Pi, Copilot, Grok CLI, Kiro, Devin, Muse, and Antigravity CLI support `agent start --type …` but were not fully exercised in the orchestration demos. Use `ai-devkit status` as a hint only — it can report false positives/negatives for auth (see [Status & Capacity](/docs/15-capacity)). Test login and permissions in your environment before unattended runs. + +## Related + +- [Multi-agent orchestration](/docs/17-multi-agent-orchestration) +- [Troubleshooting: Agents & Orchestration](/docs/18-troubleshooting-agents) +- [Agent Management](/docs/8-agent-management) diff --git a/web/content/docs/2-supported-agents.md b/web/content/docs/2-supported-agents.md index e5ea20225..7930aef8d 100644 --- a/web/content/docs/2-supported-agents.md +++ b/web/content/docs/2-supported-agents.md @@ -192,4 +192,4 @@ Want to add support for a new AI environment? We welcome contributions! 4. **Update Documentation** — Add the environment to this guide 5. **Test Integration** — Verify skill paths, generated configuration, and any harness behavior -See our [Contributing Guide](https://github.com/Codeaholicguy/ai-devkit/blob/main/CONTRIBUTING.md) for details. +Open a [GitHub issue or pull request](https://github.com/Codeaholicguy/ai-devkit) to add or improve environment support. diff --git a/web/content/docs/6-memory.md b/web/content/docs/6-memory.md index ba6a963c2..314c4e6e9 100644 --- a/web/content/docs/6-memory.md +++ b/web/content/docs/6-memory.md @@ -20,6 +20,8 @@ Before using Memory, ensure you have: If this is your first AI DevKit command, complete [Getting Started](/docs/1-getting-started) first. With npx only, prefix every CLI example below with `npx ai-devkit@latest`. +If `memory search` fails with a `NODE_MODULE_VERSION` error, the CLI was built with a different Node than your shell uses — see [Node.js and native modules](/docs/1-getting-started#nodejs-and-native-modules). + ## How It Works You can interact with Memory in three ways: diff --git a/web/content/docs/8-agent-management.md b/web/content/docs/8-agent-management.md index b9aa29b62..addb32c69 100644 --- a/web/content/docs/8-agent-management.md +++ b/web/content/docs/8-agent-management.md @@ -10,8 +10,18 @@ The `agent` command allows AI DevKit to detect, list, and interact with other AI For an interactive terminal UI that combines listing, previewing, messaging, starting, renaming, killing, and channel controls, see [Agent Console](/docs/13-agent-console). +For a lead agent supervising Codex, OpenCode, or other workers, read [Multi-agent orchestration](/docs/17-multi-agent-orchestration) and [Troubleshooting: Agents & Orchestration](/docs/18-troubleshooting-agents). + ## Prerequisites +### Linux session detection + +For reliable `agent list`, `agent send --wait`, and session correlation on **Linux**, install **`lsof`** and ensure it is on the `PATH` of the shell and tmux server that runs your agents. Without `lsof`, AI DevKit falls back to `pwdx`; on 0.70.1 that fallback can fail to parse cwd, so sessions never match. + +If `agent list` hangs with `lsof` installed, try lowering the open-file limit for that shell (for example `ulimit -n 1024`). + +### Terminal focus (`agent open`) + To use the `agent open` command, your environment must meet these requirements: - **Operating System**: macOS is currently the primary supported platform for terminal focusing. Linux detection may work, but terminal focus behavior depends on your terminal and desktop environment. @@ -59,9 +69,12 @@ ai-devkit agent start --type claude --name backend --cwd ./packages/backend `--type` accepts `claude`, `codex`, `copilot`, `gemini_cli`, `grok_cli`, `kiro`, `antigravity_cli`, `opencode`, `pi`, `devin`, or `muse`. Names default to the current folder plus a timestamp. Use `--cwd ` to choose a working directory and `--debug` to show startup diagnostics. -The default `--mode interactive` starts the agent in an interactive session. Start output reports the runtime used (for example `Runtime: herdr`). The `durable` mode keeps a named agent available without an interactive terminal: +Interactive managed agents run in **tmux** (or Herdr when configured). Run `ai-devkit setup` to check the host prerequisite early; it reports the installed tmux version or prints a platform-aware install command. tmux 2.6+ is the provisional documented compatibility floor. -Run `ai-devkit setup` to check the host prerequisite early. It reports the installed tmux version or prints a platform-aware install command without installing packages or failing setup. tmux 2.6+ is the provisional documented compatibility floor; older versions are reported, not rejected. +> [!IMPORTANT] +> **Naming and concurrent `agent list`:** On 0.70.1, if `agent list` or `agent console` runs while `agent start` is still waiting for a stable process ID, the registry can record an auto name (`{folder}-{pid}`) and your `--name` is **silently dropped** even though start reports success. While starting a worker, do not poll `agent list`; wait with `tmux has-session -t ` or a short `sleep`, then run the [start-then-assign](/docs/17-multi-agent-orchestration#start-then-assign-sequence-robust-on-0701) handshake. Use one [worktree or directory per agent](/docs/17-multi-agent-orchestration#layout-one-directory-per-agent) so sessions are not mixed. + +The default `--mode interactive` starts the agent in an interactive session. Start output reports the runtime used (for example `Runtime: herdr`). The `durable` mode keeps a named agent available without an interactive terminal: ```bash ai-devkit agent start --type claude --mode durable --name backend --cwd ./packages/backend @@ -69,6 +82,8 @@ ai-devkit agent start --type claude --mode durable --name backend --cwd ./packag Durable mode supports `--type claude`, `--type codex`, and `--type pi`. +`agent start` does not accept an initial prompt or extra harness CLI arguments. To set an opening task or pass flags such as Codex approval policy or Gemini `--approval-mode`, use [Agent Console](/docs/13-agent-console) (**task** and **args** fields) or start the harness manually in tmux. + ### List Agents List all detected running agents. @@ -144,11 +159,16 @@ ai-devkit agent send "continue with the failing tests" --id my-project Useful options: - `--stdin` to read the message from standard input (useful for piping logs or diffs) -- `--wait` to wait for and print the agent's response -- `--group ` to send to every agent in a group -- `-j, --json` for machine-readable output +- `--wait` to wait for and print the agent's response (use with `--id`, not `--group`) +- `--timeout ` with `--wait` — maximum wait time (default **10 minutes**). Examples: `180000`, `3m`, `90s` +- `--group ` to send to every agent in a group (cannot combine with `--wait`, `--timeout`, or `--json`) +- `-j, --json` with `--id --wait` for machine-readable output -If the agent is not currently waiting for input, AI DevKit warns you and still sends the message. +`--id` accepts an agent **name or partial match** (same as fuzzy matching for `agent open`). Prefer exact names from `agent list --json`; partial matches can target the wrong agent when several names share a substring. + +**First message after `start`:** On 0.70.1 and earlier, `send --wait` fails with `No session file found` until the harness has handled a first message. Send a plain message first (for example `ready?`), then use `--wait`. Newer releases wait for the session file when `--wait` is set; the two-step handshake remains useful while TUIs boot. See [Troubleshooting](/docs/18-troubleshooting-agents). + +If the agent is not currently waiting for input, AI DevKit warns you and still sends the message. In scripts, treat that as unsafe: messages can queue or mix, and a following `--wait` may return a reply from an earlier task. Prefer `agent detail` or an explicit handshake before `--wait`. ### Show Agent Details @@ -173,7 +193,7 @@ Stop a running agent by name: ai-devkit agent kill my-project ``` -For managed agents, AI DevKit also cleans up the associated tmux session. +For managed agents, AI DevKit also cleans up the associated tmux session when kill succeeds against the registered process. On 0.70.1, **Codex** may register a child `codex app-server` PID; killing by auto name can fail while the tmux session keeps running. See [Troubleshooting](/docs/18-troubleshooting-agents#codex-shows-name-pid-agent-kill-impl-says-no-agents-found). ### Rename an Agent @@ -205,6 +225,24 @@ Available group commands are: - `agent group list` - `agent group detail ` +## Known limitations + +The following behaviors are known on **0.70.1** (and some persist until a future release). See [Troubleshooting: Agents & Orchestration](/docs/18-troubleshooting-agents) for fixes. + +| Topic | Summary | +|-------|---------| +| `--name` race | Concurrent `agent list` during `agent start` can drop `--name` | +| Codex PID | Registry may track `app-server` child; kill/name quirks | +| Same cwd | Two agents in one directory can swap session views | +| Pi matching | Slow first reply (> ~3 min) may never match | +| Boot-time send | Messages typed before the TUI is ready can be lost | +| Busy send | `send` while not waiting still types; `--wait` can mis-associate | +| Idle Claude `running` | Status can show `running` at an idle prompt | +| `--group` + `--wait` | Not supported; use per-agent `--id --wait` | +| Partial `--id` | Substring match can hit the wrong agent | +| Stale `devkitd` | After upgrade, run `daemon stop` before trusting list output | +| Linux `pwdx` | Without `lsof`, cwd detection can fail on 0.70.1 | + ## Troubleshooting ### "No running agents found"