# Changelog (/docs/changelog) The highlights of each release, newest first, grouped by patch release. Every detail, including the upgrade steps a release carries, is in the plugin's [CHANGELOG.md](https://github.com/AgentLayer1/agentlayer-agent/blob/main/CHANGELOG.md). After a plugin update, run `upgrade` to bring your home current ([Updating](/docs/run/updating)). ## 1.0 · Nov 15 – 21, 2026 [#10--nov-15--21-2026] ### 1.0.9 · Nov 21 [#v1-0-9] * **The heartbeat shows what it's doing.** A band above its prompt says whether it is looking or refreshing, counts down to the next look, and lists its last few looks and skips with a mark for each. [What the heartbeat shows](/docs/use/proposals#what-the-heartbeat-shows) * **The best five, not just five.** The heartbeat looks even when five proposals show, swaps out the ones a stronger candidate beats or that no longer hold, and leaves out work a session already has. [When it looks](/docs/use/proposals#when-it-looks) * **The brain stays fresh between syncs.** Every six hours, when something new has happened, the heartbeat runs a brain refresh: sync's maintenance with none of its questions, so your own sync is quicker. [Brain refresh](/docs/use/sync#brain-refresh) * **Sessions open where the work lives.** Discuss and a proposal's Start open in the agent's workspace that fits the work, focused, never in another agent's. [cmux](/docs/workstation/cmux#opening-a-session) * **Closing the heartbeat's tab gives the heartbeat up,** so the next `/heartbeat` no longer reports taking over from a session that's gone. [Start a heartbeat](/docs/use/proposals#start-a-heartbeat) * **A file shows as a path you Cmd-click** to open in your default app, instead of a command to paste. [Upgrade notes](/docs/reference/upgrades#file-paths-in-109) ### 1.0.8 · Nov 21 [#v1-0-8] * **The heartbeat follows your home, not the clock.** It wakes while the home's other sessions are active, at any hour, and stays still while nothing else runs there. [When it looks](/docs/use/proposals#when-it-looks) · [Upgrade notes](/docs/reference/upgrades#heartbeat-in-108) * **`/heartbeat` looks at once, whatever the hour**, then waits a full interval, and says whether it looked. `/heartbeat status` says when another session was last active. [Start a heartbeat](/docs/use/proposals#start-a-heartbeat) * **PROPOSED waits until you open it.** The cmux Manager's section starts folded, no card opens on its own, and each closed card says why it's there. [cmux](/docs/workstation/cmux#proposed) ### 1.0.7 · Nov 20 [#v1-0-7] * **The setup guide runs the release it names.** The one-line installer downloads its steps from the latest release, never from work on the plugin's `main` that isn't released yet. [Quickstart](/docs/getting-started/quickstart) ### 1.0.6 · Nov 20 [#v1-0-6] * **Proposals: the agent lines up sessions worth starting.** Each one waits for you: Start opens a fresh session that runs it, Later brings it back in the morning, Skip drops it. One long-running session, the heartbeat, keeps up to five coming on its own clock and stays quiet at night. [Proposals](/docs/use/proposals) · [Upgrade notes](/docs/reference/upgrades#proposals-in-106) * **Proposals in the cmux Manager.** A PROPOSED section above Needs you holds every agent's proposals, with Start, Later and Skip on each card, and a card that starts a heartbeat for an agent without one. [cmux](/docs/workstation/cmux#proposed) * **Talk a task or goal through** with the Discuss icon on every task and goal in the cmux sidebar: a short brief, a conversation, then a choice of next move, with nothing built first. [cmux](/docs/workstation/cmux#discuss) * **The board has a one-line summary** of what the open work is about, written by sync and the heartbeat, shown above Tasks in the sidebar and at the top of the dashboard's Attention tab. [Tasks](/docs/use/tasks#the-summary) * **A plugin or your home can add what the heartbeat looks at** with a proposal source skill. [Proposal sources](/docs/use/proposals#proposal-sources) ### 1.0.5 · Nov 19 [#v1-0-5] * **Dashboard links open the file itself** in a new tab, unless you set `MARKDOWN_URL` to route them through an app such as MarkEdit or Obsidian. A home without Obsidian no longer gets links to an app it doesn't have. [Opening links](/docs/dashboard#opening-links) · [Upgrade notes](/docs/reference/upgrades#file-links-in-105) * **The agent shows you a file with `open`**, so your system's default app opens it, never an app you didn't name. * **The installer checks for Node.js** on macOS, Linux and Windows, and points you at fnm when it's missing. [Install](/docs/getting-started/install#prerequisites) * **The Mac guide sets up your editors:** it recommends MarkEdit for the agent's notes and checks that CotEditor opens `.txt` and `.json` and MarkEdit opens `.md`. [Install](/docs/getting-started/install#prerequisites) * **The demo dashboard's week starts on its own Monday.** ### 1.0.4 · Nov 19 [#v1-0-4] * **Put the cmux sidebar's agents in your order** with `cmux sidebar order`, by agent name or home folder. The order holds through every home's refresh, and a new agent joins at the end. [cmux](/docs/workstation/cmux#sidebar-commands) * **"Refresh my sidebar"** refreshes the cmux sidebar alone and says how it went: written, already up to date, not installed, or this home not in it yet. [cmux](/docs/workstation/cmux#how-it-stays-current) * **Reports sit under the day they were last updated**, on the dashboard and in the sidebar, so a report edited after the day it was filed moves up. [Reports](/docs/dashboard/reports-and-scheduler) * **Three short agent names fit on one line** in the sidebar's header. ### 1.0.3 · Nov 18 [#v1-0-3] * **A guided installer for macOS, Linux and Windows.** One line in your terminal starts a guide that checks the machine, shows each step with the vendor's page or the exact command, waits while you run it, and ticks it off. It never installs anything itself, and `--prereqs` prepares a machine without setting up an agent. [Quickstart](/docs/getting-started/quickstart) * **Every agent has its own colors**, a primary and an accent picked at setup from four pairs, drawn in the session banner, the dashboard and the cmux sidebar. Oppi keeps orchid and mint. [Naming](/docs/run/naming) * **Change how a plugin skill works in your home** with `extensions/skills/.md`. The skill reads it before it runs, and it wins where the two disagree. Helpdesk's rules for every queue now live there. [Extending a plugin skill](/docs/reference/skills#skill-extensions) * **Pages stay files in your home.** Claude Code's Artifact tool is off, so pages, plans and proposals are written into the home and open from disk instead of being published to claude.ai. `upgrade` turns it off in your home. [Artifacts off](/docs/run/claude-code#artifacts) * **Codex homes default to `gpt-6.2-sol`**, and `upgrade` moves a home still on `gpt-6.1-sol`. [Codex](/docs/run/codex) · [Upgrade notes](/docs/reference/upgrades#codex-sol-and-artifacts-in-103) * **A skill of your own can file reports under its own folder**, and the dashboard lists them after the plugin's. An `.html` report is written as it is. [MCP tools](/docs/reference/mcp-tools) * **The morning brief flags a red CI run** on your code repo's default branch. [Daily rhythm](/docs/use/daily-rhythm) * **A browser flow can carry its own Chromium flags**, such as a fake camera for one site. [Browser](/docs/packs/browser#flows) * **An agent on its own Claude subscription is pointed at `agent`**: the installer's last line starts it with `agent`, and the cmux settings check recommends `agent` for the Claude Code button. [Billing per agent](/docs/run/billing) * **Pack pickers show every pack as its own option**, over three questions, instead of merging packs to fit. ### 1.0.2 · Nov 17 [#v1-0-2] * **The AgentLayer sidebar for cmux.** One panel in cmux's right sidebar that every agent home on the Mac joins: **Manager** lists every agent session by what needs you, and **Agents** shows each agent's projects, reports and goals, with its dashboard and roadmap a tap away. Switch it on with `configure-skills`. [cmux](/docs/workstation/cmux#the-agentlayer-sidebar) * **One reading of your projects and tasks** feeds the dashboard, `TASKS.md` and the sidebar, with one task order (priority, then due date, then the newest change) and one set of due-date words. * **A report's status reads as a word** (clean, findings, critical, draft) in a coloured badge. [Reports](/docs/dashboard/reports-and-scheduler) * **The agent rows under the prompt are drawn by a mod**, since Claude Code 2.1.323 removed the setting that drew them: each subagent's type, description and a context bar. [Mods](/docs/reference/mods#agent-rows) * **Setup offers the Helpdesk, App Store and cmux packs** with the others. * **Outside Obsidian, the dashboard opens HTML pages as pages** in a new tab. ### 1.0.1 · Nov 16 [#v1-0-1] * **A hardening release**: fixes from a full review of the plugin and a second model's review, including tool paths that could write outside the home or hand out its secrets, and five ways a task file could lose data. * **A moved home checks the move before finishing it**: its first session reads the change list the move saved, flags renames that meant someone else, and puts back the ones you pick. [Moving from agent-kevin](/docs/reference/upgrades#moving-from-agent-kevin) * **`curl_run` accepts a listed set of request flags and one URL per call**, and every outbound request has a deadline. [API collections](/docs/engineering/api-collections) * **Codex wiring is named `agentlayer`**, so it no longer shares the bare `agent` name with your own Codex config. A home wired for Codex on 1.0.0 has one step to do by hand. [Upgrade notes](/docs/reference/upgrades#codex-names-in-101) * **`upgrade` flags a home missing from the auto-mode "Agent homes:" entry**, and a Codex-wired home whose Codex has no `agentlayer` plugin. * **A new home that keeps the name Oppi gets its nickname, Ops.** [Naming](/docs/run/naming) ### 1.0.0 · Nov 15 [#v1-0-0] * **The plugin is `agentlayer`, and Oppi 🐙 is the agent a new home wakes up with.** Commands are `/agentlayer:` in Claude Code (`$` in Codex, as before), and tools are `mcp__plugin_agentlayer_agent__`. A home on agent-kevin moves here with `/agent-kevin:move`, which copies it to a new folder. [Moving from agent-kevin](/docs/reference/upgrades#moving-from-agent-kevin) * **A moved home's first session finishes the move.** It says where the home came from and notes it in memory, runs `upgrade` and a sync, checks the move's renamed lines with you, and offers the sessions you picked to continue. [Moving from agent-kevin](/docs/reference/upgrades#moving-from-agent-kevin) * **`find-session` searches the brain's session logs too**, so it can load a session Claude Code can't resume from this folder, such as one from before the move. [Skills](/docs/reference/skills) * **The CLI is `src/cli.ts`, run with `bun`.** The plugin's package lives at its root, there is no `bin/` folder, and nothing goes on your PATH. [CLI](/docs/reference/cli) * **SOUL gains a core truth, "Many arms, one brain."** `upgrade` offers it with a diff. [Upgrade notes](/docs/reference/upgrades#agentlayer-in-100) ## Before 1.0: agent-kevin [#before-1-0-agent-kevin] These releases shipped under the plugin's old name, agent-kevin. Their full detail, through 0.9.4, is in its [CHANGELOG at v0.9.4](https://github.com/AgentLayer1/agentlayer-agent/blob/v0.9.4/CHANGELOG.md). A home still on agent-kevin moves to agentlayer with `/agent-kevin:move` ([Moving from agent-kevin](/docs/reference/upgrades#moving-from-agent-kevin)). ## 0.9 · Oct 30 – Nov 15, 2026 [#09--oct-30--nov-15-2026] ### 0.9.5 · Nov 15 [#v0-9-5] * **`/agent-kevin:move` moves your homes to agentlayer, the plugin that replaces this one.** It finds every agent-kevin home on the machine, asks each one's new name and folder, previews the move, reviews the renamed lines that really mean someone else, and lets you pick the sessions the new home offers first. Nothing moves until you run the command it hands you. [Moving from agent-kevin](/docs/reference/upgrades#moving-from-agent-kevin) * **The move copies a home and changes only the copy.** The old home is only read, apart from a mark that says where it went: its sessions then open with the new folder, and its sync stops at its first commit. Deleting `movedTo` from its `.state/version.json` undoes it. * **Sync and the banner offer the move** until the home has moved. ### 0.9.4 · Nov 13 [#v0-9-4] * **An agent only reads git stash.** The stash is shared by every worktree and session on a repo, so the guard now refuses every `git stash` except `list` and `show`, on Claude Code and Codex. Your own terminal is not affected. [Hooks](/docs/reference/hooks) * **The GitHub sweep opens with My promises folded**, like the other reference sections. [Everything waiting on you](/docs/engineering/pull-requests#everything-waiting-on-you) ### 0.9.3 · Nov 9 [#v0-9-3] * **The shell guard refuses any `cd` that moves the session**, not only one out of the home: a folder inside the home or a computed target like `cd "$DIR"` too, and the refusal hands back the same command in a subshell, ready to run. [Hooks](/docs/reference/hooks) * **The guard refuses git that rewrites or hides history**: `commit --amend`, a merge with the `ours` strategy, and `stash --keep-index`, on Claude Code and Codex. [Hooks](/docs/reference/hooks) * **The guard refuses a commit its check can't stop**: a commit, merge or push after a test, lint, typecheck, build or format step must be joined to it with `&&`, and a piped check needs `set -o pipefail` first. [Hooks](/docs/reference/hooks) * **The manual is stricter about evidence and shell commands**: a safety verdict names what would break it, a claim carried in from a plan or report is re-read at its source, and a pass needs a positive count of what it proves. `upgrade` brings it into your home. [Upgrades](/docs/reference/upgrades#a-stricter-manual-in-093) * **Sync's self-review question names both halves**, so a brain review you ran the night before no longer reads as skipped. ### 0.9.2 · Nov 8 [#v0-9-2] * **Cancelling a tool call stops what it started**: worktree setup's install and build, `run_upgrade`'s install, the media tools, browser flows, and `gh` and `git`. [MCP tools](/docs/reference/mcp-tools#cancelling-a-call) * **A browser flow has a 15-minute cap**, the 5-minute login wait plus the run, and a cancelled or hung flow stops with its browser. [Browser](/docs/packs/browser#flows) * **Idle compaction is off in every home**, so a session you stepped away from no longer comes back as a summary. Auto-compact when the context fills still runs. [Idle compaction](/docs/run/claude-code#idle-compaction) * **API collections write sturdier tests**: they check a response's shape, not exact ids or timestamps, and a request that writes data says how to undo it. With `bru` installed, a collection can start from an OpenAPI spec, and you get a one-line `bru run` to paste. [API collections](/docs/engineering/api-collections) * **The GitHub sweep drafts your stale PR descriptions**: a new title and body to paste for each of your PRs the branch has outgrown, and for a pushed branch that should become a PR. [Everything waiting on you](/docs/engineering/pull-requests#everything-waiting-on-you) * **Walkthroughs light the path each step travels**, and a reset button starts them over. [Explainers](/docs/engineering/engineer#explainers) * **Interrogate reviews your branch the way a PR review would, before there's a PR**: the same lanes, local checks and verifiers, with verified defects fixed uncommitted and a PR description drafted in chat. "Simplify and interrogate this branch" cleans it up first. [Interrogate](/docs/engineering/design-and-review#interrogate) ### 0.9.1 · Nov 2 [#v0-9-1] * **`/task` replaces `/done`.** `/task ` shows a task as a card above the prompt (status, priority, due date, the description's opening, checklist progress, a Done button), `/task done` closes it and `/task cancel` cancels it. In the terminal, task ids in a reply open their file on a click. A schedule or script that runs `/done` needs `/task done`. [Mods](/docs/reference/mods) * **Bun 1.4.4 or newer is required.** Setup and `upgrade` stop below it with `bun upgrade`. With it the browser tools drop their old workarounds, and `browser_record` works on Windows; `upgrade` runs `bun install`, which downloads Chromium again. [Install by hand](/docs/getting-started/install) * **Setup and `upgrade` install the plugin's packages themselves.** On a fresh install, `init` runs the package install and carries on, so the relaunch it ends with is the only restart. `upgrade` installs into the version you just pulled and records the new version only once that succeeds, so a home no longer shows "upgrade ready" after an upgrade that ran. [Updating](/docs/run/updating) * **The Xcode pack moves to Xcode 27.2 and reads Apple's own skills** (SwiftUI, App Intents, accessibility, Instruments' `xctrace` and more), exported once per Xcode build with one command you run. [Coding rules](/docs/engineering/coding-rules#the-xcode-pack) * **Windows line endings no longer break a home.** Setup, `upgrade` and the dashboard read files with Windows line endings correctly, and files the agent edits come back with one kind of line ending. New checkouts of the plugin stay LF. [Platforms](/docs/about/platforms) * **Closing a task twice keeps the date it was first closed**, and report ids like `745` stay text in Obsidian. ### 0.9.0 · Oct 30 [#v0-9-0] * **An agent on its own Claude subscription now starts with `agent`.** Claude Code 2.1.312 stopped reading the subscription token from an agent's `settings.local.json`, so those agents were quietly billing your default login. The token now lives in the agent's secrets folder, and a small `agent` command you add to your terminal once starts Claude Code with it. `upgrade` moves the token and offers to add the command. [Billing per agent](/docs/run/billing) * **The session banner warns when an agent with its own subscription was started with `claude`**, so a session never bills the wrong account without you noticing. * **Claude Code 2.1.314 or newer is required.** Setup and `upgrade` stop below it with `claude update`. * **The shell guard checks the Monitor tool's commands too**, in Claude Code: its scratch-file and home-folder checks cover them, and a Monitor command that `cd`s out of the home is refused like a Bash one. [Claude Code](/docs/run/claude-code#hooks) * **A seed bundle that holds a symlink is refused by name again**, as "payload is not a regular file", before anything is extracted. [Seed bundles](/docs/run/seed-bundles) * **`run_upgrade` passes your choices to a migration**, so an upgrade step can ask first and then act. [MCP tools](/docs/reference/mcp-tools#notes-on-a-few) * **The GitHub sweep tracks your own promises**: the commitments you made in replies over the last 30 days, each checked where it was made and marked open, done, superseded or wrong. [Everything waiting on you](/docs/engineering/pull-requests#everything-waiting-on-you) ## 0.8 · Oct 15 – 29, 2026 [#08--oct-15--29-2026] ### 0.8.11 · Oct 29 [#v0-8-11] * **Four privacy opt-outs replace the traffic kill, and `/design` comes back.** The home turns off telemetry, crash reports, `/feedback` and the session survey with four settings in `.claude/settings.json`, instead of `CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC`, which also hid `/design`, artifacts and Remote Control. `upgrade` makes the swap. If your own `~/.claude/settings.json` sets the old variable, delete that line yourself, and turn off **Help improve Claude** in your Claude account. [Privacy](/docs/run/privacy) * **The status line counts down to each rate-limit reset** on Pro and Max: `16% ↻ 2h · 56% ↻ 3d`. [Status line](/docs/run/claude-code#status-line) * **Explainers gain reveal cards, rails and accordions**, for detail that stays one click away: a row of short phrases that each open a panel, a list beside one panel for long detail, and rows that open in place. [Explainers](/docs/engineering/engineer#explainers) ### 0.8.10 · Oct 28 [#v0-8-10] * **A Slack pack: read-only Slack through your own account.** `slack` gives a pulse across your channels, grouped by a channel map you own, and reads one channel, a thread or a search. Each workspace creates a Slack app once, and `configure-skills` → Slack walks you through it. It never posts and never reads DMs. [Slack](/docs/packs/slack) * **The attention queue and sync show what Slack is waiting on**: the mentions you owe a reply, threads where someone outside the workspace has waited an hour or more, and channels you joined that the channel map doesn't list yet, with an offer to sort them in. [What's waiting](/docs/packs/slack#whats-waiting) ### 0.8.9 · Oct 28 [#v0-8-9] * **A GitHub sweep: everything on GitHub waiting on you, on one page.** `engineer sweep` (or "github sweep", "what do I owe on GitHub") finds the comments, reviews and conflicts waiting on you across your PRs, the reviews you owe and your issues, drafts a code-checked reply for each, and folds it all by issue with a Copy box and a Handled tick per item. Nothing is posted. [GitHub sweep](/docs/engineering/pull-requests#everything-waiting-on-you) * **Sync counts what GitHub is waiting on**: replies owed, re-reviews, pending reviews and your conflicting PRs, from numbers alone, and offers the sweep when any are owed. [Sync](/docs/use/sync#what-needs-attention) * **Sync saves the home before it starts**, so the run's own changes land as a clean diff and the opening snapshot is the point to go back to if a run goes wrong. [Saving a snapshot](/docs/use/sync#saving-a-snapshot) * **Briefings close with ranked first moves**: three to five actions across tasks due, sessions waiting on a decision, PRs and replies owed, and goals, instead of one first move. Sync now checkpoints your sessions before the briefing so the list sees them. [How a briefing ends](/docs/use/daily-rhythm#how-a-briefing-ends) * **"tldr" restarts step by step too**, the same as "I didn't read that". ### 0.8.8 · Oct 28 [#v0-8-8] * **The focus skill is now `attention`.** Claude Code ships its own `/focus` command, so `/agent-kevin:focus` never reached the skill. Run `/agent-kevin:attention` (or `$attention` in Codex); `where-am-i` and `triage` are now `attention checkpoint all`, and `upgrade` moves your project pages and permission rules over. [Upgrade notes](/docs/reference/upgrades#the-attention-skill-in-088) * **A checkpoint is a checklist.** `attention checkpoint` writes the session you're in as done steps with their proof, what's in progress, the next step, decisions waiting on you with a recommended pick, and traps. `attention checkpoint all` does the same for every recent session, the waiting decisions first, then offers to jump to one. [Checkpoints](/docs/use/attention#checkpoints) * **The Sessions page reads checkpoints**, one line per step, and the Today feed shows each session's in-progress step. [Sessions](/docs/dashboard/sessions) * **The dashboard's Tasks tab "Needs attention" is now "Blocked · stale"**, so "attention" means one thing on the dashboard. [Tasks and projects](/docs/dashboard/tasks-and-projects) * **"I didn't read that" restarts step by step.** The agent answers in three lines, then walks through the rest one short step per reply. * **Explainers gain step-through walkthroughs and clickable UI mocks.** [Explainers](/docs/engineering/engineer#explainers) * **A worktree on a base branch is never torn down**, and a stalled Chromium launch retries instead of hanging a capture. ### 0.8.7 · Oct 26 [#v0-8-7] * **A routine can note and assign tickets without asking.** When a queue profile's routine says its notes and assignments go ahead without asking, a sweep reads each new ticket, leaves a private note and hands it to a person, then lists everything it wrote. Cards, tasks and comments still wait for your yes. [Helpdesk](/docs/packs/helpdesk#routines-that-dont-ask) * **The agent can assign a SupportCandy ticket** to a teammate, and reads the ticket back to confirm the change took. [Helpdesk pack](/docs/packs/helpdesk) * **SupportCandy setup keeps the API out of the page cache.** A caching plugin with REST caching on can serve the agent's reads to anyone, login or not; setup now turns that off. [Helpdesk pack](/docs/packs/helpdesk#keep-the-api-out-of-the-page-cache) * **Explainer and PR report diagrams take the page's colours, and code is highlighted**, with added and removed diff lines marked. [Explainers](/docs/engineering/engineer#explainers) * **Ticket, review and diff text can't break out of its untrusted wrapper**, so a source can't speak outside it, and an attachment read from its temp folder counts as untrusted too. [Privacy](/docs/run/privacy) ### 0.8.6 · Oct 22 [#v0-8-6] * **The agent can fix its own GitHub comment** on an issue or a PR conversation, and never someone else's. [Writes](/docs/packs/github#writes) * **Hand off a task to the team.** `project handoff ` opens a GitHub issue for a task's work on the project's repo, after checking for one already open and only once you approve the draft. The task keeps the issue's link, and sync offers to close the task when the issue closes. [Tasks](/docs/use/tasks) * **App Store bug reports become one card each.** `helpdesk reviews` clusters recent reviews by what broke, at every star rating, and gathers each bug's cards, tickets and older reviews into one card or a comment on the open one. Sync counts the day's reviews and offers the pass when new ones arrive. [App Store](/docs/packs/app-store) * **An accepted issue is tracked through the fix.** The engineer skill moves it to `in progress` when work starts and, once the fix is proven, sets its milestone to the release it ships in and writes `Fixes #`, each on your yes. [Engineer](/docs/engineering/engineer) * **The agent can open a pull request from a pushed branch, and always asks first.** [Writes](/docs/packs/github#writes) * **A bare `engineer simplify` reviews this session's changes** against the build, the full test suite and every caller, and fixes the clear findings before reporting. [Simplify](/docs/engineering/engineer#simplify) * **Tools that always ask stay that way.** The server refuses `curl_run`, `seed_import` and `github_pr_create` until their ask rule is in place, and Codex now asks before each of them too. [MCP tools](/docs/reference/mcp-tools#what-is-granted-when) * **A classic token for an org that holds fine-grained ones for approval**, and `github_pr_update` now works on one. [GitHub pack](/docs/packs/github) ### 0.8.5 · Oct 22 [#v0-8-5] * **Raise a ticket as a bug, a feature or a task.** `helpdesk raise 318` proposes the kind with its reason, then files it wherever the queue profile's `## Raising` section sends that kind: a task or a GitHub card. `helpdesk bug 318` stays the shortcut for a bug. [Helpdesk](/docs/packs/helpdesk) * **The pulse reaches older open tickets.** A SupportCandy list filtered by status used to stop at the 1,000 most recently updated tickets, so older open ones never reached the pulse, routines or queue counts; it now reaches 10,000. [Helpdesk](/docs/packs/helpdesk) * **`database_query` checks a secret column with aggregates only**, never reading its values into the conversation. [Database pack](/docs/packs/database) ### 0.8.4 · Oct 21 [#v0-8-4] * **The `helpdesk` skill works a support queue**: a pulse that ranks what needs a person, a ticket's story, replies left as private notes for a person to send, and real bugs filed as a task or a GitHub card. When a card closes or development asks the user something, the pulse drafts the reply. [Helpdesk](/docs/packs/helpdesk) * **A queue profile per project** holds its own pulse, bug lifecycle, routines, tone and context, written by an interview: `helpdesk setup acme-shop`, or just "set up helpdesk for acme-shop". Sync nudges each scheduled routine when it's due. [Helpdesk](/docs/packs/helpdesk#a-queue-profile) * **Queue counts in sync and on demand.** Every support queue's last 24 hours by status and tag, unassigned and newly opened, counted without reading a ticket: each project's queue and the no-project connection. `helpdesk stats` asks for them any time. [Helpdesk](/docs/packs/helpdesk#pulses-on-a-schedule) * **One helpdesk connection per project.** `configure-skills` asks which project a SupportCandy site or Pylon workspace serves and names its keys after it; a named connection never borrows another's. [Several sites or workspaces](/docs/packs/helpdesk#several-sites-or-workspaces) * **Tickets carry their people** (the customer, the assignee, each message's author), and new reads list accounts, statuses, tags, teammates and macros. [Helpdesk pack](/docs/packs/helpdesk) * **An App Store pack** reads any app's reviews from Apple's public feed, with no key, and a queue profile can add them to its pulse. Nothing replies to a review. [App Store](/docs/packs/app-store) * **Review a stack of PRs from its edge** in one report, each finding on its own layer, and **preview every paste box** as GitHub will render it. [Pull requests](/docs/engineering/pull-requests) ### 0.8.3 · Oct 21 [#v0-8-3] * **A GitHub token per owner.** Each GitHub tool picks `GITHUB_TOKEN_` for the repo it's called on, then `GITHUB_TOKEN`, then your `gh` login, so repos under several orgs each get their own fine-grained token. Errors name the key and say whether the token was rejected, lacks a permission, or can't see the repo. [GitHub pack](/docs/packs/github) * **GitHub writes, when your token allows them**: open, edit, comment on and label issues with screenshots attached, and replace a PR's title or description. The token's permissions decide; nothing merges or closes. [Writes](/docs/packs/github#writes) * **Your own PR's description, applied after you approve it.** PR walkthroughs and replies offer to update it once you've seen the old and new text side by side; a teammate's PR is never edited. [Pull requests](/docs/engineering/pull-requests) * **GitHub goes through the tools only**: the GitHub pack denies `gh` in the agent's own shell, Codex gets the same block as a forbidden rule, and a seed bundle carries it to the recipient. [Codex](/docs/run/codex#what-gets-wired) * **A Helpdesk pack** reads support tickets and leaves private draft notes in SupportCandy or Pylon; a person sends every reply. [Helpdesk pack](/docs/packs/helpdesk) * **The `guide` skill** writes a guide someone else can follow, as one polished page: a setup walkthrough, onboarding, or who does what in a shared workflow. [Skills](/docs/reference/skills) * **Task tools set a task's parent, checklist, dependencies and description**, and say which fields they wrote. [Tasks](/docs/use/tasks#driving-them) * **Copy a diagram's Mermaid source** from its expanded view, and **jump back to the top** of a long review or explainer. [Engineer](/docs/engineering/engineer#explainers) ### 0.8.2 · Oct 19 [#v0-8-2] * **Sync commits the `assets/` and `scripts/` folders** that 0.8.1 created, so the moved avatar lands in history. ### 0.8.1 · Oct 19 [#v0-8-1] * **`.claude/` holds only what Claude Code reads.** The avatar moves to `assets/` and your browser flows to `scripts/browser/`, in a `scripts/` folder for the scripts you keep for recurring tasks; `upgrade` moves them. [Agent home](/docs/reference/agent-home) * **Pin a report or doc to a project**: it lives in the project's README and shows on its card, its focus page, and the Reports page. [Dashboard](/docs/dashboard#pinned-reports) * **`rename-agent` shows a dry run first**, keeps the home folder and dated records as they are, and records the old name under `Formerly` so the agent knows it was once called that. [Naming](/docs/run/naming#renaming-an-existing-home) * **PR reviews check the description, read the whole conversation, and re-review only what changed**, with an architecture section for large features and findings laid out as scenarios with proof. [Pull requests](/docs/engineering/pull-requests) * **Expand and zoom any diagram** on review and explainer pages. [Engineer](/docs/engineering/engineer#explainers) * **The agent no longer calls itself a Claude Code plugin**, so a Codex session isn't told it runs under Claude Code. Existing homes change the `Kind` line in `IDENTITY.md` by hand. [Upgrades](/docs/reference/upgrades#media-and-scripts-at-the-home-root-in-081) * **Fixes for Claude Code 2.1.299 and 2.1.300**: capture no longer saves logged API requests as turns, find-session no longer ranks every new session first, and a `/queue` sent while a background agent runs goes out. ### 0.8.0 · Oct 15 [#v0-8-0] * **One `AGENT_*` name per setting.** A `KEVIN_*` variable no longer overrides its twin, and the first `upgrade` renames what your home holds. [Configuration](/docs/run/configuration) * **Codex runs the MCP servers Claude Code runs**, not just the plugin's own. [Codex](/docs/run/codex#what-gets-wired) * **Seed bundles carry browser flows and say who they're for**, your own second agent or a teammate, never a `.env`. [Seed bundles](/docs/run/seed-bundles) * **The banner shows your agent's own name and emoji**, and briefings add the Hijri date only when you keep that calendar. * **A home still on `.kevin/` upgrades through 0.7.3 first**: this version no longer reads or moves that folder. [Upgrades](/docs/reference/upgrades#one-name-per-knob-in-080) ## 0.7 · Oct 8 – 14, 2026 [#07--oct-8--14-2026] ### 0.7.3 · Oct 14 [#v0-7-3] * **See this conversation's reports** with `/reports` and its session id with `/session`, each in a row above the prompt in Claude Code, and `/today` shows its agenda there too. [Mods](/docs/reference/mods#reports-from-this-conversation) ### 0.7.2 · Oct 12 [#v0-7-2] * **Queue a prompt until the current task ends** with `/queue` in Claude Code: each goes out as its own turn, in order, and a turn stopped with Esc or one that fails pauses the rest. [Mods](/docs/reference/mods#queue-a-prompt) * **PR reviews and replies end in one page** with a Copy button on every comment, and reviews add two lanes (generated-code tells and performance), a reading guide, and the case against merging; a small, low-risk PR runs as three agents unless you pass `--full`. [Pull requests](/docs/engineering/pull-requests#the-report-page) * **Pin reports to the dashboard sidebar** by listing them in `reports/pinned.md`; every session's context names them, and the brain pass asks about a broken or stale one. [Dashboard](/docs/dashboard#pinned-reports) * **Every generated page has an Auto / Light / Dark switch**, Auto by default, from the dashboard to roadmaps and itineraries. [Dashboard](/docs/dashboard#light-and-dark) * **Explainers have a template**: the `engineer` skill writes the body, and a script checks it and wraps it in a page with a contents dropdown. [Engineer](/docs/engineering/engineer#explainers) * **Pick a project's color** with `hue:` in its README, and see its roadmap and focus links on the card's first line. [Tasks and projects](/docs/dashboard/tasks-and-projects#projects) * **`/done` suggests the task to close** in Claude Code, from the start of its id or a word of its title. [Tasks](/docs/use/tasks#driving-them) * **A new folder points at setup** in Claude Code, with a Set up button above the prompt. [Mods](/docs/reference/mods#setting-up-a-new-folder) * **The shell guard holds the `cd` and scratch-file rules**, refusing a `cd` that would leave the home (in Claude Code) and a shared temp path found by pattern or picked by hand. [Hooks](/docs/reference/hooks) * **The Xcode pack stops asking before `RunCodeSnippet`** in Claude Code; the debugger stays gated. [Xcode](/docs/packs/xcode#what-it-gives-you) * **One command installs the plugin in Claude Code**, adding the marketplace when it's missing. [Install by hand](/docs/getting-started/install#install-the-plugin) * **Claude Code 2.1.293 or newer is required.** Setup and `upgrade` stop below it and say to run `claude update`. [Claude Code](/docs/run/claude-code#required-version) ### 0.7.1 · Oct 8 [#v0-7-1] * **Notices: one place for upgrade and sync reminders**, louder as they go unaddressed: sync by days since the last run, upgrade by releases behind. In the Claude Code terminal the top one sits above the prompt with a button that runs it and one that snoozes it until tomorrow; everywhere else it's in the session banner. [Notices](/docs/reference/notices) * **Sync offers a north-star roadmap** at every run until the home has one, and the north star then heads your yearly goals. [Daily rhythm](/docs/use/daily-rhythm#working-sessions) * **The status line reads on a light terminal**, following your Claude Code theme or the macOS appearance. [Claude Code](/docs/run/claude-code#status-line) * **The dashboard lists the mods**: a Mods tab on the Capabilities page, with the commands each adds and whether they've loaded on this machine. [Capabilities](/docs/dashboard/capabilities#mods) ### 0.7.0 · Oct 8 [#v0-7-0] * **One data folder name for every agent.** The runtime folder moves from `.kevin/` to `.state/`, and its `version.json` records which agent owns it. The first `upgrade` moves it for you, with nothing to answer. [How the move works](/docs/reference/upgrades#moving-to-state-in-070) * **Secrets stay guarded in every home**, including homes created when your global settings already carry their own deny list. [Privacy](/docs/run/privacy) * **A clear message when the move can't happen yet**, such as a Windows file lock, with what to close before running `upgrade` again. * **Instant commands in Claude Code**: `/capture`, `/lesson`, `/done` and `/today` run without waiting on a reply. [Mods](/docs/reference/mods#instant-commands) * **A repo's own instructions load the first time a session touches it**, in Claude Code, so the agent follows that repo's conventions without being told to read them. [Mods](/docs/reference/mods#repo-manuals-on-first-touch) * **Sync shows its progress** above the prompt, and its report quotes counted numbers. [Sync](/docs/use/sync#progress-and-reminders) * **Sync's closing question takes several picks**, worked through in order or each queued as a task. [Sync](/docs/use/sync#the-closing-interview) ## 0.6 · Sep 29 – Oct 7, 2026 [#06--sep-29--oct-7-2026] ### 0.6.5 · Oct 7 [#v0-6-5] * **Removed: renaming the runtime folder** (`AGENT_RUNTIME_DIR`). It was only partly supported and could leave secrets unguarded. ### 0.6.4 · Oct 7 [#v0-6-4] * **A monthly brain pass.** Self-review finds stale tasks, outdated memory and decisions worth keeping, and asks you about each. [Self-evolution](/docs/use/self-evolution) * **Codex homes default to GPT-6.1 Sol.** [Codex](/docs/run/codex) ### 0.6.3 · Oct 2 [#v0-6-3] * **Sync reminds you** after three days without one, and offers the brain pass when it's due. [Sync](/docs/use/sync) ### 0.6.2 · Oct 1 [#v0-6-2] * **Audio and video.** Transcribe voice memos and recordings on your Mac, grab screenshots at chosen moments, and turn a bug-report video into repro steps. [Skills](/docs/reference/skills) * **Drop folders, zips and PDFs into the inbox**, and the next compile reads them. [Capture](/docs/use/capture) ### 0.6.1 · Sep 30 [#v0-6-1] * **Daily goals**, set in the morning and scored at night. [Daily rhythm](/docs/use/daily-rhythm) * **A welcome after setup** that suggests where to start. [Your first ten minutes](/docs/getting-started/first-ten-minutes) * **Fewer, broader skills.** Fifteen skills folded into five, each with playbooks for the different asks. [Skills](/docs/reference/skills) * **Postman support** for API request collections. [API collections](/docs/engineering/api-collections) * **Machine-specific settings live in `settings.local.json`**, so a home's shared settings travel cleanly. [Configuration](/docs/run/configuration) ### 0.6.0 · Sep 29 [#v0-6-0] * **Focus: your day in one place.** Plan today, the week and the month, get a standup card, see where every session left off, and turn "I'm overwhelmed" into a sorted list. [Attention](/docs/use/attention) * **Setup asks about your world**: what you're working on, what should land this year, and the company the agent works for, so the first sessions start with context. [What setup asks](/docs/getting-started/onboarding) * **Python runs through uv**, so scripts never install packages globally. [Install by hand](/docs/getting-started/install) ## 0.5 · Sep 23 – 29, 2026 [#05--sep-23--29-2026] ### 0.5.3 · Sep 29 [#v0-5-3] * **Tax and books.** What you owe right now, deadlines as tasks, receipts and the monthly close. [Tax and books](/docs/use/tax) ### 0.5.2 · Sep 28 [#v0-5-2] * **Pull requests in the engineer skill**: review a teammate's PR, answer the review on yours, or prepare yours for standup. [Pull requests](/docs/engineering/pull-requests) ### 0.5.1 · Sep 26 [#v0-5-1] * **Version history for the brain**, kept on your machine, so any change to what the agent knows can be seen and undone. [History](/docs/run/history) * **Safer worktree cleanup**: a PR review removes the worktree it made once its report is saved, and the cleanup audit never offers a worktree a session is still working in. [Worktrees](/docs/engineering/worktrees) ### 0.5.0 · Sep 23 [#v0-5-0] * **Upgrades keep your edits.** Template changes merge three ways against what you changed since the last upgrade. [Upgrades](/docs/reference/upgrades) * **Windows fixes**: files with Windows line endings read correctly, and the one tool that needs a POSIX shell says so instead of failing halfway. [Platforms](/docs/about/platforms) ## 0.4 · Sep 6 – 23, 2026 [#04--sep-6--23-2026] ### 0.4.12 · Sep 23 [#v0-4-12] * **The engineer skill**: a playbook for each kind of code task and the principles behind them. [Engineer](/docs/engineering/engineer) ### 0.4.10 · Sep 23 [#v0-4-10] * **Self-review prunes first**, and rules that prove useful in real homes move into the templates. [Self-evolution](/docs/use/self-evolution) ### 0.4.9 · Sep 18 [#v0-4-9] * **Xcode pack**: build, test and run Apple apps from a session. [Coding rules](/docs/engineering/coding-rules) ### 0.4.8 · Sep 17 [#v0-4-8] * **Second-model review.** Have another model review your own branch, plan or document, then verify every finding against the work. [Second-model review](/docs/engineering/second-model-review) ### 0.4.1 · Sep 7 [#v0-4-1] * **Codex is a second host.** Run the same home from Claude Code or Codex. [Codex](/docs/run/codex) * **A guard on shell commands** that would write into the wrong folder after the session changed directory. [Hooks](/docs/reference/hooks) ### 0.4.0 · Sep 6 [#v0-4-0] * **One manual for every host.** `AGENTS.md` is the operating manual, and Claude Code reaches it through a short bridge. [Hosts](/docs/run/hosts) ## Earlier · Jun 20 – Sep 5, 2026 [#earlier--jun-20--sep-5-2026] The foundations: the compiled brain and session capture, tasks and projects, briefings, the dashboard, skill packs for SEO, the browser, databases and GitHub, and seed bundles for handing an agent to a teammate. How it got here: [Before the plugin](/docs/about/history). # What it is (/docs) AgentLayer turns Claude Code or Codex into an agent that remembers your work, in a folder you own. It installs as a plugin into the agent CLI you already use. Everything that makes the agent yours (its character, what it knows about you, your projects and tasks) lives in one folder of plain markdown on your disk. Any model can read it. You can browse it in Obsidian, keep it in git, and take it with you. ## Meet Oppi [#meet-oppi] Oppi, the AgentLayer octopus Your agent wakes up as Oppi 🐙. An octopus keeps many arms busy at once with one brain behind them, and that is how it works for you: several jobs in flight, one memory of all of them. Call it whatever you like; Oppi is just who shows up first. See [why an octopus](/docs/run/naming#why-an-octopus). cmux with three agents, Oppi, Nova and Scout: their sessions on the left, Oppi working in the middle, and the AgentLayer sidebar on the right Your agent's projects, what is due and what comes next, in the [AgentLayer sidebar](/docs/workstation/cmux#the-agentlayer-sidebar) beside your terminals. ## Who it is for [#who-it-is-for] Anyone who would use an agent that remembers, not only engineers. Installing is one command, in the [Quickstart](/docs/getting-started/quickstart). After that you talk to it. Pick the path that fits you: - [I lead a team](/docs/use/daily-rhythm): Daily rhythm for the briefings and goals, then Standup and checkpoints, then the Dashboard, then Seed bundles to hand the agent to your team. - [I write code](/docs/engineering/engineer): The engineer skill, then Pull requests, then Worktrees for parallel agents, then cmux to watch every session at once. - [I run support](/docs/packs/helpdesk): Helpdesk for the ticket queue, then Slack for the threads waiting on your team, then Attention to see who is waiting on you. - [I want a personal assistant](/docs/getting-started/first-ten-minutes): Your first ten minutes, then Daily rhythm, then Capture to feed it anything, then the Dashboard to see your day. ## The loop [#the-loop] Every session is saved when you exit. Saved sessions are compiled into notes the agent keeps. Those notes load before you type a word in the next session. Everything else is built around that loop: skills and tools feed it and act on what it knows. ## How it behaves [#how-it-behaves] * **You drive.** It never starts a session on its own. Skills run when your request calls for one. * **No metered API key.** Its tools return prompts and [your own session does the thinking](/docs/run/hosts#billing), on the plan you already have. * **Local by default.** No cloud sync unless you put the folder somewhere that syncs. Keys sit in a store the agent's own tools cannot read. See [Privacy](/docs/run/privacy). * **One plugin, many agents.** A personal agent and a work agent share one install and keep [separate folders](/docs/run/another-agent). ## Start here [#start-here] - [Quickstart](/docs/getting-started/quickstart): One line in a terminal, a few questions, a working agent. - [Your first ten minutes](/docs/getting-started/first-ten-minutes): Say hello, teach it something, see it remembered. - [How it works](/docs/getting-started/how-it-works): The folder, the brain, the rails, and skills and packs. The open-source plugin is `agentlayer`: 36 [skills](/docs/reference/skills), 84 tools and four hooks. The [dashboard](/docs/dashboard) shows your own agent on one page. Reading with a model? The site is also served as [llms.txt](/llms.txt) (the index) and [llms-full.txt](/llms-full.txt) (every page as Markdown). # Contributing (/docs/about/contributing) Particularly welcome: * New skill packs that ship opt-in through `configure-skills` * New MCP tools that fit the read-mostly, key-gated model * Linux and Windows hardening, with install notes * Documentation improvements and more use-case examples * Translations and regional compliance hints * New hosts: see [what a host needs](/docs/run/hosts#adding-a-host) Open an issue first for architectural changes. The plugin's contract with the markdown home is intentional and worth preserving. ## The dev loop [#the-dev-loop] You run the plugin from your own fork. The fork is where your changes live, and it doubles as the marketplace: the repo ships a developer marketplace (`agentlayer-dev`) on both hosts, so the checkout registers directly. ### Fork the repo _Your changes need a repo you can push to. Pull requests go from your fork to the upstream repo._ Open [AgentLayer1/agentlayer-agent](https://github.com/AgentLayer1/agentlayer-agent) on GitHub and click **Fork**. Keep the name `agentlayer-agent`. ### Clone your fork Swap `` for your GitHub username. The second line records the original repo as `upstream`, which is how your fork stays current: ```bash git clone https://github.com//agentlayer-agent ~/Developer/agentlayer-agent cd ~/Developer/agentlayer-agent && git remote add upstream https://github.com/AgentLayer1/agentlayer-agent ``` Then, once, install the plugin's packages at the repo root. It takes a minute and about 300 MB, most of it the browser the web tools drive: ```bash cd ~/Developer/agentlayer-agent && bun install ``` ### Install from the fork Register the clone as a marketplace on your host and install the plugin from it. The two commands per host are on [Install by hand](/docs/getting-started/install#from-your-own-fork). In Claude Code, edits to the fork go live after `/reload-plugins`, and skill-body edits on the next session; new skills or hooks need a full relaunch. Codex copies the checkout into its plugin cache, so there you remove and re-add the plugin after a change. ### Make a change Work on a branch, never on your fork's `main`, so `main` always matches upstream: ```bash cd ~/Developer/agentlayer-agent && git switch -c my-change ``` Make the change and try it in a session. Before pushing, the checks must pass: ```bash cd ~/Developer/agentlayer-agent bun src/server.ts # boot check: the banner reports the tool count bun run typecheck && bun test ``` ### Open a pull request Commit, then push the branch to your fork: ```bash cd ~/Developer/agentlayer-agent && git push -u origin my-change ``` On GitHub, open a pull request from that branch in your fork to `main` on `AgentLayer1/agentlayer-agent`. GitHub offers **Compare & pull request** right after the push; with the GitHub CLI it's `gh pr create --repo AgentLayer1/agentlayer-agent`. ### Keep your fork current Upstream moves on without you. Pull it into your fork's `main` before starting each change, and after your pull requests merge: ```bash cd ~/Developer/agentlayer-agent && git switch main && git pull --ff-only upstream main && git push origin main ``` Then bring a branch still in progress up to date by running `git merge main` on it. If the pull changed `package.json`, run `bun install` at the root again. The plugin you run is the fork, so this is also how you update it; finish with the [upgrade](/docs/run/updating) step to reconcile your home. **Adding a skill:** `skills//SKILL.md` with frontmatter; grant its MCP tools in the init skill's permission list; use `mktemp` for scratch files, since `$TMPDIR` is per-user, not per-session. **Adding an MCP tool:** declare it with `defineTool` from `@/shared/tool-def` in its domain's `src//tool.ts`. A new domain's `tool.ts` gets one import line in `src/tools.ts`. Grant it as `mcp__plugin_agentlayer_agent__` in the init skill's permission list, or in its pack's `configure-skills` walk. PR conventions: focused changes, update docs when counts change, no unjustified dependencies, typecheck passes. Full detail in [CONTRIBUTING.md](https://github.com/AgentLayer1/agentlayer-agent/blob/main/CONTRIBUTING.md); the source layout and its rules are in [AGENTS.md](https://github.com/AgentLayer1/agentlayer-agent/blob/main/AGENTS.md). ## License [#license] Apache 2.0. `agentlayer` is © AgentLayer. Third-party skill libraries installed through `configure-skills` are not bundled; each carries its own license, so review the terms before relying on one commercially. # FAQ (/docs/about/faq) ### Do I need to be a developer to use this? You need to run a plugin install command and launch Claude Code or Codex. After that the whole experience is conversational; the `init` skill walks you through everything. ### I finished init and relaunched, but no banner appears. A trust step was missed. In Claude Code, re-install with `/plugin install agentlayer --marketplace AgentLayer1/agentlayer-agent-marketplace`, then relaunch. In Codex, trust the folder and run `/hooks` to trust the four hook entries ([Codex](/docs/run/codex#set-it-up)). ### I already had a CLAUDE.md or AGENTS.md here. Was it overwritten? No. The agent's manual is `AGENTS.md` and its Claude Code bridge is `.claude/CLAUDE.md`, so a root `CLAUDE.md` is never touched. A pre-existing `AGENTS.md` gets the manual appended below your content. ### How do I update? Pull the new plugin version on your host, then run the `upgrade` skill to reconcile the home. See [Updating](/docs/run/updating). ### How do I uninstall? `/plugin uninstall agentlayer@agentlayer` in Claude Code, `codex plugin remove agentlayer@agentlayer` in Codex. Your home stays. To purge everything, delete the home directory. ### Will my agent ever message me first? No. You initiate every session. External schedulers can pipe prompts into a headless host run, but those go through the pay-per-token API. See [The host does the thinking](/docs/run/hosts#billing). ### Does subscription billing really avoid API costs? For the synthesis steps, yes. The MCP server is pure I/O and returns prompts; your interactive session does the thinking on your host's plan. [Verify it](/docs/run/claude-code#verifying-subscription-billing) against your usage meters. ### Can I run several agents on one machine? Yes. One plugin install, one home per agent, told apart by the folder you launch from. Never pin `AGENT_HOME` machine-wide. See [Adding another agent](/docs/run/another-agent). ### Can I use one home from both hosts? Yes. Wire the home for Codex once, as the [Codex](/docs/run/codex#set-it-up) page shows, and sessions from either host land in the same brain. See [Hosts](/docs/run/hosts). ### Can I use a different model or host? The brain is plain markdown and `AGENTS.md` is host-neutral, so any AGENTS.md-aware CLI reads the manual. Full plugin support today: Claude Code and Codex. What a new host needs is on the [Hosts](/docs/run/hosts#adding-a-host) page. # Before the plugin (/docs/about/history) The first version was a standalone program, not a plugin. The brain was the same markdown folder you see today. What ran around it was different: | Part | What it did | | --------------------- | ------------------------------------------------------------------------------------------ | | A long-running daemon | Talked to the Claude Agent SDK on your behalf, so the agent could work while you were away | | A chat bot | Let you reach the agent from a messaging app on your phone | | Scheduled jobs | Sent a morning briefing at 7am and an evening wrap, and compiled knowledge every six hours | ## Why it changed [#why-it-changed] Anthropic [closed off](https://www.anthropic.com/news/claude-developer-platform) the Agent SDK from subscription billing, so headless SDK calls became pay-per-token only. The design depended on a flat monthly subscription, not on a bill for whatever the agent did overnight. Without a subscription-backed SDK the daemon could not survive. ## What it became [#what-it-became] The agent was rebuilt as a plugin, first for Claude Code, then for Codex. The brain is intact and the skills were ported. The MCP server runs locally and returns prompts that you, in your own session, synthesize on your plan. That is why everything in the plugin makes the host do the model work, never the plugin itself. See [Architecture](/docs/reference/architecture#why-the-model-never-runs-inside-the-plugin). | Kept | Gone | | -------------------------------------------- | ------------------------------------------------------------------------------------- | | Memory compounding, the wiki pipeline | Proactive messaging at 7am | | Projects, tasks, audits, briefings on demand | The chat bridge | | Everything file-based and portable | The scheduling daemon (an external scheduler can run a headless host, on API billing) | If the Agent SDK ever reopens to subscription billing, the daemon comes back. Until then, the plugin is as much of the agent as fits inside the rules. # Platforms and limits (/docs/about/platforms) ## Platform support [#platform-support] | Platform | Status | Notes | | ------------------- | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **macOS** | Primary | Built and tested here | | **Linux** | Works | Setup installs the browser tools' Chromium, but a fresh distro lacks the system libraries it needs. The first failed launch prints the one `install-deps` command to run ([Browser](/docs/packs/browser#if-the-browser-wont-start)) | | **Windows, native** | Works through Git Bash (Claude Code) | Git Bash supplies the POSIX environment the hooks, server, and skills expect. Needs `bun` and `git` on `PATH`. Codex on native Windows is unverified | | **Windows, WSL2** | Works | Closest to a Linux production target; run everything inside the distro | Native Windows rough edges: * MSYS path-mangling can bite commands that pass colon-paths. `MSYS_NO_PATHCONV=1` is the escape hatch. * The OS sandbox is unavailable, so that block is omitted and a shell command can read `.state/secrets/`. WSL2 has the sandbox. * A few pack-gated playbooks assume tools Git Bash lacks (`seo serp` pipes through `jq`), and `init` prints the `winget` command for each missing one. Files with Windows line endings read correctly, and the plugin's own checkout stays LF whatever `core.autocrlf` says. The core loop of tasks, compile, memory, briefings, worktrees, and dashboard runs natively. Platform-specific fixes and install notes are welcome as pull requests. ## Known limitations [#known-limitations] 1. **The host must open in the home** for the static identity to load. Outside, you get nothing, silently. See [the one convention](/docs/getting-started/onboarding#the-one-convention). 2. **A host sandbox can block `.claude/skills/` writes** during `configure-skills`. Pre-create the directory from a normal terminal if it hits the wall. 3. **The browser download can be cut short** when it runs inside a host's sandbox. Setup installs Chromium for you; if a browser tool then says the binary is missing, [the repair is one command](/docs/packs/browser#if-the-browser-wont-start) from a normal terminal. 4. **No live GUI.** The dashboard is a static snapshot regenerated on sync; between syncs it can drift from task frontmatter. 5. **Single-user.** Team isolation is not built in; use separate homes per person, or a shared repo where everyone gets the same identity. 6. **Nothing runs on its own.** You start every session. See [The host does the thinking](/docs/run/hosts#billing). # Brain (/docs/dashboard/brain) The Brain page is the agent's memory made visible. See [The brain](/docs/reference/the-brain) for how it's built. ## Context [#context] Brain · Context Everything loaded at the start of every session, with a check that each file resolves and its size. The files are the bridge, the manual, the identity stack, the indexes, and the task dashboard. A bar breaks the total down by kind: instructions, identity, knowledge, tasks. Below it: * **Path-scoped rules**, each with the globs it applies to. * **Injected at SessionStart**, the dynamic lane: today's date first, then the last session tail, today's reports, your [pinned reports](/docs/dashboard#pinned-reports), and recent git activity, each with a short note such as how many pins or commits it carries. Watch the total: everything here is paid for on every turn. What each lane holds and how it arrives is on [Agent home](/docs/reference/agent-home#what-loads-at-session-start). ## Memory [#memory] Brain · Memory * **Daily memory:** the last 14 days of daily notes. * **Learnings:** the rules the agent synthesized from your corrections, which is how it self-corrects. * **Pending:** the open loops it's tracking. ## Threads [#threads] Brain · Threads The **active threads** the agent keeps in hot memory, and the **recent decisions** with their dates, from `knowledge/memory/index.md`. ## Concepts [#concepts] Brain · Concepts The concept articles: cross-cutting patterns that span several projects, each with its one-line description from the knowledge index. ## Pipeline [#pipeline] Brain · Pipeline * **Compile pipeline:** how many captured session days are ingested, how many are pending, when it last compiled, the inbox waiting to be absorbed, and the running compile cost. * **Memory footprint:** the size of the curated wiki, the memory index, the learnings count, the daily files, and the feedback log. ## Lint [#lint] Brain · Lint The last knowledge lint: errors, warnings, and suggestions, each issue listed, with a link to the full report. `sync` runs the lint and fixes what it safely can. # Capabilities (/docs/dashboard/capabilities) ## Cheatsheet [#cheatsheet] Capabilities · Cheatsheet Starter recipes: when to run something, what to say, and what happens. It's the fastest way in for a new operator. ## Skills [#skills] Capabilities · Skills Every skill as a tile with its description, and a playbook skill's playbooks as chips under it; run one as the skill plus its name, `goals week`. The tab counts skills and playbooks. An **auto** badge marks the skills the agent may run on its own when a request clearly calls for them, all but `init`, `release`, and `rename-agent`, which wait for you to name them. Chips filter auto against manual, and a home's own custom skills carry a custom chip. The full list is on [Skills](/docs/reference/skills). ## Tools [#tools] Capabilities · Tools Every MCP tool the plugin's server exposes, with its description. The grouped reference is on [MCP tools](/docs/reference/mcp-tools). ## Commands [#commands] Capabilities · Commands The plugin's CLI, `src/cli.ts`: its groups and commands, for scripts and terminals. See [CLI](/docs/reference/cli). ## Mods [#mods] The plugin's in-process features for Claude Code, one tile each: instant commands, repo manuals, sync progress, notices, the prompt queue, and the setup prompt. Each tile lists the slash commands and tools it adds, like `/capture ` or `sync_stats`. A line on top gives the Claude Code version mods need and whether they've loaded on this machine. The evidence is the stamp the notices mod leaves at each session start: the last date it ran and the plugin version it ran on. See [Mods](/docs/reference/mods). ## Reflexes [#reflexes] Capabilities · Reflexes The hooks wired into the host: session start, session end, pre-compact capture, and the shell guard. Each has an explanation of what it does. See [Hooks](/docs/reference/hooks). # Dashboard (/docs/dashboard) Every sync regenerates `/dashboard.html`. Open it like any file: no server, no service, no account. A left sidebar carries the plugin's wordmark and version, the page nav, your operator card, and a system-health badge. The pages are operator-first: what needs you today comes before how the machinery works. > **Try it** A live demo, rendered from a fictitious company's home (Acme's agent Ace, operator Alex Chen), is at [agentlayer.one/demo/dashboard](/demo/dashboard). Every screenshot in this section comes from it. Today: attention for the day, the week, the roadmap, and who is waiting on you ## The pages [#the-pages] | Page | What it's for | | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | [Today](/docs/dashboard/today) | Your day, opened on Attention: today's three, what slipped, the week and month, the roadmap, who is waiting on you, what moved today, goals, and the morning's news | | [Tasks and projects](/docs/dashboard/tasks-and-projects) | Every open task by deadline, what's in flight, blocked, or going stale, and each project's progress | | [Sessions](/docs/dashboard/sessions) | What you and the agent worked on, where it left off, and how to resume it | | [Brain](/docs/dashboard/brain) | What the agent loads every session and what it has learned | | [Reports and scheduler](/docs/dashboard/reports-and-scheduler) | Everything the agent produced, and the routines that keep it current | | [Capabilities](/docs/dashboard/capabilities) | Every skill, tool, command, and hook, with a cheatsheet of what to say | | [Persona and system](/docs/dashboard/persona-and-system) | Who the agent is, who you are, its settings and logs, the changelog, and the health checks | A **Surfaces** group in the sidebar lists the standalone pages the agent builds alongside it, discovered by convention: `roadmap.html` at the home root (🗺️), then any project's `dashboard.html`. The home attention view is the Today tab itself; a project's own roadmap and attention page are linked from its project card. ## Pinned reports [#pinned-reports] A **Pinned** group under Surfaces lists the reports you want in view. Say "pin this report" or "unpin" and the `dashboard` skill edits `reports/pinned.md`, one link per line, relative to `reports/`: ```markdown # Pinned - 🛡️ [Security plan](plans/security-plan.html) - [Launch checklist](plans/launch-checklist.md) ``` The emoji is optional (📌 otherwise). `*` bullets, `%20` in a path, a `#anchor`, and a `<…>` target read too. * Each pin opens in a new tab, like the roadmap. * The [Reports](/docs/dashboard/reports-and-scheduler#reports) page leads with the pins. * Every session's context lists them too, up to ten by name, so the agent knows what you keep in view. * A pin whose file is gone, or one outside the home, drops out of the sidebar, and the monthly [brain pass](/docs/use/self-evolution#the-brain-pass) asks you to fix or remove it. ### Pins for one project [#pins-for-one-project] A pin that belongs to one project goes in that project instead. Say "pin this to acme" and the line lands under a `## Pinned` heading in `projects/acme/README.md`, linked relative to the README (`../../reports/plans/x.md`). "Pin this" with no project named stays global. * The project's [card](/docs/dashboard/tasks-and-projects#projects) shows a 📌 count and lists the pins above its tasks. * Its attention page gets a Pinned lane. * The Reports page lists them after the global ones, each with its project. * They stay out of the session context, since the README is read whenever the project is in play. * The brain pass checks them like global pins, and a seed export ships the README without its Pinned section. ## The health badge [#the-health-badge] The badge at the bottom of the sidebar reads **all nominal** only when five blocking signals are all zero: * overdue tasks; * captured sessions not yet compiled; * errors in today's log; * a missing `@` import in the context chain; * a task file that doesn't parse. Tasks going stale are shown but never turn the badge amber. Click the badge for the [Status](/docs/dashboard/persona-and-system#status) page. A separate **sync overdue** badge appears when the last briefing is more than eight hours old. ## Refreshing it [#refreshing-it] * `sync` does it automatically. * `dashboard` rebuilds and opens it. * `bun "/src/cli.ts" dashboard` does the same from a terminal. Every refresh also rebuilds `projects/TASKS.md`; the two derived views always regenerate together. It's a snapshot, not a live app. The footer says when it was generated and when knowledge last synced. ## Opening links [#opening-links] Links to files (tasks, reports, concepts, pages) open the file itself in a new tab, so the dashboard stays put. A page renders; a note shows as plain markdown text. To open notes rendered and editable in an app, set `MARKDOWN_URL` in the home's `settings.local.json`: ```json { "env": { "MARKDOWN_URL": "markedit://open?path={path}" } } ``` For Obsidian, use `obsidian://open?path={path}&paneType=tab`. Every list has a filter box, and every page and sub-tab has its own URL fragment (`dashboard.html#brain/concepts`), so you can bookmark or share a view. ## Light and dark [#light-and-dark] Every page the agent generates has an Auto / Light / Dark switch: the dashboard, attention pages, pull-request pages, roadmaps, the tax dashboard, itineraries, guides, and explainers. Auto is the default and follows your system's appearance as it changes. The browser remembers your choice, and every one of these pages opened in the same browser reads it. An itinerary always prints light. A roadmap or itinerary built before the switch existed keeps its old look until its skill renders it again. > **Privacy** The page makes zero external requests and nothing on it leaves your machine. It does reflect your tasks, knowledge stats, and redacted settings, so if you ever publish the home repo (GitHub Pages, say), this page publishes too. Keep agent homes private. # Persona and system (/docs/dashboard/persona-and-system) ## Persona [#persona] Persona The agent as its identity files describe it: its name, emoji, and avatar; its kind and vibe; and its bio. Below come the sections from `IDENTITY.md` and `SOUL.md`: core role, vibe, operational pattern, and the rest. Further down, **Runtime** shows the plugin version, where the home lives, and its timezone. ## Profile [#profile] Profile You, as the agent knows you. Open it from the operator card at the bottom of the sidebar. It shows your headline and timezone, the sections of your profile facet, and **Go deeper** links to every user facet with its description and size. ## System · Settings [#system--settings] System · Settings * **Settings layers:** user, project, and local, with the allow, deny, and env counts in each. * **Plugin:** which plugin and marketplace are active. * **Environment:** every variable and the scope that set it. Secret values are masked. * **Secrets:** key names only; values are never shown. ## System · Logs [#system--logs] System · Logs The log file's size, today's and all-time warnings and errors, and a filterable tail, newest first. ## System · Changelog [#system--changelog] System · Changelog The plugin's changelog with your home's baseline marked. It says whether you're up to date and, for each release, what changed and what its upgrade step does. See [Updating](/docs/run/updating). ## Status [#status] Status Open it by clicking the health badge. It shows the five blocking signals behind [the badge](/docs/dashboard#the-health-badge), each explained with what's wrong and how to clear it. Going-stale tasks are listed for information only. # Reports and scheduler (/docs/dashboard/reports-and-scheduler) ## Reports [#reports] Reports Every briefing, plan, radar, review, API run and helpdesk pulse the agent wrote, newest first, grouped by the day each was last updated, so a report edited after the day it was filed moves up. Each row has its time, its status as a word in a coloured badge (clean, findings, critical or draft), the title, and the skill that wrote it. Category chips filter by kind: the plugin's categories first, then any folder of your home's own. Every title opens the report file. `reports/index.md` holds the same reports under the day each was filed. Your [pinned reports](/docs/dashboard#pinned-reports) lead the page as their own group, and a 📌 Pinned chip beside the categories shows only them. ## Scheduler [#scheduler] Scheduler The recurring routines and when each is next due: * sync, morning and evening; * weekly, monthly, and quarterly goals; * the monthly self-review. Each card shows its cadence, the next run relative to today, and the exact command. Routines are manual for now: the card tells you when, and you run it. # Sessions (/docs/dashboard/sessions) Every session is captured by the host's hooks and summarized. The header counts today's sessions, the last seven days (and how many of those were resumed), and the sessions on the latest radar. A **Volume** bar shows how much was captured on each of the last seven days. ## Recent [#recent] Sessions · Recent The latest session radar, written by the [attention](/docs/use/attention) skill's `checkpoint all`: the decisions waiting on you first, ranked, then a card per session with its checklist (✓ done, ▶ in progress, ▷ next) and the command that resumes it. The Today feed shows each session's in-progress step, or its next step when nothing is in progress. When a session touched tasks or plans, the card links them. [Checkpoints](/docs/use/standup-and-checkpoints#checkpoints) shows the report as the skill writes it, with an example card. ## History [#history] Sessions · History The last 30 days of real working sessions, grouped by day, each with its turn count, a one-line summary of what it was about, and the folder it ran in. A session that spanned several days shows where it started. ## Locations [#locations] Sessions · Locations Every folder sessions ran in, with a session count and the last date. It shows at a glance which repos the work actually touched. To find an older session by what it did (a branch, a PR, a bug), ask for it: the `find-session` skill searches every transcript. # Tasks and projects (/docs/dashboard/tasks-and-projects) Tasks are one markdown file each (see [Tasks](/docs/use/tasks)). The dashboard reads their frontmatter directly, so what you see is the files, never a cached copy. The Tasks header counts what's overdue, due today, due this week, in flight, blocked, and going stale; each tile scrolls to the group that lists them. Deadline counts include in-flight tasks, which the agenda lists once, under In flight, so a tile names how many of its count are there. The Projects header counts the projects, how many are moving, how many have blockers, the quiet ones, and how much is done overall. ## Tasks · Agenda [#tasks--agenda] Tasks · Agenda Every open task by deadline. **In flight** leads: the active tasks, each once, with its own due date. Then the rest by due date: overdue, due today, due this week, due this month, due later, and no due date. Project chips filter the list, and the filter box searches titles. The agenda is about deadlines. What you *planned* for today, the week, or the month is [Today → Attention](/docs/dashboard/today). ## Tasks · Blocked · stale [#tasks--blocked--stale] Tasks · Blocked · stale * **Blocked:** every blocked task, with its reason. * **Going stale:** open tasks not updated in over a week. They're informational; they never turn the health badge amber. ## Projects [#projects] Projects One card per project, most recently updated first, with the description from its README, an active, open, and blocked count, and a progress bar of done over total (archived tasks count as done). Click a card to expand its tasks by status. A project with its own `roadmap.html` or attention page gets a 🗺️ Roadmap or 🎯 Attention link on the card's first line, visible without expanding it. Each project's color comes from its name. To pick one, set `hue:` (0 to 359 on the color wheel: 0 red, 120 green, 210 blue) in the frontmatter of the project's `README.md`, or ask the agent to; the card, its chips, and its rows on the attention pages follow at the next refresh. # Today (/docs/dashboard/today) Today opens with a time-aware greeting and a stat strip drawn from your attention view: today's picks out of three, carried over, due and not planned, this week's progress, roadmap milestones in flight, and how many people are waiting on you. Each tile names its detail underneath (the oldest carried item, how many milestones slipped, when the queue was pulled) and jumps to the part of the page it counts. The four sub-tabs below answer "what is today for", "what already happened", "what am I aiming at", and "what changed in the world". ## Attention [#attention] Today · Attention The home view of the [attention](/docs/use/attention) skill, and the tab the dashboard opens on. It is drawn exactly like a project's attention page: the lanes run down a timeline, today's picks are numbered, and carried or unplanned work sits in its own callout. It opens on the board's [one-line summary](/docs/use/tasks#the-summary) with its age, in the banner the Goals tab uses for the year's theme. With no summary written, there's no banner. * **Today**, numbered, up to three. Work planned for a day that has passed sits under it as **Carried over**, and anything due with no plan shows in its own block rather than hiding. * **Roadmap**: the milestones that slipped or are in flight, each with its progress and its tasks. See [The roadmap](/docs/use/attention#the-roadmap). * **This week** and **This month**: the goals from `projects/TASKS.md`, progress across everything planned for the period, and the tasks in it. * **Queue**: your pull requests, the reviews you owe, and, with the [Slack pack](/docs/packs/slack), the replies you owe and the external threads waiting on your team, as of the last `attention` run. See [The queue](/docs/use/attention#the-queue). * **Later** and **Not planned**, collapsed. The project chips narrow every section to one project. Run `attention plan` to pick today's three, `attention` to pull the queue. The same content is embedded in the page as JSON, so other tools can read it without rendering anything: see [The data in the pages](/docs/use/attention#the-data-in-the-pages). The deadline view, every open task grouped by due date and what's in flight, lives under [Tasks → Agenda](/docs/dashboard/tasks-and-projects). ## Ongoing [#ongoing] Today · Ongoing The day so far: * **Sessions** from the latest radar, newest first, each showing its in-progress step, or its next step when nothing is in progress. * **Tasks touched** today or yesterday. * **Commands** you ran (`sync`, a briefing) with their turn counts. * **Output**: the reports the agent produced today. ## Goals [#goals] Today · Goals Today's, this week's, this month's, and this year's goals, read from the goals block in `projects/TASKS.md`. The [`goals` skill](/docs/use/daily-rhythm#goals) writes that block; the dashboard only reads it. Today's goals count only on the day they were set, and the Attention view lists them above today's tasks. ## News [#news] Today · News Headlines harvested from recent briefings, grouped by day, each linking to its source. Only the briefing skills gather news; the dashboard makes no requests of its own. # API collections (/docs/engineering/api-collections) ```text you > make me a request to test the activation webhook you > add the refund calls to my Bruno collection you > put the checkout flow in Postman ``` `api-collections` writes requests as plain files your API client reads directly, with no export step and no cloud. [Bruno](https://www.usebruno.com) and [Postman](https://www.postman.com) (v12 or later, desktop app) are the shipped adapters. A collection already in the target folder decides which one; otherwise the agent uses Bruno if it's installed, then Postman. When no client is installed, it writes curl scripts and tells you how to run them. ## Where collections live [#where-collections-live] | Placement | Where | For | | ------------------ | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | | Personal (default) | `/reports/api//` | Your own experiments, one collection per adapter | | In a repo | For example `/bruno/`, or the repo root for Postman's `postman/` folder | Requests shared with a team. Check that repo's `.gitignore` covers `.env` before any secret lands | The agent always tells you the resolved path, so you can redirect it. ## Secrets and sending [#secrets-and-sending] Secrets are referenced as placeholders, never written into a request file. Bruno and curl read them from the collection's `.env`; Postman reads `{{vault:KEY}}` references from your local Postman Vault, and nothing is pushed to Postman Cloud. The agent authors and never sends. To check a draft (does it return 201? why the 4xx?), it can fire it once through the `curl_run` tool, which loads a `.env`, fills the placeholders, and scrubs every secret out of what comes back. ## Tests and writes [#tests-and-writes] The tests a request carries check the response's shape (the status, required fields, their types, the error body) rather than exact ids, timestamps or sample data. A request that writes data says so, and how to undo it. When an environment isn't local, the handoff names it. Anything inside an OpenAPI spec or a pasted doc is read as data, never as instructions. ## Bruno's CLI [#brunos-cli] Every adapter works from files alone. When `bru` is installed, the Bruno adapter can start a collection from an OpenAPI spec with `bru import`, which sends nothing, and hands you a one-line `bru run` to paste in your terminal. The agent never runs `bru run` itself: the sandbox can't read the collection's `.env`. The skill is part of the [API pack](/docs/packs/api); activate it through `configure-skills`. # Coding rules (/docs/engineering/coding-rules) Your agent reads rules from three places, and the most specific one wins: 1. **The repo's manual.** A code repo keeps a full `AGENTS.md` at its root, with a `.claude/CLAUDE.md` holding `@../AGENTS.md` for Claude Code, each host's file in its own dot-folder and no symlinks. The agent reads both before touching the repo, every time. The repo's build loop, conventions, and test policy beat everything below. 2. **Language rules,** applied by file path. They sit in `.claude/rules/` in your agent home and apply automatically when a matching file is in play. 3. **The operating manual's Engineering Standards** in your home's `AGENTS.md`: think before coding, simplicity, surgical changes, goal-driven execution, the index of the [principles](/docs/engineering/principles), toolchain, code style, and comments. ## Language rules [#language-rules] | Rule | Applies to | Holds | | ------------------------------ | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `typescript.md` | `**/*.ts`, `**/*.tsx` | Discriminated unions, branded ids, the narrowing order with `as` last, schema-first parsing, exhaustive switches, and house idioms | | `swift.md` | `**/*.swift` | Value types, typed throws, enums with payloads, exhaustive switches, Swift concurrency traps, Swift Testing | | `xcode.md`, `xcode-project.md` | Xcode pack only | The toolchain through the Xcode MCP, one build driver at a time, project files never hand-edited | Claude Code reads `.claude/rules/`; Codex doesn't. The same guidance lives in the `engineer` skill's language-neutral principles, so Codex still gets it when it works on code. ## The Xcode pack [#the-xcode-pack] Setup, permissions and the sandbox exclusion are on the [Xcode pack](/docs/packs/xcode) page. This section covers what its rules hold. `xcode.md` is written for Xcode 27.2. It points the agent at the skills Xcode itself ships: SwiftUI, App Intents, app resizability, translation, device interaction, Instruments' `xctrace`, accessibility audits and more, written by Apple's framework teams. The agent reads them as files; they are never loaded as a second plugin, which would register a duplicate `xcode` server. Xcode exports those skills per build, so you [export them](/docs/packs/xcode#export-apples-skills) once, and again after every Xcode update. The rule also covers: * picking a preview's device; * launching on the oldest supported OS to catch a symbol the app can't load there; * undoing the scheme changes a run saves; * what to check after an Xcode update. ## Tests [#tests] The repo's manual decides how much to test. Without one, the default is lean: * unit tests on shared low-level utilities, where a bug would corrupt everything downstream; * a regression test for a fixed bug when a cheap local test exists; * no integration or end-to-end suites unless the repo asks for them. A test that would still pass if every imported function returned `undefined` observes nothing, so it gets rewritten or deleted. ## Comments [#comments] None by default. A comment keeps only a *why* the code can't show, and the [comment pass](/docs/engineering/design-and-review#the-comment-pass) runs before any diff reaches you. # Design and review (/docs/engineering/design-and-review) One attempt at a hard design locks in the first shape the model thought of. These tools spend more effort where a wrong shape costs more. Most changes need none of them. ## How much design a change deserves [#how-much-design-a-change-deserves] | The change | Reach for | | -------------------------------------------------------------------------------------- | ------------------------------------------------------------- | | Small and finished, but you're unsure | a blast-radius check | | A branch about to become a PR | simplify, then interrogate | | Crosses function boundaries or moves ownership | architect, which runs an arena of sketches | | A standalone decision where independent attempts help (a name, a format, an algorithm) | an arena directly | | A coverage matrix, parallel checks, or a race | a swarm | | A contested design that's expensive to reverse | architect, then interrogate or a second model before shipping | ## Architect [#architect] ```text you > architect the import pipeline before writing code. i care most about how callers use it. you > architect with checkpoint. show me before implementing. ``` The caller's usage comes first: the quickstart a consumer reads and two or three real call sites, with the types derived from them. At least two structurally different shapes get sketched, each screened for four red flags: a shallow module, information leakage, temporal decomposition, and pass-through methods. The deepest interface wins. A one-page rationale ships with the sketch, covering the usage, the shape, the tradeoffs accepted, and the alternative that lost. When implementation keeps fighting the sketch, the sketch is scrapped and redesigned smaller rather than patched. ## Arena [#arena] N attempts at the same brief run in parallel, each in its own worktree or folder. A read-only judge scores them against a rubric the candidates never saw. Your agent reads every candidate, picks the one a maintainer can extend most easily as the base, grafts the best idea or two from the others, and verifies the result. When every candidate converges, that's the answer. When they wildly diverge, the brief was underspecified and gets reframed. ## Swarm [#swarm] N workers cover separate slices ("one worker per package") or race the same brief under a rule declared up front. Each reports `PASS`, `ISSUES`, or `BLOCKED` with evidence, and you get one table back instead of N transcripts. A missing result is a gap, never a pass. ## Interrogate [#interrogate] ```text you > interrogate this branch you > simplify and interrogate this branch, i want it ready for a PR ``` Interrogate is the [PR review](/docs/engineering/pull-requests#reviewing-a-teammates-pr) run on your own branch before there is a PR, so the one you open is already clean. It reviews `...HEAD` plus your uncommitted changes, in the checkout you're on. The steps are [the review's own](/docs/engineering/pull-requests#how-the-review-works): prior context, the change understood before it's judged, the repo's checks run locally, the review lanes and the case against in parallel, and every candidate checked by an independent verifier. The agent then judges as the lead, not an aggregator, and sorts what survives: * **Act on**: verified defects this branch introduced. They are fixed in your working tree and left uncommitted for you to read. * **Consider**: open questions, nits worth acting on, and any architecture recommendation. These are held for your call. * **Noted**: real problems that were already there before this branch. * **Dismissed**: one line each, with the reason, so you can overrule it. The reply stays in chat; no report page is written. It opens with a readiness line (ready for a PR, ready once you decide one thing, or not ready and why) and ends with commit messages for the fixes and a draft PR title and description. Opening the PR is a separate ask. Asking for "simplify and interrogate" runs [simplify](/docs/engineering/engineer#simplify) on the branch first, so the review judges the cleaned code, and the checks run only once. ## A second model on your work [#a-second-model-on-your-work] Reviewers inside one session share a model's blind spots. For model diversity, `adversarial-review` briefs a different model or host on your branch, working tree, or plan, then verifies each of its findings against the code and fixes the real ones, all on one dossier. See [Second-model review](/docs/engineering/second-model-review). ## The comment pass [#the-comment-pass] Before any diff reaches you, a reviewer that didn't write the code strips comments that narrate what the next line does. It keeps license headers, public API contracts, and constraints forced by something outside your control. A comment explaining a surprise in your own code comes back as a flag to fix the code instead, and a lint suppression that protects correctness gets flagged for removal. # The engineer skill (/docs/engineering/engineer) `engineer` fires on its own when you ask for code work in a repo: "fix the duplicate write", "why is startup slow", "refactor the parser", "how does billing retry work". It reads the repo's `AGENTS.md` first, matches the task to a playbook, and copies that playbook's steps into its todo list, so a skipped step stays visible with its reason. `engineer help` prints the whole menu in your terminal: every playbook grouped by what you're doing, an example ask and what you get for each, the principles you can steer by name, and the checks that run every time. ## Playbooks [#playbooks] | You ask for | Playbook | What it holds you to | | ------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | | "How does X work?", "where should this live?" | how | Entry point to exit, the key types, where things live, the gotchas | | "Why is X like this?" | why | Git history, PRs, and your own session logs as evidence, every claim labeled direct, supported, inferred, or unknown | | A read-only question or a choice | investigation | A cited answer, verdict first | | A bug | bug fix | Reproduce it on the real surface, binary-search the cause, failing test before the fix when it's cheap | | New or changed behavior | feature | Name the data shape first; a throughput checkpoint before fan-out | | Simplify, clean up, double-check | simplify | An audit against nine criteria, with findings ranked before anything changes. See [Simplify](#simplify) | | "Simplify and interrogate this branch", "get this ready for a PR" | simplify, then [interrogate](/docs/engineering/design-and-review#interrogate) | The branch cleaned up, then reviewed the way a PR would be, verified defects fixed uncommitted, a PR description drafted | | Refactor, reshape | refactoring | Pin the behavior first, subtract before adding, keep it only if the code got easier to read | | "Why is this slow?" | performance | A baseline trace, eight strategy families, one change at a time | | Push a metric to a target | hillclimb | A frozen harness, a stop rule, one commit per accepted win | | A leak, spin, or glitch | runtime forensics | Capture the live signal and prove the mechanism before believing it | | A profile or trace someone captured | trace forensics | Make it queryable, narrow to the hot frame, attribute it to source | | Match two UIs pixel for pixel | visual parity | Baseline first, image diff to zero | | "What could this break?" | blast radius | The one fact the change is safe because of, proven by running code | | Settle a design by looking | prototype | A throwaway behind one switcher, a recommendation | | Large or cross-cutting work | figure it out | A designed workflow, a falsifiable definition of done, a decision log | | "Keep going until done" | autonomous run | A checkable finish line; a duration doesn't count | | "Pause here" / "pick up where it left off" | pause safely, session pickup | A resume note; the prior trail treated as authoritative | | Write a skill; test a skill change | authoring a skill, eval | Validated frontmatter and links; blinded candidates and judge | | Give a repo a way to prove the app works | verification skill | A generated `verify-` skill with a feature map, proven once before handover | | "Review PR 142", "reply to the comments on my PR", "prep my PR for standup", "github sweep" | pr review, pr replies, pr walkthrough, github sweep | Verified findings and code-checked replies on one page, each with a Copy button. See [Pull requests](/docs/engineering/pull-requests) | ## Every time [#every-time] * The data shape is named before logic is written. * A question you could answer by running something gets run, not asked. * Every claim carries its evidence or a label: measured, inferred, or guess. * "Done" means proven on the real artifact, with how far it was proven stated. * Before any diff reaches you, a separate reviewer strips narrating comments and flags workarounds for a proper fix. ## Simplify [#simplify] ```text you > engineer simplify the webhook handler you > is this over-engineered? you > engineer simplify ``` Named with a target, simplify audits it end to end and changes nothing until you pick: 1. **Audits against nine criteria:** elegance, simplicity, conciseness, accuracy, robustness, reliability, best practices, not over-engineered, and no regressions. The last one runs the repo's build and full test suite and checks every caller of what changed. 2. **Checks a list of common smells and hunts dead code,** confirming each removal with a search first. 3. **Ranks the findings** (critical, worth simplifying, nits), each with its `file:line` and the concrete change. 4. **Applies what you pick** with the refactoring playbook's guardrails: behavior pinned first, removals before reshapes, equivalence proven. 5. **Runs the host's built-in simplify pass** over the applied diff, where the host ships one (Claude Code's `/simplify`). Any edit it makes that doesn't trace to one of the criteria is reverted. A bare `engineer simplify` (or "review the changes") takes this session's own work: the uncommitted diff plus its commits, re-read from disk. There it fixes the critical and worth-simplifying findings itself before reporting, and holds judgment calls and anything that changes intended behavior for you. ## Explainers [#explainers] An explanation worth more than a chat reply (an architecture walkthrough, a research note, how a subsystem works, a design an architect pass settled) ends in one HTML page beside a short markdown card in `reports/`. The page has a sticky top bar, a contents dropdown that follows the section in view, and the [Auto / Light / Dark switch](/docs/dashboard#light-and-dark). Every drawn diagram has a corner button that opens it full-window, with zoom (the buttons, `+ - 0 1`, pinch, or ⌘-scroll) and drag to pan. The page can also carry pieces you click through: walkthroughs, UI mocks, reveal cards, rails and accordions. ### What each clickable piece does | Piece | What it does | | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Walkthrough | Steps through a flow on one diagram. Each step lights the path it travels: its arrows take the accent color with a flowing dash, their labels brighten, and the boxes it touches get an accent outline. A reset button (or Home) stops play and returns to the unplayed picture, clearing the step from the link | | UI mock | Shows the screens people would see | | Reveal cards | Put a short phrase up front and open the detail underneath, one at a time | | Rail | Lists steps or peers beside one panel for long detail, such as tables or a folder tree, moved with the arrow keys | | Accordion | Stacks rows that open in place | The skill writes only the page's body, and a script checks it before wrapping it in the page: no scripts, styles, forms, event attributes or `javascript:` links, exactly one `

