From 33bd3b87fd069dc2bc4d2ae4662cedd2a6bd5229 Mon Sep 17 00:00:00 2001 From: Hoang Nguyen Date: Sat, 10 Oct 2026 13:13:03 +0000 Subject: [PATCH 1/3] docs: add Runtime & Capacity page for status, capacity, and devkitd Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- web/content/docs/15-runtime-and-capacity.md | 70 +++++++++++++++++++++ 1 file changed, 70 insertions(+) create mode 100644 web/content/docs/15-runtime-and-capacity.md 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 From 75e9d5443695fbb1e326dc8e7a113115ce43077f Mon Sep 17 00:00:00 2001 From: Hoang Nguyen Date: Sat, 10 Oct 2026 13:34:06 +0000 Subject: [PATCH 2/3] docs: split runtime-and-capacity into capacity and runtime pages Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- web/content/docs/15-capacity.md | 38 +++++++++++++++++ ...-runtime-and-capacity.md => 16-runtime.md} | 41 ++++--------------- 2 files changed, 45 insertions(+), 34 deletions(-) create mode 100644 web/content/docs/15-capacity.md rename web/content/docs/{15-runtime-and-capacity.md => 16-runtime.md} (56%) diff --git a/web/content/docs/15-capacity.md b/web/content/docs/15-capacity.md new file mode 100644 index 000000000..227fddfcf --- /dev/null +++ b/web/content/docs/15-capacity.md @@ -0,0 +1,38 @@ +--- +title: Status & Capacity +description: Check setup health with status and monitor provider quota with capacity before starting agents. +slug: capacity +order: 15 +--- + +Two operational commands answer the questions you hit every day: is my setup healthy (`status`), and which agent has quota left (`capacity`). + +## 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. + +Before starting a managed agent, check the provider behind your chosen `--type`: if it reports `available: "no"` or a window near exhaustion, pick another agent type whose provider has headroom — `status` shows which alternatives are healthy on your machine. + +## Next Steps + +- **[Runtime (devkitd)](/docs/16-runtime)**: the daemon that powers agent detection and coordination +- **[Agent Management](/docs/8-agent-management)**: start and supervise agents once you know they have capacity diff --git a/web/content/docs/15-runtime-and-capacity.md b/web/content/docs/16-runtime.md similarity index 56% rename from web/content/docs/15-runtime-and-capacity.md rename to web/content/docs/16-runtime.md index 7cca9781d..41856c389 100644 --- a/web/content/docs/15-runtime-and-capacity.md +++ b/web/content/docs/16-runtime.md @@ -1,44 +1,17 @@ --- -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 +title: Runtime (devkitd) +description: How the devkitd coordination daemon works, how it auto-starts, and the daemon commands for status, logs, and persistence. +slug: runtime +order: 16 --- -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 +## Commands ```bash ai-devkit daemon status # running state, socket, binary path (-j for JSON) @@ -50,7 +23,7 @@ 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`. -### Troubleshooting +## 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. @@ -67,4 +40,4 @@ ai-devkit daemon install # install a systemd --user unit for boot persistence ## 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 +- **[Status & Capacity](/docs/15-capacity)**: operational checks for setup health and provider quota From b4158f7e03b9df80c03f854e67c3f0e8d97ab490 Mon Sep 17 00:00:00 2001 From: Hoang Nguyen Date: Sat, 10 Oct 2026 13:36:43 +0000 Subject: [PATCH 3/3] docs: clarify capacity provider credentials (technical-writer pass) Generated with [Devin](https://devin.ai) Co-Authored-By: Devin <158243242+devin-ai-integration[bot]@users.noreply.github.com> --- web/content/docs/15-capacity.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/web/content/docs/15-capacity.md b/web/content/docs/15-capacity.md index 227fddfcf..d77c4bd93 100644 --- a/web/content/docs/15-capacity.md +++ b/web/content/docs/15-capacity.md @@ -30,6 +30,8 @@ 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. +Capacity reads the credentials each provider's own tool already stores on your machine — no extra setup is needed. A provider you have not logged into reports as unauthenticated instead of showing quota. + Before starting a managed agent, check the provider behind your chosen `--type`: if it reports `available: "no"` or a window near exhaustion, pick another agent type whose provider has headroom — `status` shows which alternatives are healthy on your machine. ## Next Steps