From 36799251e28f84b5ca808f90381d9aa89c86bffa Mon Sep 17 00:00:00 2001 From: Hoang Nguyen Date: Sat, 10 Oct 2026 12:42:17 +0000 Subject: [PATCH] docs: refresh docs to 0.69.1 reality - Fix duplicated prerequisites block and extend setup description (memory MCP wiring, --agent flag) in getting-started; add status to first-run checks - Overview: add status/capacity/daemon under a new "Observe And Operate" capability - supported-agents: refresh example version, fix env.ts path - memory: setup-first MCP wiring with capable-agents table, add semantic/reembed/--explain commands - skills: add session-compact to built-ins, note remote manifest - agent-management: 10 --type values, durable claude/codex/pi, grok/kiro/antigravity/devin detection, herdr runtime, send --wait/--stdin/--json, agent session compact - channel: generalize agent prerequisite to any detected harness - console: rewrite start-agent pane for the 0.68 UX (vertical type list, mode/task/args fields, Ctrl+R recents, elapsed cancel) - New page: Runtime & Capacity (status, capacity, devkitd daemon, upgrade notes) Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- web/content/docs/0-what-is-ai-devkit.md | 12 +++- web/content/docs/1-getting-started.md | 24 ++++--- web/content/docs/12-channel.md | 2 +- web/content/docs/13-agent-console.md | 10 ++- web/content/docs/15-runtime-and-capacity.md | 70 +++++++++++++++++++++ web/content/docs/2-supported-agents.md | 8 +-- web/content/docs/6-memory.md | 29 +++++++-- web/content/docs/7-skills.md | 5 +- web/content/docs/8-agent-management.md | 30 +++++++-- 9 files changed, 166 insertions(+), 24 deletions(-) create mode 100644 web/content/docs/15-runtime-and-capacity.md diff --git a/web/content/docs/0-what-is-ai-devkit.md b/web/content/docs/0-what-is-ai-devkit.md index bde9cce9f..0ef209572 100644 --- a/web/content/docs/0-what-is-ai-devkit.md +++ b/web/content/docs/0-what-is-ai-devkit.md @@ -80,6 +80,16 @@ The [Memory](/docs/6-memory) service gives your coding agents persistent, local 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. +### Observe And Operate + +AI DevKit ships with a local coordination daemon (`devkitd`) that runs agent detection and session routing, plus operational commands for day-to-day checks: + +- `ai-devkit status` reports readiness for your whole setup — CLI version, per-agent health, tmux, registries, channels, and memory MCP wiring +- `ai-devkit capacity` shows remaining quota across your logged-in providers (Codex, z.ai, OpenAI, Anthropic, Claude, Devin) so you can pick the agent with the most headroom +- `ai-devkit daemon` manages the background daemon; it auto-starts on first use, so no manual step is needed + +See [Runtime & Capacity](/docs/15-runtime-and-capacity) for details. + ## A Typical Workflow Here's what working with AI DevKit looks like in practice: @@ -98,7 +108,7 @@ Project initialization and lifecycle work produce documentation in `docs/ai/`, g 1. **Connect** - Run `npx ai-devkit@latest setup` once per machine to connect detected agents and install their global workflow skills. 2. **Initialize** - Run `npx ai-devkit@latest init` once per project to create workflow docs and environment-specific project configuration. -3. **Operate** - Use `agent list`, `agent console`, and `agent send` to supervise and route work across running local agents. +3. **Operate** - Use `agent list`, `agent console`, and `agent send` to supervise and route work across running local agents; use `status` and `capacity` to check readiness and provider quota. 4. **Develop** - Ask the agent to use installed workflow skills such as `dev-lifecycle`, `tdd`, and `verify` so it follows the workflow instead of improvising in chat. 5. **Remember** - Store important decisions and patterns in memory so they persist across sessions. 6. **Extend** - Install skills to give your AI specialized knowledge for your stack and domain. diff --git a/web/content/docs/1-getting-started.md b/web/content/docs/1-getting-started.md index eb2401380..c3f98357f 100644 --- a/web/content/docs/1-getting-started.md +++ b/web/content/docs/1-getting-started.md @@ -8,7 +8,7 @@ order: 1 Getting started has two scopes: -1. **Once per machine:** run `setup` to connect detected local agents, install their session integrations, and install AI DevKit's built-in skills globally. +1. **Once per machine:** run `setup` to connect detected local agents, install their session integrations and built-in skills globally, and wire the AI DevKit memory MCP server into MCP-capable agents. 2. **Once per project:** run `init` to create `.ai-devkit.json`, environment-specific project files, and workflow documentation. Keeping these steps separate makes it clear which changes affect your machine and which files belong in your project. @@ -22,10 +22,6 @@ Before you begin, make sure you have: - **tmux** for interactive managed agents (provisional compatibility floor: tmux 2.6+; setup reports but does not reject older versions) - At least one [supported AI coding agent or environment](/docs/2-supported-agents) -- **Node.js 20.20.0 or newer** -- **npm** or **npx**, which comes with Node.js -- At least one [supported AI coding agent or environment](/docs/2-supported-agents) - 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 @@ -69,7 +65,15 @@ An npx-only installation does not make a permanent `ai-devkit` command available ### Machine setup -`setup` checks for supported agent home directories. For each detected agent, it installs the available session hook or tracker and the AI DevKit built-in skills in that agent's global skill location. +`setup` checks for supported agent home directories. For each detected agent, it installs the available session hook or tracker, installs the AI DevKit built-in skills in that agent's global skill location, and wires the `ai-devkit-memory` MCP server into agents with a user-level MCP config (see [Memory](/docs/6-memory)). + +To set up only specific agents, pass a comma-separated list: + +```bash +ai-devkit setup --agent claude,codex +``` + +Supported values: `codex`, `pi`, `claude`, `gemini`, `cursor`, `opencode`, `grok`. Read the setup summary carefully. A skipped agent was not changed. If an agent you use is skipped, launch it once and rerun the same setup command. @@ -91,7 +95,13 @@ If the directory is not already a Git repository and Git is available, `init` al ## Verify the First Run -Restart your coding agent after machine setup, then start an agent session in the initialized project. Check discovery before opening the console: +Restart your coding agent after machine setup, then start an agent session in the initialized project. First check overall readiness: + +```bash +ai-devkit status +``` + +`status` reports the CLI version, project config, per-agent readiness (executable, auth, skills), tmux, skill registries, channels, and memory MCP wiring — see [Runtime & Capacity](/docs/15-runtime-and-capacity). Then check discovery before opening the console: ```bash ai-devkit agent list diff --git a/web/content/docs/12-channel.md b/web/content/docs/12-channel.md index 0d27d7bc8..029e0fabe 100644 --- a/web/content/docs/12-channel.md +++ b/web/content/docs/12-channel.md @@ -13,7 +13,7 @@ The `channel` command lets you bridge a running AI agent to Telegram or Slack. O ## Prerequisites - **AI DevKit** installed globally (see [Getting Started](/docs/1-getting-started)) -- **A running AI agent** (Claude Code or Codex) detected by AI DevKit (see [Agent Management](/docs/8-agent-management)) +- **A running AI agent** of any detected harness type — Claude Code, Codex, Gemini CLI, Copilot, opencode, Pi, Grok CLI, Kiro, Antigravity CLI, or Devin — listed by `ai-devkit agent list` (see [Agent Management](/docs/8-agent-management)) - **Telegram:** a bot token from [@BotFather](https://t.me/BotFather), or - **Slack:** a custom single-workspace app with Socket Mode, an `xapp-` app token, and an `xoxb-` bot token - **Terminal environment**: The agent must be running in **tmux**, **WezTerm**, **Ghostty**, **iTerm2**, or **Apple Terminal** (same requirements as `agent open`) diff --git a/web/content/docs/13-agent-console.md b/web/content/docs/13-agent-console.md index b0bc2ca9a..8c67672dd 100644 --- a/web/content/docs/13-agent-console.md +++ b/web/content/docs/13-agent-console.md @@ -87,7 +87,13 @@ If the agent is not waiting for input, AI DevKit may still send the message, but ### Start a Managed Agent -Press `s` to open the start-agent pane. Use `Left`/`Right` or `h`/`l` to choose the agent type, `Tab` or `Down` to move between fields, `Up` to move back, `Enter` to advance or submit, and `Esc` to cancel. +Press `s` to open the start-agent pane. Fields are visited in order: **type**, **mode**, **cwd**, **name**, **task**, **args**, then **submit**/**cancel**: + +- In the **type** field, move through the vertical list with `Up`/`Down` or `j`/`k`; types whose harness is unavailable are marked so you can pick a working one. +- In the **mode** field, use `Left`/`Right` or `h`/`l` to switch between `interactive` and `durable` (durable is limited to claude, codex, and pi). +- **cwd** accepts `~` expansion; press `Ctrl+R` in that field to cycle recently used project directories. **task** sets an initial prompt and **args** passes extra harness CLI arguments. +- `Tab` or `Down` moves to the next field; `Shift+Tab` or `Up` moves back. `Enter` advances through fields and submits from the name field; `Esc` cancels. +- While a start is pending, the pane shows elapsed time and lets you cancel. The pane remembers your last type and cwd. Supported start types: @@ -104,7 +110,7 @@ Supported start types: | `kiro` | Kiro CLI | | `devin` | Devin | -Starting an agent from the console uses a managed tmux session. If tmux is not installed or the selected agent command is not in `PATH`, the console shows an error. +Starting an agent from the console uses the configured managed runtime (tmux by default, or Herdr when configured). If tmux is not installed or the selected agent command is not in `PATH`, the console warns you in the start pane. ### Rename an Agent diff --git a/web/content/docs/15-runtime-and-capacity.md b/web/content/docs/15-runtime-and-capacity.md new file mode 100644 index 000000000..7cca9781d --- /dev/null +++ b/web/content/docs/15-runtime-and-capacity.md @@ -0,0 +1,70 @@ +--- +title: Runtime & Capacity +description: Check setup health with status, monitor provider quota with capacity, and manage the devkitd coordination daemon. +slug: runtime-and-capacity +order: 15 +--- + +AI DevKit runs a local coordination daemon (`devkitd`) underneath the `agent` commands, and ships two operational commands — `status` and `capacity` — for checking setup health and provider quota before you start work. + +## Status + +`ai-devkit status` prints a readiness report for your whole setup: + +```bash +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. + +## Capacity + +`ai-devkit capacity` shows remaining quota across your logged-in providers so you can pick the agent type with the most headroom: + +```bash +ai-devkit capacity +ai-devkit capacity codex claude +ai-devkit capacity --json +``` + +Supported providers: `codex`, `zai` (or `z.ai`), `openai`, `anthropic`, `claude`, `devin`. With no arguments, all providers are queried; pass provider names to check a subset. Output is a per-quota table with usage bars and humanized reset times; `--json` gives the raw report for scripting. + +## The devkitd Daemon + +Agent detection and session coordination run through `devkitd`, a small daemon written in Rust. You normally never manage it: any AI DevKit command that needs it auto-spawns it and connects over a Unix socket. + +- **Socket:** `~/.ai-devkit/daemon.sock` +- **Log:** `~/.ai-devkit/daemon.log` +- **Binary:** resolved from the `DEVKITD_BIN` environment variable, the per-platform binary package that ships with the release, or a local cargo build. + +### Commands + +```bash +ai-devkit daemon status # running state, socket, binary path (-j for JSON) +ai-devkit daemon start # ensure it is running (auto-spawned anyway on use) +ai-devkit daemon stop # stop the daemon +ai-devkit daemon logs # tail the daemon log (-n , default 50) +ai-devkit daemon install # install a systemd --user unit for boot persistence (Linux) +``` + +`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`. + +### 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. + +## 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. + +## Next Steps + +- **[Agent Management](/docs/8-agent-management)**: the commands that run on top of the daemon +- **[Getting Started](/docs/1-getting-started)**: machine setup and first-run checks diff --git a/web/content/docs/2-supported-agents.md b/web/content/docs/2-supported-agents.md index 19fffd8d5..00f401902 100644 --- a/web/content/docs/2-supported-agents.md +++ b/web/content/docs/2-supported-agents.md @@ -150,11 +150,11 @@ Your selections are saved in `.ai-devkit.json`: ```json { - "version": "0.21.1", + "version": "0.69.1", "environments": ["cursor", "claude", "github"], "phases": ["requirements", "design"], - "createdAt": "2026-04-04T...", - "updatedAt": "2026-04-04T..." + "createdAt": "2026-10-10T...", + "updatedAt": "2026-10-10T..." } ``` @@ -192,7 +192,7 @@ Existing phase documents use a separate per-phase confirmation. This behavior be Want to add support for a new AI environment? We welcome contributions! -1. **Create Environment Definition** — Add to `src/util/env.ts` +1. **Create Environment Definition** — Add to `packages/cli/src/util/env.ts` 2. **Add Templates** — Create `templates/env/{code}/` directory 3. **Update Documentation** — Add to this guide 4. **Test Integration** — Ensure proper initialization and configuration diff --git a/web/content/docs/6-memory.md b/web/content/docs/6-memory.md index d198d6b17..105c1cb0c 100644 --- a/web/content/docs/6-memory.md +++ b/web/content/docs/6-memory.md @@ -33,14 +33,23 @@ This is the most powerful way to use Memory. Your AI (Cursor, Claude, etc.) gain ### Setup -Add the server to your MCP configuration file: +Run `ai-devkit setup` once per machine. It wires the memory MCP server — named `ai-devkit-memory`, launched with `npx -y @ai-devkit/memory` — into the global config of every MCP-capable agent it detects: + +| Agent | MCP wiring | +|-------|-----------| +| Claude Code, Codex, Gemini, Cursor, opencode, Grok | Automatic via `setup` | +| Pi | No MCP support by design — use the `memory` skill or `ai-devkit memory` CLI instead | + +`ai-devkit status` reports the wiring state per agent, so you can confirm the server is connected before relying on it. + +If an agent's config is managed manually, you can still add the server yourself: ```json { "mcpServers": { - "memory": { + "ai-devkit-memory": { "command": "npx", - "args": ["@ai-devkit/memory"] + "args": ["-y", "@ai-devkit/memory"] } } } @@ -117,10 +126,11 @@ ai-devkit memory search --query "docker m1" Useful options: -- `--limit ` to control how many results are returned +- `--limit ` to control how many results are returned (1–20, default 5) - `--scope ` to filter results to one scope - `--tags ` to boost matches using context tags - `--table` to print a compact table with `id`, `title`, and `scope` +- `--explain` to include the lexical and semantic rank details behind each result > **Note:** If no results are found, the `results` array is empty. @@ -144,6 +154,17 @@ ai-devkit memory update \ --scope "global" ``` +### Semantic Search + +Memory search is hybrid: lexical matching plus local semantic embeddings. Manage the embedding model and index with: + +```bash +ai-devkit memory semantic status # model and embedding index state +ai-devkit memory semantic download # download the embedding model (also for offline use) +ai-devkit memory reembed # recompute stale embeddings +ai-devkit memory reembed --force # recompute all embeddings +``` + ## Using the Memory Skill If MCP is not available in your environment, you can install the **memory skill** to teach your AI agent how to use memory via CLI commands. diff --git a/web/content/docs/7-skills.md b/web/content/docs/7-skills.md index 251ea887b..ed427c574 100644 --- a/web/content/docs/7-skills.md +++ b/web/content/docs/7-skills.md @@ -50,10 +50,13 @@ AI DevKit ships with a core set of skills in its default registry: | `brainstorm` | Explore, compare, and refine product or technical ideas | | `tdd` | Apply test-driven development by writing a failing test before production code | | `verify` | Require fresh terminal evidence before claiming work is complete | +| `session-compact` | Compact a historical agent session into durable continuation facts and memory candidates | You can install these skills the same way you install community skills. -The repository also contains skills such as `agent-orchestration`, `technical-writer`, and `security-review`. They can be installed individually from the AI DevKit registry, but they are not part of the curated set installed by `ai-devkit skill add --built-in`. +The built-in set is served from a remote manifest, so new built-in skills can ship without a CLI release; an embedded copy is used as an offline fallback. + +The repository also contains skills such as `agent-orchestration`, `technical-writer`, `security-review`, `changelog`, and `refactor`. They can be installed individually from the AI DevKit registry, but they are not part of the curated set installed by `ai-devkit skill add --built-in`. For more detail on the core workflow skills, see the built-in skill pages for [`dev-lifecycle`](/skills/dev-lifecycle), [`structured-debug`](/skills/structured-debug), [`tdd`](/skills/tdd), [`verify`](/skills/verify), and [`security-review`](/skills/security-review). diff --git a/web/content/docs/8-agent-management.md b/web/content/docs/8-agent-management.md index bf5733906..2e55b832f 100644 --- a/web/content/docs/8-agent-management.md +++ b/web/content/docs/8-agent-management.md @@ -43,20 +43,24 @@ AI DevKit detects active sessions from the following tools: ``` The tracker gives AI DevKit better session information than process detection alone. +- **[Grok CLI](https://x.ai/cli)**: Detects running `grok` sessions and exposes them through the same agent management commands. +- **[Kiro CLI](https://kiro.dev/)**: Detects Kiro CLI sessions via `~/.kiro/sessions/cli` and exposes them through the same commands. +- **[Antigravity CLI](https://antigravity.google/)**: Detects `agy` sessions and exposes them through the same commands. +- **[Devin](https://devin.ai/)**: Detects Devin CLI sessions and exposes them through the same commands. ## Commands ### Start an Agent -Start a named agent in a managed tmux session: +Start a named agent in a managed runtime session (tmux by default; the Herdr runtime is used when configured): ```bash ai-devkit agent start --type claude --name backend --cwd ./packages/backend ``` -`--type` accepts `claude`, `codex`, `copilot`, `gemini_cli`, `grok_cli`, `kiro`, `opencode`, or `pi`. Names default to the current folder plus a timestamp. Use `--cwd ` to choose a working directory and `--debug` to show startup diagnostics. +`--type` accepts `claude`, `codex`, `copilot`, `gemini_cli`, `grok_cli`, `kiro`, `antigravity_cli`, `opencode`, `pi`, or `devin`. 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 tmux. Claude also supports a durable mode that keeps a named agent available without an interactive terminal: +The default `--mode interactive` starts the agent in an interactive session. The `durable` mode keeps a named agent available without an interactive terminal: 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. @@ -64,7 +68,7 @@ Run `ai-devkit setup` to check the host prerequisite early. It reports the insta ai-devkit agent start --type claude --mode durable --name backend --cwd ./packages/backend ``` -Durable mode currently supports only `--type claude`. +Durable mode supports `--type claude`, `--type codex`, and `--type pi`. ### List Agents @@ -105,6 +109,17 @@ ai-devkit agent session detail --tail 50 --verbose The detail command supports `--type`, `--tail `, `--full`, `--verbose`, and `--json`. +### Compact a Session + +Distill a historical session into a durable continuation artifact — structured facts plus memory candidates — that you can hand to a successor agent or store for later: + +```bash +ai-devkit agent session compact --id +ai-devkit agent session compact --id --format json +``` + +Compaction is classified by Jev and requires the `TYPESAFE_API_KEY` environment variable. Use `--format markdown` (default) for a readable summary or `--format json` to splice the artifact into another agent's instructions. The built-in [`session-compact`](/docs/7-skills) skill teaches agents to run this workflow themselves at handoff points. + ### Open Agent Focus the terminal window associated with a specific agent. @@ -127,6 +142,13 @@ Send a message directly to a running agent. 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 + If the agent is not currently waiting for input, AI DevKit warns you and still sends the message. ### Show Agent Details