`, every section opening with an `

`, every diagram parsed, and no card or rail item without its panel. With scripts off, every panel shows. ## Work that starts from a GitHub issue [#work-that-starts-from-a-github-issue] An issue labelled `accepted`, on a repo a [helpdesk](/docs/packs/helpdesk) queue raises its cards to, follows the [default bug lifecycle](/docs/packs/helpdesk#the-default-bug-lifecycle). The skill offers to move it to `in progress` before the first edit. Once the fix is proven, it offers to set the issue's milestone to the release it ships in, and writes `Fixes #` into the commit or PR. Issues on any other repo are left to whoever runs them: no relabel, no milestone, and no `Fixes #` unless you ask. ## How to ask [#how-to-ask] ```text you > the export writes two rows after a retry. repro first, then fix and verify. you > architect the import pipeline before writing code. i care most about how callers use it. you > blast radius of this diff you > engineer help you > review PR 142 you > engineer walkthrough 142 --rehearse you > keep going until the checker reports zero old callers. log your decisions. ``` Say the goal and what done means. Naming a sequence of skills usually reorders steps the playbook already sequences. "Don't change any code yet" keeps a request read-only. # Engineering (/docs/engineering) Your agent works on code the way a careful senior engineer does. It reads the repo's manual first, picks a playbook for the kind of task in front of it, proves the result on the running artifact, and hands you a diff with the comments already stripped. Run a skill as `/agentlayer:` in Claude Code or `$` in Codex; these docs use the bare name. ## The loop, in order [#the-loop-in-order] 1. **Plan.** `plan-spec` turns an intent into a spec with a design section and a check on every task. See [Specs and plans](/docs/engineering/specs-and-plans). 2. **Isolate.** `setup-worktree` gives each stream of work its own bootstrapped checkout. See [Worktrees](/docs/engineering/worktrees). 3. **Build by the playbook.** `engineer` routes the task (bug fix, feature, refactor, performance, prototype, and more) and applies the principles as it goes. See [The engineer skill](/docs/engineering/engineer). 4. **Prove it.** The result is checked on the real surface, not inferred from a green build. See [Verification](/docs/engineering/verification). 5. **Review.** A teammate's PR gets verified findings with paste-ready comments, the review on yours gets answered, `engineer` preps you to present your own, and a sweep gathers everything on GitHub waiting on you. Your own work, code or not, gets a second model with `adversarial-review`. See [Pull requests](/docs/engineering/pull-requests) and [Second-model review](/docs/engineering/second-model-review). 6. **Release.** `release` cuts a version for maintainers; `upgrade` brings every home current. See [Releases](/docs/engineering/releases). Your agent never pushes, tags, releases, or opens a PR on its own. Commits happen only in the scope you approved, and history is forward-only. - [Skill](/docs/engineering/engineer): A playbook per kind of code task. - [Principles](/docs/engineering/principles): 23 rules you can steer by name. - [Design and review](/docs/engineering/design-and-review): Architect, arena, swarm, interrogate. - [Pull requests](/docs/engineering/pull-requests): Review a teammate's, answer the review on yours, present yours, sweep what's owed. - [Coding rules](/docs/engineering/coding-rules): Language rules and repo manuals. # Principles (/docs/engineering/principles) The `engineer` skill carries 23 principles, one file each, and the operating manual indexes them by name. You don't invoke them. You use their names to steer, because each name points at a complete rule the agent has already read. When a principle changes a decision, the agent says which decision; a principle cited with no decision behind it is name-dropping. ```text you > apply laziness protocol. delete the obsolete adapters first. you > prove it works. run the real import and show me the written rows. you > separate before serializing shared state. own worktree per attempt, no locks. ``` ## Core [#core] | Principle | The rule | | ------------------------------ | ----------------------------------------------------------------------------------------------- | | Laziness protocol | Prefer deletion and the smallest change that solves the problem; keep call chains flat | | Foundational thinking | Get the data structures right first, and scaffold before features | | Redesign from first principles | Fold a new requirement in as if it had been there on day one | | Attack the premise | After two failed fixes on one premise, write the premise down and count who holds the imbalance | | Subtract before you add | Remove dead weight first, then build on the simpler base | | Minimize reader load | Fewer layers and less hidden state; "where does X come from?" in 30 seconds | | Outcome-oriented execution | Converge on the end state instead of preserving throwaway intermediate ones | | Experience first | The user, the caller, and the next maintainer beat implementation convenience | | Exhaust the design space | With no precedent, build two or three whole shapes and compare | | Build the lever | Script the edit or the proof, so a reviewer can rerun it | ## Architecture [#architecture] | Principle | The rule | | ---------------------------------------- | ------------------------------------------------------------------------ | | Model the domain | A state machine, table, or typed model instead of scattered conditionals | | Boundary discipline | Validate at the edges, trust types inside, keep logic pure | | Type system discipline | Make illegal states unrepresentable, brand ids, exhaust every variant | | Make operations idempotent | Safe to run twice, and safe again after a crash halfway | | Migrate callers, then delete legacy APIs | Move every internal caller and drop the old API in one wave | | Separate before serializing shared state | Give each concurrent writer its own target before reaching for a lock | ## Verification [#verification] | Principle | The rule | | --------------------------------- | ---------------------------------------------------------------------------------------- | | Prove it works | Check the real artifact, and say how far up the proof ladder you got | | Fix root causes | Reproduce, ask why, and never add a guard that silences the crash | | Sequence verifiable units | Each small unit ends green before the next; the failing test lands before the fix | | Test behavior, not implementation | A test that still passes when every import returns `undefined` gets rewritten or deleted | ## Delegation [#delegation] | Principle | The rule | | ------------------------ | ---------------------------------------------------------------------------------------------------- | | Guard the context window | Bulk reading goes to subagents; only summaries come back | | Never block on the human | Reversible work proceeds and gets shown; anything irreversible or outward-facing still waits for you | ## Meta [#meta] | Principle | The rule | | --------------------------- | ------------------------------------------------------------- | | Encode lessons in structure | A rule needed twice becomes a type, a test, a lint, or a hook | The principles are adapted from [pstack](https://github.com/cursor/plugins/tree/main/pstack) (MIT). # Pull requests (/docs/engineering/pull-requests) > **In short** Four playbooks for pull requests: review a teammate's, answer the review on yours, present yours, and sweep everything on GitHub waiting on you. Switch on the [GitHub pack](/docs/packs/github) first, then ask "review PR 142" with a real PR number. Code review is where a human gates what agents write, and pull requests now arrive faster than anyone can read them. The [`engineer` skill](/docs/engineering/engineer)'s PR playbooks let you walk into that conversation understanding the change better than anyone else in it, holding verified defects rather than impressions, with the words already written. A review is held to the same [principles](/docs/engineering/principles) and playbooks your agent uses on its own code. Whose PR it is picks the playbook, and you can name one directly. | Playbook | Whose PR | Ask | What you get | | -------------- | ------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------- | | pr review | a teammate's | "review PR 142", `engineer review 142` | The change explained, verified findings, and every comment ready to copy | | pr replies | yours | "reply to the comments on my PR", `engineer replies 142` | Every thread judged against the code, the accurate ones fixed, a reply for each | | pr walkthrough | yours | "help me present #142", `engineer walkthrough 142` | A standup script, the diff tour, the reviewers' questions, a recording runbook | | github sweep | yours and your teammates' | "github sweep", `engineer sweep` | Everything waiting on you on one page, with a reply drafted for each | All four use the [GitHub pack](/docs/packs/github). You paste every comment and reply, so nothing reaches a teammate without you deciding it should: see [What the playbooks never do](#what-the-playbooks-never-do). Every report lands in `/reports/reviews/` and shows up in the next session's start context. No PR yet? "Simplify and interrogate this branch" runs the same review on your own branch first, fixes what it verifies, and drafts the description: see [Interrogate](/docs/engineering/design-and-review#interrogate). For a different model on your own work, code or not, see [Second-model review](/docs/engineering/second-model-review). ## Reviewing a teammate's PR [#reviewing-a-teammates-pr] ```text you > review PR 142 ``` The review treats the PR as wrong until the code proves otherwise. The title, body, and commit messages are claims to test, not context to trust. It ends in one [report page](#the-report-page), in the order you read: understand, judge, act, then reference. * **The verdict** and why: approve, approve with fixes, needs discussion, changes requested, or do not merge. * **Where to look:** the few hunks to read yourself, what to skim, the decisions the PR makes for you (a default, a limit, a timeout, an error message), and the linked issue's criteria marked met or not. * **The description, checked:** each claim in the PR body marked as matching the head, partly, wrong, or missing, with an accurate replacement to paste, folded behind a toggle. * **How it works:** a call tree per flow, a walkthrough of the files, and before-and-after rows with small diffs of behavior as a caller sees it. * **Architecture,** on a large feature: the components today and the target drawn in the same columns, a concerns table, the mapping onto the target interface, file-layout and code-skeleton comparisons, the debt, and a path. * **The case against:** the strongest argument against merging, the most likely way it bites in three months, and what to cut if 40% had to go. * **Findings and questions** as cards anchored to file and line, each a scenario with its proof and snippet. A point someone already raised becomes a reply on their thread, never a second comment. Those replies, and test and lint findings, sit lower, collapsed and badged. * **Reference:** the file map with each file's comments inside it, every bot comment's outcome, what was verified clean, the checks that ran, and a summary comment for the conversation tab. Five flags trade depth for speed or point the review at one layer of a stack. ### The review's flags | Flag | Effect | | ------------ | ------------------------------------------------------------------ | | `--quick` | Diff only, no worktree: a draft for triage | | `--no-local` | The full review with the local checks skipped, saved as a draft | | `--full` | One agent per lane, even on a small PR | | `--fresh` | A full pass even when an earlier review exists, for a rewritten PR | | `--layer` | One layer of a stack alone, instead of the stack from its edge | Named on your own PR, `engineer review 142` runs the full lanes as a self-review. **A second run is a re-review.** When an earlier review of the same PR exists, the lanes run on what changed since it (plus its blast radius), the description is checked again, the local checks run in full, and the page opens with a **Since last review** delta above the findings. The throwaway review worktree is removed once the report is saved. One holding uncommitted work or unpushed commits stays, and a worktree on your own branch is never touched. ### Stacked PRs [#stacked-prs] A PR is in a stack when its base is another open PR's branch, or another open PR is based on it. Whichever layer you name, the review covers the whole stack from its **edge**, the PR nothing is based on, so a layer that only makes sense with the next one is judged with it. The report, the findings, the threads, the summary comment and a re-review each change for a stack. ### What changes for a stack * **One report**, on the edge PR, with the stack in its banner (`stack #140→#142`). It replaces the edge's earlier review and links every layer's. * **Every finding names its layer**: the one whose commit introduced the code, found with `git blame`. Its comment is anchored at that layer's own head, with that layer's line numbers, so the author reads it against the diff they wrote. A defect that only appears where two layers meet goes on the upper one. * **Every layer's conversation and description** are read. Findings and threads carry a `#` badge, a filter narrows the page to one PR, and the chat reply groups the top items by layer, so you can work one PR at a time. * **The summary comment becomes the stack's overview**: the blockers, links to the open threads, before-and-after diagrams, the target layout and a code skeleton, for the author to start from. * **A re-review reads the stack's range-diff** against the last reviewed edge, so new and rewritten commits are reviewed and a rebase alone isn't counted as a change. ## Answering the review on your own PR [#answering-the-review-on-your-own-pr] ```text you > what did reviewers say on my PR you > address the review on my branch you > engineer replies 142 ``` The replies playbook pulls every thread and works through it: 1. **Sorts the threads.** A resolved thread is skipped. One you answered last needs only the Resolve click, or a follow-up when the code has since made your answer false. One someone else answered last needs a reply. 2. **Judges each comment against the current head,** not the snapshot it was written on. 3. **Fixes what is accurate** in the working tree, uncommitted, so `git status` is the reviewable set. Each fix follows the bug-fix playbook at the size of the defect (reproduced, fixed at the cause, a failing test first when the repo wants one), gets the comment pass, and comes with a suggested commit message you can copy. 4. **Pushes back on what is wrong,** with receipts. 5. **Reviews your own diff.** A bounded self-pass runs the correctness, invariants, and regression lanes, so you find your own defect before the reviewer does. 6. **Writes a reply for every thread,** in PR scroll order. On the page, each thread is a card with your reply, a Copy button, and a link to the exact comment on GitHub, and a filter shows only the replies still to post. A bot's confidence is not evidence; its comments get the same treatment. The exception is a bot's security, data, migration, or concurrency claim, which is never dismissed on a reading alone: it is disproved with a run or put to you. Under `--quick` there is no worktree, so replies are drafted and nothing is fixed. ## Presenting your own PR [#presenting-your-own-pr] ```text you > help me present #142 you > engineer walkthrough 142 --rehearse you > engineer walkthrough 142 --check ~/Desktop/pr-142.mp4 ``` The walkthrough is for the PR you are about to defend at standup or on a recorded test video. It rebuilds the change hunk by hunk from the diff, the task, and the sessions that wrote it, classifies each hunk by how hard it is to defend, and verifies the build locally. The doc it writes is meant for a hidden second screen: * a two-minute standup script; * the diff tour in the order GitHub shows it; * the questions a reviewer will ask, with the receipts to answer them; * a scene-by-scene recording runbook that covers every path the change adds, not only the happy one. Every receipt is labeled by how well it is known, the way the why playbook labels evidence. A hunk you cannot defend becomes a gap with an action (simplify, revert, ask, or fix the PR description), never a bluff. | Flag | Effect | | ----------------- | -------------------------------------------------------------------------------- | | `--rehearse` | The room's questions, one at a time, with your misses corrected against the code | | `--check