# Overview (/docs) The agent installs as a plugin into the agent CLI you already use, Claude Code or Codex. Everything that makes it *yours* (character, memory, knowledge, projects, tasks) lives in one folder of plain markdown on your disk. Any model can read it. You can browse it in Obsidian, commit it to git, and take it with you if you ever change hosts. It is not a chat wrapper. It is an operating system for one agent: a 56-tool MCP server, 39 skills, four hooks, and a knowledge pipeline that turns every conversation into structured, queryable memory. The open-source plugin behind it is `agent-kevin`. ## Three layers [#three-layers] The product is one progression, and the docs follow it. | Layer | What it is | Start with | | ------------------------- | ---------------------------------------------------------------------------------------- | ------------------------------------------- | | **01 Platform · Context** | The brain: the home folder, the compile pipeline, memory, capture, seed bundles | [The agent home](/docs/platform/agent-home) | | **02 Agent · Harness** | The agent that loads that context: hosts, hooks, permissions, tasks, cadences, worktrees | [Hosts](/docs/agent/hosts) | | **03 Modules · Powers** | What it can do and what it can reach: skills, tools, packs | [Skills](/docs/modules/skills) | The [dashboard](/docs/dashboard) renders all three as one static page: the operator surface. ## The loop [#the-loop] ```mermaid graph LR A[Sessions] -->|capture| B[Knowledge] B -->|informs| C[Projects] C -->|generate| D[Results] D -->|feed back into| A ``` Every session is captured on exit. Captured sessions compile into a wiki. The wiki loads before you type a word in the next session. That loop is the whole product; the skills and tools exist to feed it and to act on what it knows. ## How it behaves [#how-it-behaves] * **You drive.** Every bundled skill waits for you to invoke it. A handful of read-only helpers (dashboard, where-am-i, find-session, standup, api-collections, roadmap) may run when a request clearly calls for them, and none of them mutates state. * **Subscription-billed.** The MCP server returns prompts; your own session does the thinking. Nothing bills a metered API key. See [Hosts](/docs/agent/hosts#billing). * **Local by default.** No cloud sync unless you commit the folder somewhere. Secrets sit in a deny-gated store the agent's own tools cannot read. * **One plugin, many homes.** A personal agent, a work agent, an SEO agent: same install, separate brains, told apart by the folder you launch from. ## What can it do? [#what-can-it-do] The capabilities, grouped by what they are for. Start with the group that matches the work in front of you. - [Plan and run](/docs/modules/plan-and-run): Projects and tasks, roadmap, goals, briefings, the session radar. - [Build and ship](/docs/modules/build-and-ship): Worktrees, pull-request review, API collections, deploy checks. - [Reach and see](/docs/modules/reach-and-see): Browser, logs, database, search, chat, support desk, SEO. - [Brain and memory](/docs/modules/brain-and-memory): Capture, compile, self-review, sync, seed bundles. ## Start here [#start-here] - [Install](/docs/getting-started/install): Prerequisites and the two-minute marketplace install. - [Onboarding](/docs/getting-started/onboarding): What the init wizard asks and what it writes. - [The brain](/docs/platform/the-brain): How raw sessions become compiled memory. - [The harness](/docs/agent): Hosts, hooks, permissions, and what gets recorded. - [Every capability](/docs/modules): Skills, tools, and packs, grouped by what they do. - [Dashboard](/docs/dashboard): The one-file mission-control page, and a live demo. Reading with a model? The whole site is also served as [llms.txt](/llms.txt) (the index) and [llms-full.txt](/llms-full.txt) (every page as Markdown). > The plugin is named after Kevin, the loyal minion. Your agent does not have to be. See [Naming](/docs/reference/naming). # 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/agent/hosts#adding-a-host) Open an issue first for architectural changes. Kevin's contract with the markdown home is intentional and worth preserving. ## The dev loop [#the-dev-loop] ```bash git clone https://github.com/AgentLayer1/agent-kevin ~/Developer/agent-kevin cd ~/Developer/agent-kevin/mcp-server && bun install bun src/server.ts # boot check: the banner reports the tool count bun run typecheck ``` Register the clone as a local marketplace on your host (see [Install](/docs/getting-started/install#from-a-clone)). Skill-body edits go live on the next session; new skills or hooks need a full relaunch. **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:** `defineTool` in `mcp-server/src/tools/`, register it in the module list, add its `mcp__plugin_agent-kevin_kevin__` permission. PR conventions: focused changes, update docs when counts change, no unjustified dependencies, typecheck passes. Full detail in [CONTRIBUTING.md](https://github.com/AgentLayer1/agent-kevin/blob/main/CONTRIBUTING.md). ## License [#license] Apache 2.0. `agent-kevin` 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, `bun install`, 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-add the marketplace and re-install (`/plugin marketplace add github:AgentLayer1/agentlayer-agent-marketplace`, `/plugin install agent-kevin@agentlayer`), then relaunch. In Codex, trust the folder and run `/hooks` to trust the four Kevin entries. ### I already had a CLAUDE.md or AGENTS.md here. Was it overwritten? No. Kevin'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/getting-started/updating). ### How do I uninstall? `/plugin uninstall agent-kevin@agentlayer` in Claude Code, `codex plugin remove agent-kevin@agentlayer` in Codex. Your home stays. To purge everything, delete the home directory. ### Will Kevin 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/agent/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/agent/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 a `KEVIN_*` variable machine-wide. See [Multiple agents](/docs/platform/multiple-agents). ### Can I use one home from both hosts? Yes. Create it from Claude Code, run `$upgrade` once from Codex, and sessions from either land in the same brain. See [Hosts](/docs/agent/hosts). ### Can I use a different model or host? The brain is plain markdown and `AGENTS.md` is harness-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/agent/hosts#adding-a-host) page. # What Kevin used to be (/docs/about/history) Kevin started life as a much more ambitious thing: a standalone Bun daemon running a Telegram bot for the whole family, a cron-style heartbeat that woke Kevin at 7am to send morning briefings, evening wraps that arrived while you were cooking dinner, a homeschool planner that produced printable HTML for the kids before the school week, autonomous knowledge compiles every six hours. The brain was the same markdown folder you see today. The body was a long-running process talking to the Claude Agent SDK on your behalf, reachable from your phone, the office, the car. Then Anthropic [closed off](https://www.anthropic.com/news/claude-developer-platform) the Agent SDK from subscription billing. Headless SDK calls became pay-per-token only. The whole point of Kevin was that it ran on a flat monthly subscription, not "what did Kevin do while you were sleeping". Without a subscription-backed SDK the daemon model could not survive. So Kevin was reborn as a plugin, first for Claude Code, then for Codex. The brain is intact. 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 is structured to make the host do the model work, never the plugin itself. | Kept | Gone | | -------------------------------------------- | ----------------------------------------------------------------------------- | | Memory compounding, the wiki pipeline | Proactive messaging at 7am | | Projects, tasks, audits, briefings on demand | The Telegram bridge | | Everything file-based and portable | The cron daemon (external schedulers can run a headless host, on API billing) | If the Agent SDK ever reopens to subscription billing, the daemon comes back. Until then, this plugin is the maximum amount of Kevin that 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 | Chromium auto-install via Playwright is sometimes flaky in headless sandboxes; run `playwright install-deps chromium` once on a fresh distro | | **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; a few pack-gated skills assume tools Git Bash lacks (`serpapi` pipes through `jq`). 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. **Browser launch can fail in sandboxed subprocesses** on macOS. Install Playwright's Chromium once from a normal terminal so it caches. 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. **No proactive Kevin.** You start every session. External schedulers can run a headless host, but those calls bill the API, not your plan. See [The host does the thinking](/docs/agent/hosts#billing). # Privacy (/docs/about/privacy) * **All data stays local.** The home is markdown on your disk. No cloud sync unless you commit it somewhere. * **Secrets live in the deny-gated `.kevin/secrets/.env`**: API keys, database connection strings, Google OAuth. Non-secret config lives in `.claude/settings.local.json`, runtime state in `.kevin/`. All gitignored by default, and Kevin's own shell is blocked from reading the secrets store on both hosts. * **Transcripts are redacted before persisting.** Session capture exact-matches every value in the secrets store and the local settings, and runs prefix heuristics for common key formats. * **Nothing on the dashboard leaves your machine.** The page makes zero external requests: no CDN, no webfonts, no analytics. * **Keys never enter chat.** Neither init nor `configure-skills` asks for a credential in conversation, because a pasted secret would land in the transcript and the model API. You fill values in your editor. * **Training opt-out and telemetry off** are recommended on your host. Claude Code: [docs.claude.com](https://docs.claude.com). Codex: the user-level note the plugin generates carries the analytics and telemetry keys. * **The folder is the product.** If anything goes wrong, the markdown plus its git history is the complete backup. > **Keep homes private** `dashboard.html` sits at the home root and reflects your tasks, knowledge stats, and redacted settings. If you publish the home repo, it publishes too. # Architecture (/docs/agent/architecture) ```mermaid graph LR YOU["You"] HOST["Claude Code / Codex"] PLUGIN["agent-kevin plugin
MCP server · skills · hooks"] BRAIN["Brain
your markdown home"] OBS["Obsidian"] TERM["Terminal"] EXT["External services
GSC · PageSpeed · SerpAPI
OpenPageRank · Perplexity · Chromium"] YOU <-->|chat| HOST HOST <-->|plugin loaded| PLUGIN PLUGIN -->|reads + writes| BRAIN PLUGIN -.->|hooks capture sessions| BRAIN PLUGIN -->|dispatch with your keys| EXT TERM -->|bin/kevin CLI| BRAIN BRAIN -->|browse| OBS ``` | Layer | What | Where | | --------------------- | ------------------------------------------------------------------- | ------------------------------------------------------------------- | | **You** | The decision maker | wherever you are | | **Host** | The AI runtime that reads the brain and acts on it | Claude Code or Codex in your terminal | | **Plugin** | Skill bodies, the MCP server, hooks | one repo, many homes | | **Brain** | Personality, knowledge, projects: everything that makes Kevin yours | `/`, portable markdown | | **Obsidian** | Human-facing browser for the brain | `/` opened as a vault | | **Terminal** | Bypass route for scripted task ops and headless compile prep | `bin/kevin` | | **External services** | Optional tools the MCP server calls with your keys | GSC, PageSpeed, SerpAPI, OpenPageRank, Perplexity, bundled Chromium | ## Why the model never runs inside the plugin [#why-the-model-never-runs-inside-the-plugin] Other personal-AI setups call the LLM internally, which bills a metered API key. Kevin does not. Tools do I/O and return prompts; your own session does the thinking on your host's plan. This shapes everything: compile is a loop your session drives, briefings are skills you invoke, and there is no daemon waking up at 7am. The trade-off is that Kevin is reactive, never proactive. See [The host does the thinking](/docs/agent/hosts#billing) and [History](/docs/about/history). ## The plugin repo [#the-plugin-repo] ```text agent-kevin/ ├── .claude-plugin/ │ ├── plugin.json # Claude Code manifest: skills/, hooks/claude.json, the kevin MCP server │ └── marketplace.json # developer marketplace (agentdev-kevin) so a clone installs ├── .codex-plugin/plugin.json # Codex manifest: the same skills/ (hooks + server register per home) ├── .agents/plugins/marketplace.json # the same developer marketplace for Codex ├── bin/kevin # standalone CLI ├── hooks/claude.json # SessionStart · SessionEnd · PreCompact · PreToolUse guard ├── mcp-server/ # the kevin MCP server (Bun) ├── skills/ # 38 skills; per-version migrations in skills/upgrade/scripts/ ├── templates/ # init copies these into ├── CHANGELOG.md # release contract: Upgrade blocks drive /upgrade └── LICENSE · NOTICE # Apache 2.0 ``` ## Two hosts, one home [#two-hosts-one-home] The home does not care which CLI opened it. Claude Code gets bundled hooks and a bundled MCP server from the plugin manifest. Codex, whose plugins cannot yet carry hooks or a server that knows its home, gets the same entry points wired per home into `.codex/`. A session ended in one host is in the other's context next time. What every host provides, and what a new one needs: [Hosts](/docs/agent/hosts). # Claude Code (/docs/agent/claude-code) Claude Code is where Kevin was built and where every feature is exercised first. The plugin manifest registers the skills, the four hooks, and the `kevin` MCP server, so a session launched from a home gets all of it with no per-home wiring. | | | | ---------------------------- | ----------------------------------------------------------------------------------------- | | Launch | `claude` from the home | | Skills | `/agent-kevin:` | | Manual | `AGENTS.md` through the `@`-imports in `.claude/CLAUDE.md` | | Hooks and MCP server | Bundled with the plugin | | Settings | `.claude/settings.json` (permissions) and `.claude/settings.local.json` (env, gitignored) | | Reload after a plugin update | `/reload-plugins`; new hooks need a full relaunch | ## Hooks [#hooks] The four hooks ship in the plugin's `hooks/claude.json`. Claude Code runs a plugin's hooks only for sessions started where the plugin is enabled, so a session can only ever be captured by the agent whose home it launched in. See [Hooks](/docs/agent/hooks) for what each one does. > **Do not add capture hooks to ~/.claude/settings.json** Earlier versions recommended machine-wide hooks routed by a `KEVIN_HOME` variable. That hands every session on the box to one brain. Plugin hooks are the only supported path. ## Permissions and the sandbox [#permissions-and-the-sandbox] Init pre-grants the always-on core tools in `settings.json`. Pack tools land there only when you activate the pack through `configure-skills`, so the file stays an accurate audit trail. A few entries sit in `permissions.ask` (`git push`, `gh pr create`, `curl_run`, `seed_import`): an ask rule is evaluated before Claude Code's auto-mode classifier and cannot be approved past, which makes it the one durable form of "nothing leaves this machine without a human". The Bash tool runs under a sandbox that denies reads of `.kevin/secrets/` and every `.env`. The MCP server runs outside that sandbox, which is how the GitHub tools, worktree setup, and the upgrade scripts do the writes the seatbelt blocks. See [MCP tools](/docs/modules/mcp-tools). ## Memory routing [#memory-routing] Claude Code ships an auto-memory directory under `~/.claude/projects/`. Kevin does not use it. The `.claude/CLAUDE.md` bridge overrides that instruction so every correction, preference, project fact, and reference routes into the `knowledge/` tree, which is what stays portable across hosts and what every other tool in the home reads. ## Multiple accounts [#multiple-accounts] `/login` is a single slot per OS user, so on its own it cannot keep two homes on two subscriptions. `CLAUDE_CODE_OAUTH_TOKEN` can: it sits above the login slot in credential precedence, and each session resolves its own `settings.local.json` env block at launch. ```bash # /login as account A, then: claude setup-token # OAuth flow, prints a token for account A # put it in home A's settings.local.json; repeat for account B and home B ``` ```json { "env": { "CLAUDE_CODE_OAUTH_TOKEN": "sk-ant-oat01-..." } } ``` This is the one credential that lives in `settings.local.json` rather than the secrets store, because Claude Code consumes it at launch, before Kevin's tools exist. The file is gitignored. Gotchas: switch `/login` between mints or you get two tokens for one account; the env block is read at launch, so restart after adding it; an `ANTHROPIC_API_KEY` in your shell rc silently outranks the token; verify with independent `/usage` meters, not the shell. ## Verifying subscription billing [#verifying-subscription-billing] The [host does the thinking](/docs/agent/hosts#billing), so nothing bills the API. To see it: open Anthropic Console → Usage and note the API cost, run the `knowledge-compile` skill, refresh. API cost should not change. Subscription usage should increment. If it does change, open an issue. ## Recommended settings [#recommended-settings] * `CLAUDE_CODE_NO_FLICKER=1` in your user-level env block turns on the fullscreen renderer: click-to-position in the prompt, no flicker, flat memory in long sessions. See [Terminal](/docs/workstation/terminal). * Training opt-out and telemetry off on your Claude Code install. See [Privacy](/docs/about/privacy). # Codex (/docs/agent/codex) Since 0.4.1 the agent-kevin checkout is also a Codex plugin. The skills are the same files. What differs is the wiring: Codex plugins cannot yet carry hooks or a bundled MCP server that knows which home it serves, so both are generated per home into `.codex/`. | | | | ---------------------------- | --------------------------------------------------------------------------------------------------------------------- | | Launch | `codex` from the home | | Skills | `$` | | Manual | `AGENTS.md`, read natively | | Hooks and MCP server | Generated per home into `.codex/` | | Settings | The home's `.claude/settings.json` and `settings.local.json`, projected into `.codex/config.toml` and `.codex/rules/` | | Reload after a plugin update | Remove and re-add the plugin, then `$upgrade` | ## Setting up a home [#setting-up-a-home] Install the plugin as on the [Install](/docs/getting-started/install) page. Then, from a home that already exists: ```bash cd ~/Documents/Agents/Kevin codex ``` Run `$upgrade` there (or `/agent-kevin:upgrade` from Claude Code, which asks whether the home also runs Codex). Either writes the wiring below. Trust the folder and the hook entries once via `/hooks`. > **Create the home from Claude Code for now** A brand-new home created with `$init` under Codex is not exercised yet. Scaffold it from Claude Code, then open it from Codex. ## What gets wired [#what-gets-wired] ```text /.codex/ ├── hooks.json # SessionStart context · SessionEnd + PreCompact capture · PreToolUse guard ├── config.toml # [mcp_servers.kevin] with AGENT_HOME · [permissions.kevin] profile · shell env policy · [tui] status line └── rules/kevin.rules # one prefix_rule per Bash(…) entry in the Claude settings' ask list ``` | Piece | What it does | | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `SessionStart` hook | Delivers the whole static stack (identity files, indexes, task board) plus the same dynamic lane Claude gets, as one payload. Registered with `additionalContextLimit: 0`, since Codex otherwise truncates a hook at about 2,500 tokens | | `SessionEnd` + `PreCompact` | Capture from Codex's rollout JSONL: user and assistant turns only, with injected `AGENTS.md`, environment block, and `$skill` expansions dropped | | `PreToolUse` | The same cwd-drift guard; Codex presents shell commands to hooks as `Bash`, the same contract | | `[mcp_servers.kevin]` | The plugin's MCP server registered per home with `--home=` pinned, so an inherited override cannot outrank it | | `[permissions.kevin]` | A profile generated from the home's settings: denies every read of `.kevin/secrets/` and any `.env`, keeps `.git` writable so commits stay routine, lists the code path and `additionalDirectories` as workspace roots | | `rules/kevin.rules` | Every `Bash(…)` pattern in `permissions.ask` becomes a prompt, with `approvals_reviewer = "user"` so a human answers | | `[shell_environment_policy]` | Hands the model's shell the home variables and the home's `AGENT_*` settings, never a key or token | The generator merges into existing files, replaces only Kevin's own entries, and validates the TOML before writing. Codex reads the home's `AGENTS.md` natively, so the manual needs no bridge file. ## User-level settings [#user-level-settings] Some keys belong in `~/.codex/config.toml` rather than a home: telemetry and provider keys, which Codex ignores in a project config, plus analytics, feedback, terminal animation, and update checks, which describe your machine rather than an agent, and the model context window, a cost choice for every session on the machine (the note asks for the cap Codex's model catalog serves, since a larger request is silently clamped to it). The home's own footer status line (model, directory, branch, approval mode, context used) is written into its `.codex/config.toml` by init and upgrade; a status line you already set there is kept. The plugin never writes a user-level file. Init and upgrade generate a paste-ready note at `.kevin/updates/codex-user-config.md` built from your Claude Code user-level settings, and until you paste it, the home's own profile carries the user-level denies too. Nothing in the note names an agent. ## Sessions are shared [#sessions-are-shared] A session ended in Codex is in Claude Code's context next time, and the other way round. Session blocks record which harness and model produced them. ## Updating [#updating] Codex installs a copy of the checkout into its plugin cache, so after pulling new code: ```bash codex plugin remove agent-kevin@agentdev-kevin && codex plugin add agent-kevin@agentdev-kevin ``` Then `$upgrade` from the home. Hook commands rarely change; the report says `hooks.changed: true` when you need to re-trust. ## Current limits [#current-limits] * Skills that name `${CLAUDE_PLUGIN_ROOT}` resolve it through the plugin-root line in the SessionStart header, an instruction rather than a shell variable. * The session radar (`where-am-i`, `find-session`) reads Claude transcripts only. * The profile enables the network inside the sandbox, since an approved escalation does not lift a profile; the outbound gate is the rules file alone. Domain allowlists need Codex's experimental network proxy. * The reviewer model (`auto_review`) stays opt-in; on this plugin's tests it denied a named push and a local commit. * Native Windows under Codex is unverified: the wiring is shaped to parse under PowerShell, but the skills are bash. # Configuration (/docs/agent/configuration) ## Two spellings per knob [#two-spellings-per-knob] Every variable has an agent-neutral `AGENT_*` name, which init and `configure-skills` write, and a per-agent override under the plugin's prefix (`KEVIN_*` for `agent-kevin`; a fork named `agent-scout` reads `SCOUT_*` with no code change). The prefixed spelling wins. **Set them per home, in `/.claude/settings.local.json`, under the `AGENT_*` names.** The file's location is what scopes the value to that agent, and every host reads it: Claude Code directly, Codex through the shell env policy generated from it. Never put a `KEVIN_*` value in a user-level settings file: it is machine-wide and hands every session to one brain. | Variable | Purpose | Default | | ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ | | `KEVIN_HOME` | Path to the home. Normally unset: the home is found by walking up for `.kevin/`. Useful as a one-off prefix for the CLI outside a home | resolved from the launch dir | | `AGENT_TIMEZONE` | IANA timezone for dates | system timezone | | `AGENT_HOME_TIMEZONE` | Home-base timezone; when it differs from the live one, session context flags you as traveling | unset | | `AGENT_KNOWLEDGE` · `AGENT_PROJECTS` · `AGENT_REPORTS` | Move those directories elsewhere (a synced folder, another repo) | under the home | | `AGENT_CODE_PATH` | Your primary codebase. Grounds code tasks and surfaces its git activity in session context | none | | `AGENT_GIT_REPOS` | Comma-separated extra repos shown in the SessionStart git block | derived from `AGENT_CODE_PATH` | | `AGENT_LOG_LEVEL` · `AGENT_LOG_FILE` | `debug` · `info` · `warn` · `error`; `off` disables file output | `info` · `.kevin/logs/app.log` | | `AGENT_RUNTIME_DIR` | Rename the runtime folder (a bare name, validated) | `.kevin` | | `MARKDOWN_URL` | Opener for markdown links on the dashboard | `obsidian://open?path={path}&paneType=tab` | If you move `knowledge/` or `projects/` outside the home after init, add the matching `permissions.allow` entries to `settings.json` yourself; the wizard does it only during scaffold. ## Where keys live [#where-keys-live] | Sensitivity | File | Examples | | -------------- | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ | | **Secret** | `/.kevin/secrets/.env` (and `secrets/google/`) | `SERPAPI_KEY`, `OPENPAGERANK_API_KEY`, `PERPLEXITY_API_KEY`, `GITHUB_TOKEN`, `AGENT_DB_*`, the Google OAuth client | | **Non-secret** | `/.claude/settings.local.json` env block | `GSC_SITE_URL`, `AGENT_CODE_PATH`, `AGENT_GIT_REPOS`, and under Claude Code `CLAUDE_CODE_OAUTH_TOKEN` | Both are gitignored. The secrets store is deny-gated: Kevin's own shell cannot read it, only the MCP server can. Init owns universal-infra keys (only the optional codebase pair); `configure-skills` plants a pack's keys as empty placeholders when you activate it. You fill values in your editor, never in chat. ## Database pack [#database-pack] `database_list`, `database_schema`, and `database_query` run read-only Postgres queries. Connections are discovered by convention: every `AGENT_DB_` line in the secrets store becomes a connection named ``. ```sh # /.kevin/secrets/.env AGENT_DB_APP=postgres://user:pass@localhost:5432/app_dev AGENT_DB_ANALYTICS=postgres://user:pass@host:5432/analytics ``` Every query runs inside a `BEGIN READ ONLY` transaction with a statement timeout and is rolled back, so Postgres rejects any write. For tighter control, point the connection string at a SELECT-only role. `database_list` reports host, port, and database, never credentials. `database_fork` is the one write tool: it clones a local database via `CREATE DATABASE TEMPLATE ` (pure SQL, no dump files) so you can run destructive schema changes against a scratch copy. It refuses remote hosts, names the fork after the current branch, can repoint an env file at it, and `drop: true` tears it down. `setup-worktree` uses it to give a worktree its own database. ## GitHub pack [#github-pack] The `pr-review` skill runs on this pack. Eleven read-only tools wrapping the `gh` CLI (`brew install gh`): PR list, view, inline review comments, diff, checks; run list, view, and failed-step logs; issue list and view; and `github_fast_forward`, which fast-forwards local default branches during sync. No write subcommands exist. Auth is a fine-grained, read-only personal access token as `GITHUB_TOKEN` in the secrets store. `configure-skills` walks you through minting it: resource owner set to the repos' owner, repository permissions **Pull requests · Issues · Metadata · Actions · Contents**, all read. > **Two permission gotchas** Grant **Actions: Read** (workflow runs and logs). Do not grant **Workflows**: despite the name it is write access to the workflow files. **Contents: Read** is required for `git fetch` and diffs and grants no push ability. There is no Checks permission for fine-grained tokens, so `github_pr_checks` returns 403 where CI reports as check runs; read build state from the run tools instead. When a call omits `repo`, Kevin resolves it from the `origin` remote of `AGENT_CODE_PATH`, then the first `AGENT_GIT_REPOS` entry. An explicit `repo="owner/repo"` always wins. # Daily rhythm (/docs/agent/daily-rhythm) Nothing here runs on its own. You invoke a cadence when you sit down, and it reads the board, the memory, and the recent sessions to tell you what matters. ## A day [#a-day] | When | Skill | What you get | | --------------------- | ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Sitting down | `morning-briefing` | Priorities, drafted artifacts, goals delta, per-project pulse, news, one first move. Includes the Hijri date when your profile asks for it | | Any time | `quick-pulse` | A one-minute scan: anything stalled, recent errors, tasks past their cadence | | Before standup | `standup` | Did / next / blocked, derived from git, PRs, sessions, and the board. `standup 48` widens the window | | Lost | `where-am-i` | The sessions from the last 24 hours scoped to this home, what each was about, where it left off, the resume command. `triage` ranks them; `checkpoint` writes a pickup note for the current one | | Looking for something | `find-session` | Find a past session by what it worked on (a branch, a PR, a bug) and get its resume command | | Wrapping up | `evening-briefing` | What shipped, drafted, stalled, the goal delta, tomorrow's first move | | Been away | `sync` | Everything current in one pass, optionally chaining a briefing. See [Sync](/docs/platform/sync) | ## Goals [#goals] Three skills set the goals blocks at the top of `projects/TASKS.md`. Each reads the board and recent sessions, then interviews you. | Skill | Sets | | --------------- | ---------------------------------------------------------- | | `yearly-goals` | The year, quarter by quarter, tied to a north-star roadmap | | `monthly-goals` | This month's themes and big rocks | | `weekly-goals` | This week's goals | Briefings and sync flag a cadence that has come due, with the command to run it, and keep nudging until you set it or consciously skip it. ## Working sessions [#working-sessions] * `flywheel` runs a cross-project work session framed by the roadmap: advance, update, close, and keep milestone statuses honest. Sync runs it for you. * `self-review` turns accumulated feedback into prompt and skill edits. See [Self-evolution](/docs/platform/self-evolution). * `plan-spec` interviews you into a standalone spec you can hand to your host's planning mode. * `roadmap` builds or updates a north-star roadmap as a self-contained HTML surface. All outputs land in `reports/` and show up under today's reports in the next session's context. # Hooks (/docs/agent/hooks) Every hook shells into `bin/kevin` with a `--hook-protocol=` flag. Claude Code runs them from the plugin's `hooks/claude.json`; Codex runs the same entry points from a per-home `.codex/hooks.json`. A new host adds a protocol, not a script. See [Hosts](/docs/agent/hosts). | Hook | Command | Timeout | Purpose | | ------------------- | ------------------------------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `SessionStart` | `kevin session-start` | 15s | Pre-init: the setup banner. Post-init: today's date in your timezone, the last session tail, today's reports, and recent git activity, capped at 10KB. Under Codex the whole static stack rides along too | | `SessionEnd` | `kevin session-capture --mode=session-end` | 30s | Append the transcript to `knowledge/raw/sessions/YYYY-MM-DD.md` with secret redaction | | `PreCompact` | `kevin session-capture --mode=pre-compact` | 30s | The same capture before auto-compaction, so mid-session context is not lost | | `PreToolUse` (Bash) | `kevin guard` | 5s | Block a home-relative `projects/`, `knowledge/`, or `reports/` write while the effective cwd is outside the home; tell the model the absolute path | ## Why the hooks live in the plugin [#why-the-hooks-live-in-the-plugin] Every host runs the hooks only for sessions started in the home (Claude Code because the plugin is enabled there, Codex because the hooks are wired there). A session can therefore only ever be captured by the agent it launched in. Two agents on one machine cannot write into each other's memory, and nothing needs configuring to guarantee it. The cost is that a session started outside a home is not captured at all. See [Onboarding](/docs/getting-started/onboarding#the-one-convention). ## Session files [#session-files] Capture appends to one file per day. Each block header carries the session id, the harness and model that produced it, and the turn range, so a resumed session appends a continuation block rather than a new file. A session index (`raw/sessions/index.json`) keys the capture cursor and the compile's continuation source, and is reconstructable from the day-file headers. ## Redaction [#redaction] Before writing, capture exact-matches every value in `.kevin/secrets/.env` and `settings.local.json`, and applies prefix heuristics for common key formats. The transcript never carries a secret into the knowledge tree. # Hosts (/docs/agent/hosts) A **host** is the agent CLI that opens the home, reads the manual, runs the skills, and calls the MCP server. Two are supported today: [Claude Code](/docs/agent/claude-code) and [Codex](/docs/agent/codex). Everything the host does not own lives in the home, which is why a home works from either, and why a session ended in one is in the other's context next time. ## What a host provides [#what-a-host-provides] | Piece | Owner | Claude Code | Codex | | ------------------- | ------ | -------------------------------------------------- | ------------------------------------------------------------------------------ | | Operating manual | Home | `AGENTS.md` through the `.claude/CLAUDE.md` bridge | `AGENTS.md`, read natively | | Skills | Plugin | Bundled | Bundled | | MCP server | Plugin | Registered by the plugin manifest | Registered per home in `.codex/config.toml` | | Hooks | Plugin | Bundled | Generated per home into `.codex/hooks.json` | | Permissions and env | Home | `.claude/settings.json`, `settings.local.json` | The same files, projected into a profile, a rules file, and a shell env policy | | Session capture | Plugin | Claude transcript format | Codex rollout format | The home's settings live under `.claude/` for historical reasons and are the source of truth for both hosts: Codex's wiring is generated from them, so a permission or a variable is set once. See [Configuration](/docs/agent/configuration). ## Speaking to either host [#speaking-to-either-host] | | Claude Code | Codex | | ---------------------------------- | ---------------------------------------------------- | ------------------------------------------------------------ | | Launch from the home | `claude` | `codex` | | Run a skill | `/agent-kevin:sync` | `$sync` | | Install the plugin | `/plugin marketplace add …` then `/plugin install …` | `codex plugin marketplace add …` then `codex plugin add …` | | Update the plugin | `/plugin update agent-kevin@agentlayer` | `codex plugin remove` then `codex plugin add` | | Reconcile the home after an update | `/agent-kevin:upgrade` | `$upgrade` | | See what loaded | `/context` | The SessionStart payload names the harness on its first line | These docs write skills by their bare name (`sync`, `morning-briefing`) and use host tabs wherever the exact command differs. Pick your host once in any tab strip; the choice sticks across pages. ## The host does the thinking [#billing] The MCP server never calls a model. It does I/O and returns prompts; your own session synthesises, and the server confirms the write. The compile loop, briefings, and audits all run inside your turn, so they draw on whatever plan your host bills, never on a metered API key. The consequence is that Kevin is reactive: you start every session, nothing runs at 7am on its own. See [History](/docs/about/history) for why. ## Adding a host [#adding-a-host] A new host needs four things, and the plugin isolates each behind a small surface: 1. **Read the manual.** Any CLI that reads `AGENTS.md` gets the operating rules; the identity stack and indexes ride in on the SessionStart hook. 2. **Run the four hooks.** `session-start`, `session-capture` at end and before compaction, and `guard` before shell commands. All shell into `bin/kevin` with a `--hook-protocol=` flag. 3. **Register the MCP server** with the home pinned (`--home=`). 4. **A capture adapter.** One format module that turns the host's transcript into user and assistant turns. Codex was the first host added this way; its page is the worked example. # The agent is the harness (/docs/agent) What makes an agent effective inside a company is not which model answers. It is what the agent knows before it starts, what it is allowed to do, and what gets recorded when it acts. Those live in files around the model. The model is a setting. ## The rails [#the-rails] | Rail | What it does | Page | | -------------------- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- | | **Operating manual** | `AGENTS.md` says how the agent works, what it may do, and how you like to work. Every host reads it at session start. | [The agent home](/docs/platform/agent-home) | | **Permission rails** | Allow and deny lists, a sandboxed shell, secrets in a store the agent's own tools cannot read. | [Configuration](/docs/agent/configuration) | | **Hooks** | Session start loads the context, session end captures it, a guard checks every shell command. Skills advise; hooks enforce. | [Hooks](/docs/agent/hooks) | | **Audit trail** | Every session captured to a dated file, every task change threaded, the folder under git. | [Tasks](/docs/agent/tasks) | | **Observability** | The dashboard, the session radar, briefings and pulses. | [Daily rhythm](/docs/agent/daily-rhythm) | | **Host-neutral** | One home works from Claude Code or Codex. What a host provides, and what a new one needs. | [Hosts](/docs/agent/hosts) | ## How a session runs [#how-a-session-runs] Launch from the home. The SessionStart hook loads the identity stack, the wiki index, active memory, the task board, today's date, and the tail of the last session. You type. Skills run when you invoke them; tools do I/O and return prompts for your own session to think with, so nothing bills a metered key. On exit the transcript is captured for the next compile. [Your first session](/docs/getting-started/first-session) walks through one. ## Work, not chats [#work-not-chats] Tasks are one markdown file each with frontmatter, a checklist, and a thread. Projects group them. Parallel work happens in [worktrees](/docs/agent/worktrees) so agents never collide on one repo. The [architecture](/docs/agent/architecture) page shows how the host, the plugin, and the brain fit. - [Hosts](/docs/agent/hosts): Claude Code and Codex, one home, and what a new host needs. - [Hooks](/docs/agent/hooks): The four moments the plugin hooks into. - [Configuration](/docs/agent/configuration): Permissions, environment, secrets, and the packs that need them. - [Tasks and projects](/docs/agent/tasks): Markdown-native task management. - [Daily rhythm](/docs/agent/daily-rhythm): Briefings, pulses, standups, the session radar, the goals ladder. - [Worktrees](/docs/agent/worktrees): Parallel agents on one repo with zero collisions. # Tasks and projects (/docs/agent/tasks) Projects and tasks are files. There is no database to sync, nothing to export, and Obsidian renders all of it. ## Projects [#projects] `create-project` scaffolds `projects//` with a README and a `tasks/` folder. The two-letter task prefix derives from the slug automatically. `archive-project` retires one cleanly: moves the folder to the archive, strips references from active docs, banners the README, recompiles the index. ## Tasks [#tasks] Each task lives at `projects//tasks/-.md`: ```markdown --- schema: 1 id: bd-004 title: "Write blog post: Why Bun is a joy for local TS scripts" type: task status: open priority: P2 project: blog-dev assignee: [basem] labels: [] created: 2026-04-21 updated: 2026-07-24 due: depends_on: [] --- ## Description ... ## Checklist - [ ] ... ## Thread > [!quote] Basem · 2026-07-24 > Let's frame it around the postinstall story. > [!info] Kevin · 2026-07-24 > Drafted an outline in the description. ``` | Field | Values | | ------------ | ---------------------------------------------------------------------------------------- | | **ID** | Two-letter project prefix plus a three-digit number. Globally unique. Kevin assigns them | | **Type** | `task` · `bug` · `idea` · `epic` | | **Status** | `open` · `active` · `blocked` · `done` · `cancelled`. Transitions are validated | | **Priority** | `P0` drop everything · `P1` this week · `P2` this sprint · `P3` backlog | | **Thread** | Append-only. `[!quote]` for you, `[!info]` for Kevin, `[!warning]` for automated actions | Closed tasks move to `tasks/archive/` on the next sync so the active folder stays scannable. ## Driving them [#driving-them] Inside a session, Kevin uses the `task_*` MCP tools (query, get, create, update, close, thread, scan). Outside a session, the same operations are on the CLI: ```bash kevin task query --status=active kevin task create --project=blog-dev --title="Draft launch post" --priority=P1 kevin task close bd-004 ``` ## The dashboard file [#the-dashboard-file] `projects/TASKS.md` is generated from task frontmatter on every mutation: weekly, monthly, and yearly goals at the top, then active tasks grouped by project, blocked, overdue, stale, and recently closed. It loads into every session, so Kevin always knows the board. Never edit it by hand. The goals blocks come from the `weekly-goals`, `monthly-goals`, and `yearly-goals` skills. See [Daily rhythm](/docs/agent/daily-rhythm). # Worktrees (/docs/agent/worktrees) A [git worktree](https://git-scm.com/docs/git-worktree) checks out a second working copy of the same repo into a separate folder, on its own branch, sharing one `.git`. Agent A refactors on `feature-x` while Agent B fixes a bug on `bugfix-y`, and nobody's files change under them. ## Two conventions [#two-conventions] * **Siblings, never nested.** The main checkout at `~/Developer/acme/repo` gets a worktree at `~/Developer/acme/repo-my-feature`. A nested worktree lands under a tracked path and pollutes the parent's working tree. * **Bootstrap before coding.** A fresh worktree has no gitignored local files (`.env*`, `.claude/settings.local.json`), no installed deps, no built packages. ## Ask Kevin [#ask-kevin] ```text make a worktree for the billing refactor ``` `setup-worktree` pins down which repo you mean (it asks when the home sits above several), creates the sibling worktree on a new branch, copies the gitignored local files from the main checkout, detects the package manager (bun, pnpm, yarn, npm), installs, and runs the build script. It offers to add the worktree to a sibling `.code-workspace` if one exists, and can give the worktree its own database through `database_fork`. Underneath, the `setup_worktree` MCP tool runs outside the host's shell sandbox so `git worktree add` can make the writes the sandbox blocks. The same logic is on the CLI: `kevin worktree --branch=...`. ## Audit [#audit] ```text which worktrees do I have? which can I delete? ``` The read-only `list_worktrees` triage reports each worktree with a verdict: merged, stale, or active. `remove_worktree` is never pre-granted, so every deletion confirms. Pair worktrees with [cmux](/docs/workstation/cmux): one workspace per worktree, one agent per workspace. # Dashboard (/docs/dashboard) Every sync regenerates `/dashboard.html`. Open it like any file: no server, no service, no account. A left sidebar carries the agent's wordmark, the page nav, your avatar, and a system-health badge. The pages are operator-first. > **Try it** A live demo, rendered from a fictitious company's home, is at [agentlayer.one/demo/dashboard](/demo/dashboard). Every page below is there. Today: the plan, in flight, waiting on ## The pages [#the-pages] | Page | Layer | Shows | | ------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Today** | all | Time-aware greeting and stat strip; sub-tabs for the plan (focus, next 7 days, waiting-on), goals, a today-so-far activity trail, and news harvested from briefings | | **Tasks** | Agent | The agenda by due horizon (overdue → today → this week → this month → later) and a needs-attention view | | **Projects** | Agent | Colour-coded cards with progress and last-updated; expand for tasks by status, plus a link to the project's own roadmap | | **Sessions** | Platform | Real working sessions from the last 30 days, grouped by day, with summaries and the latest radar | | **Brain** | Platform | Which files prime a session and how big each is, active threads, decisions, daily memory, learnings, concept articles, the compile pipeline, the last lint | | **Reports** | Agent | Everything the agent produced, by day, every title clickable | | **Capabilities** | Modules | Starter recipes, every skill as a tile (with an `auto` badge where the model may self-invoke), every MCP tool, the CLI reference, hook wiring | | **Profile** · **Persona** | Platform | You, and the agent, rendered from the identity files | | **System** | Agent | Context assembly, settings by scope, a log tail | Brain: context loaded every session, by source and size Sessions: captured automatically, summarised, resumable A **Surfaces** group lists the standalone pages the agent builds alongside it, discovered by convention: `roadmap.html` at the home root, then any `projects//roadmap.html` or `dashboard.html`. ## Refreshing it [#refreshing-it] * `sync` does it automatically. * `dashboard` rebuilds and opens it. * `kevin dashboard` does the same from a terminal. Every refresh also rebuilds `projects/TASKS.md`; the two derived views always regenerate together. It is a snapshot, not a live app: the timestamp is in the footer. ## Opening links [#opening-links] Markdown links (tasks, reports, concepts) open through a configurable opener so they land rendered and editable. The default is Obsidian, in a new tab so the dashboard stays put. Point it elsewhere with `MARKDOWN_URL` in the home's `settings.local.json`: ```json { "env": { "MARKDOWN_URL": "markedit://open?path={path}" } } ``` > **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. # Your first session (/docs/getting-started/first-session) Launch your host from the home (`claude` or `codex`). The SessionStart hook prints a banner: quick proof the brain is wired up. ```text $ cd ~/Documents/Agents/Kevin && claude 🧠 Knowledge: ~/Documents/Agents/Kevin/knowledge 📁 Projects: ~/Documents/Agents/Kevin/projects 📚 Context · 4.2KB ✓ session tail 1.6KB (YYYY-MM-DD.md) ✓ today reports 0.2KB (1 briefing) ✓ git activity 0.3KB (15 commits in the last week) > morning briefing [Kevin runs the morning-briefing skill: active threads, in-flight tasks, anything overdue, what deserves attention today, with yesterday's session tail as continuity] > Create a project called "new-blog". I want to relaunch under a different domain. [Kevin runs create-project, scaffolds projects/new-blog/, asks for the one-line vision, opens for your first task] > Audit the site I have in Search Console. [Kevin runs google-search-audit: 28 days of GSC, PageSpeed on the top 5 pages, four rules, findings ranked by impact, report written, matching findings threaded into open tasks] > /exit [The SessionEnd hook captures the conversation to knowledge/raw/sessions/, redacting secret values first. The next compile feeds it into long-term memory.] ``` Skills answer to plain language, as above, or to their command form: `/agent-kevin:morning-briefing` in Claude Code, `$morning-briefing` in Codex. See [Hosts](/docs/agent/hosts). ## Where the context comes from [#where-the-context-comes-from] **Static, loaded every session.** Claude Code reads it through the `@`-imports in `.claude/CLAUDE.md` (run `/context` to see the cascade); Codex receives the same files in the SessionStart payload. | File | Holds | | ------------------------------------- | ------------------------------------------- | | `AGENTS.md` | The operating manual | | `SOUL.md` · `IDENTITY.md` · `USER.md` | Character, role, your headline | | `knowledge/index.md` | Master catalog of the wiki | | `knowledge/memory/index.md` | Active threads, recent decisions, learnings | | `projects/TASKS.md` | Cross-project task dashboard | **Dynamic, injected per session** by the SessionStart hook: today's date in your timezone, the last session tail, today's reports, and recent git activity, capped at 10KB. **Read on demand**, never auto-loaded: user facets (`knowledge/user/*.md`), concept articles, and project READMEs. Kevin pulls them when relevant, which keeps the static lane lean while keeping the deeper material one read away. ## Things to try [#things-to-try] * `Who are you and what's on my task list?` * The `quick-pulse` skill for a one-minute status check * The `standup` skill for your last 24 hours as did / next / blocked * `capture this: ` to feed the inbox * The `sync` skill when you have been away and want everything current # Install (/docs/getting-started/install) ## Prerequisites [#prerequisites] Kevin runs on a small, Bun-first toolchain. No Node.js required. | Tool | Why | Get it | | ----------------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | | **A host**: Claude Code or Codex | The agent CLI Kevin plugs into. One home works from either, or both | [docs.claude.com](https://docs.claude.com/en/docs/claude-code/setup) · [developers.openai.com/codex](https://developers.openai.com/codex) | | **Bun** ≥ 1.1 | Runs the MCP server, hooks, and the `kevin` CLI | [bun.sh](https://bun.sh) | | **Git** | Cloning, the plugin marketplace, git-activity awareness | [git-scm.com](https://git-scm.com) | | **Python 3** *(optional)* | Some integrations still reach for it | [python.org](https://python.org) | | **Obsidian** *(optional)* | Browse the brain as a graph | [obsidian.md](https://obsidian.md) | `bun` and `git` are hard requirements; the `init` skill checks for both and stops with an install pointer if either is missing. Chromium for the browser tools is not a manual step: `bun install` pulls it through a postinstall hook. > **Windows** Native Windows works through Git Bash. WSL2 works too. See [Platforms](/docs/about/platforms) for the rough edges. ## Pick a home [#pick-a-home] The home is the folder Kevin's brain lives in. Every host is launched from it. ```bash mkdir -p ~/Documents/Agents/Kevin && cd ~/Documents/Agents/Kevin ``` ## Install the plugin [#install-the-plugin] **Claude Code** Launch `claude` from the home, then inside the session: ```text /plugin marketplace add github:AgentLayer1/agentlayer-agent-marketplace /plugin install agent-kevin@agentlayer /exit ``` Relaunch `claude` and run `/agent-kevin:init`. See [Onboarding](/docs/getting-started/onboarding). **Codex** From a terminal: ```bash codex plugin marketplace add AgentLayer1/agentlayer-agent-marketplace codex plugin add agent-kevin@agentlayer ``` Codex wires hooks and the MCP server per home rather than from the plugin, so a home needs one setup pass. Today that pass runs from Claude Code: create the home there with `init`, then open it with `codex` and run `$upgrade` once. Details on the [Codex](/docs/agent/codex) page. ## From a clone [#from-a-clone] The plugin ships its own developer marketplace on both hosts, so a clone is itself a marketplace you can register. ```bash git clone https://github.com/AgentLayer1/agent-kevin ~/Developer/agent-kevin # One-time MCP-server deps install (~150MB, pulls chromium for Playwright) cd ~/Developer/agent-kevin/mcp-server && bun install ``` **Claude Code** ```text /plugin marketplace add ~/Developer/agent-kevin /plugin install agent-kevin@agentdev-kevin /exit ``` Edits to the clone go live after `/reload-plugins`; new skills or hooks need a full relaunch. **Codex** ```bash codex plugin marketplace add ~/Developer/agent-kevin codex plugin add agent-kevin@agentdev-kevin ``` Codex copies the checkout into its plugin cache, so after pulling new code remove and re-add the plugin. > **Starting from a seed bundle?** A teammate's export or the [dev.agentlayer.one wizard](https://dev.agentlayer.one/#wizard) gives you a zip that pre-loads the agent's name, character, and starting knowledge. Install as above, then hand the zip to `init` when it asks. See [Seed bundles](/docs/platform/seed-bundles). > **Already have an AGENTS.md or CLAUDE.md here?** Kevin appends its operating manual to an existing `AGENTS.md` and never touches a `CLAUDE.md`. Both load at session start. # Onboarding (/docs/getting-started/onboarding) ## The wizard [#the-wizard] Run the `init` skill from a fresh session in the home (`/agent-kevin:init` in Claude Code; under Codex, create the home from Claude Code for now). ```text ❓ What should this agent be called? (default: Kevin; plus emoji + avatar if you rename) ❓ Its character (SOUL): accept default, or refine? ❓ Its role (IDENTITY): general / coding / research / planning / custom? ❓ Your name and home timezone? ❓ Paste any URLs about you (blog, LinkedIn, GitHub) so Kevin seeds your profile ❓ Paste a path or URL for your avatar (optional) ❓ Should knowledge/ and projects/ live somewhere else? ❓ Communication style and any hard preferences? ❓ Configure skill packs (SEO, Browser, third-party libraries)? ❓ Starting from a teammate's seed bundle? (applied after the scaffold) ❓ Do you also run Codex from this home? ❓ Confirm + scaffold ``` About five minutes. Each answer becomes the default for later steps, the name first of all, since every file the wizard writes is phrased in it. See [Naming your agent](/docs/reference/naming). A [seed bundle](/docs/platform/seed-bundles) from a teammate or the web wizard answers most of it for you. ## What it writes [#what-it-writes] - .claude/ - CLAUDE.md - settings.json - settings.local.json - rules/ - .codex/ - knowledge/ - projects/ - AGENTS.md - SOUL.md - IDENTITY.md - USER.md | File | Role | | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `AGENTS.md` | The operating manual. Harness-neutral: every AGENTS.md-aware CLI reads it | | `SOUL.md` / `IDENTITY.md` / `USER.md` | Kevin's character, Kevin's role, your headline | | `knowledge/`, `projects/` | The brain and the work, optionally at custom locations | | `.claude/CLAUDE.md` | The Claude Code bridge: `@`-imports the manual and the identity stack | | `.claude/settings.json` | The home's permissions: marketplace registration plus grants for the always-on core tools. Read by Claude Code directly and by Codex through its generated wiring | | `.claude/settings.local.json` | Gitignored. Non-secret config only; secrets go in `.kevin/secrets/.env` | | `.codex/` | Only when you said you run Codex: hooks, MCP registration, permission profile, rules. See [Codex](/docs/agent/codex) | You fill secret values in your editor, never in chat. Neither init nor `configure-skills` asks for a key in conversation, because pasted secrets touch the transcript. If you moved `knowledge/` or `projects/` outside the home, the wizard appends the needed permission entries so the host can reach them without prompting. ## Exit and relaunch [#exit-and-relaunch] Plugin registration only takes effect on a fresh session. **Claude Code** ```bash /exit cd ~/Documents/Agents/Kevin && claude ``` Watch for a **marketplace trust prompt** on first relaunch and accept it. If you miss it, recover with `/plugin marketplace add …` and `/plugin install agent-kevin@agentlayer`. **Codex** ```bash cd ~/Documents/Agents/Kevin && codex ``` Trust the folder when asked (that is what lets Codex read the home's `.codex/config.toml`), then run `/hooks` and trust the four Kevin entries. Until then Codex starts without Kevin's context and captures nothing. ## The one convention [#the-one-convention] **Always launch from the agent home, then reach your code from inside the session.** The plugin is enabled by the home's settings, so a host loads it only for sessions started there. That single fact gives you the identity stack, the skills, the MCP tools, and session capture. It is also what keeps several agents on one machine apart with no configuration. **Reaching your code.** Add the repos you work in to `permissions.additionalDirectories` in the home's `settings.local.json`. Both hosts honour it: Claude Code grants file access there, and Codex lists the same paths as workspace roots. ```json { "permissions": { "additionalDirectories": ["/Users/you/Developer/acme", "/Users/you/Developer/side-project"] } } ``` Set `AGENT_CODE_PATH` to your primary repo and its git activity shows up in every session's context. **The session can wander, the anchor cannot.** Once running, `cd` anywhere. The home is resolved from the launch directory, which never moves, so capture lands in the right brain even when the shell has roamed three repos deep. > **What you give up** A session started outside a home is not captured, and says nothing about it. No plugin loads, so no hooks run. Do not put a `KEVIN_*` variable in a user-level settings file to work around this: it is machine-wide and hands every session to one brain. Per-home config belongs in that home's `settings.local.json`. # Updating (/docs/getting-started/updating) Updating is two steps because the plugin and your home are two different things. A plugin update replaces plugin **code**. Your home (`AGENTS.md`, `SOUL.md`, settings, rules) was copied out of templates once at init and has been yours to edit since. A code update cannot safely overwrite it, so the home is reconciled separately, on your terms. ### Pull the new version [#pull-the-new-version] **Claude Code** Plugin updates are not automatic for third-party marketplaces. Inside a session: ```text /plugin marketplace update agentlayer # refresh the catalog /plugin update agent-kevin@agentlayer # pull the new version /reload-plugins # activate without restarting ``` Local dev install? Swap `agentlayer` for `agentdev-kevin`. Auto-update is a per-marketplace toggle (`/plugin` → Marketplaces); it refreshes every plugin from that marketplace at startup, so leave it off if you want to control when each one changes. **Codex** Codex installs a copy of the plugin into its cache, so an update is a remove and add: ```bash codex plugin remove agent-kevin@agentlayer && codex plugin add agent-kevin@agentlayer ``` For a clone, swap `agentlayer` for `agentdev-kevin`. ### Reconcile the home [#reconcile-the-home] Run the `upgrade` skill (`/agent-kevin:upgrade` or `$upgrade`). It reads the CHANGELOG's Upgrade blocks from your home's recorded baseline up to the installed version, backs up every file it will touch, runs `bun install` when deps changed, auto-applies the mandatory changes, and asks before touching anything you may have personalized. On a Codex home it also regenerates the `.codex/` wiring. The SessionStart banner and the dashboard badge tell you when an upgrade is pending, with no network call: the home records its template version in `.kevin/version.json` and compares it to the installed plugin. How the release and upgrade contract works underneath: [Upgrades and releases](/docs/reference/upgrades). # External accounts and costs (/docs/modules/accounts) Tasks, compile, the dashboard, session capture, and the browser tools run entirely on your machine on your host's plan. External accounts enter only when you activate the SEO, Browser, or GitHub pack. | Account | Unlocks | Pack | Credential | Cost | | ----------------------------------------------------------------- | ----------------------------------------------- | ------- | --------------------------------------------- | --------------------------------------------------------------------- | | [Perplexity](https://perplexity.ai/settings/api) | `web_search` with citations | Browser | `PERPLEXITY_API_KEY` | Pay-as-you-go, $5 per 1,000 requests. A $5 credit lasts days to weeks | | [GitHub](https://github.com/settings/tokens?type=beta) | PR, issue, and CI review; `github_fast_forward` | GitHub | `GITHUB_TOKEN`, fine-grained read-only | Free | | [Google Cloud](https://console.cloud.google.com) | `gsc_*` and `page_speed_*` | SEO | OAuth client JSON in `.kevin/secrets/google/` | Free. PSI quota 25k requests a day | | [Google Search Console](https://search.google.com/search-console) | The site data behind the audit | SEO | Your site verified under the same account | Free | | [SerpAPI](https://serpapi.com) | `serpapi_search` for rank tracking | SEO | `SERPAPI_KEY` | Free tier 250 searches a month; paid from $25 a month | | [OpenPageRank](https://www.domcop.com/openpagerank/) | `open_page_rank` domain authority | SEO | `OPENPAGERANK_API_KEY` | Free, 1,000 requests a day | `wordpress-rest` reads the public REST API of the site at `GSC_SITE_URL` and needs no account. The knowledge pipeline never bills an API key. **Bottom line:** a typical personal setup runs at $0 a month. Heavy Perplexity use or serious rank tracking adds roughly $5 to $30 a month. ## Setting each one up [#setting-each-one-up] The flow is the same for every keyed service: `configure-skills` activates the pack and creates the placeholder; you paste the value in your editor. **Perplexity.** Settings → API, load a small credit block, generate a key. The API bills separately from a Pro chat subscription. **Google Search Console and PageSpeed** (one free Cloud project covers both): Create a project at console.cloud.google.com. APIs & Services → Library → enable **Search Console API** and **PageSpeed Insights API** . Credentials → Create → OAuth client ID → **Desktop app** . First time, Google walks you through the consent screen: choose External, add your own email as a test user. Download the client JSON to `/.kevin/secrets/google/google-oauth-client.json` . Verify your site in Search Console under the same account, and set `GSC_SITE_URL` in `settings.local.json` ( `https://example.com/` or `sc-domain:example.com` ). Run the `google_auth` tool once. A browser consent flow mints tokens that are cached and shared across the Google tools. **SerpAPI.** Sign up, copy the key from the dashboard. The free tier covers a weekly audit of a small site. **OpenPageRank.** Sign up at domcop.com/openpagerank, generate the free key. # Brain and memory (/docs/modules/brain-and-memory) The capabilities that feed the loop and act on it. Most run rarely and matter most: `sync` once a day, `self-review` when corrections have piled up, `seed-export` when a teammate needs an agent. | Capability | What it does | Skills and tools | |---|---|---| | **Capture** | Feed the brain anything: a thought, a file, a URL, the clipboard, a correction. | capture | | **Compile** | Raw sessions and captures become a structured wiki that loads next session. | knowledge-compile, compile_next, compile_write, knowledge_lint | | **Self-review** | Accumulated feedback, read together, turned into changes to the agent’s own prompts. | self-review | | **Sync** | One pass through every maintenance operation, ending in a status and a next move. | sync, memory_prune, links_rewrite | | **Dashboard** | The mission-control page regenerated from the home: today, tasks, projects, sessions, brain, reports. | dashboard, dashboard, report_write | | **Seed bundles** | An agent’s persona and setup exported as a zip; a teammate’s fresh home imports it. | seed-export, seed-import, seed_scan, seed_export, seed_import | | **Diagrams and prose** | Mermaid validated before it ships; AI tells stripped from any text. | mermaid, humanizer | | **Onboarding** | A guided first run, a rename across the home, packs and custom skills configured. | init, rename-agent, configure-skills, codex_setup | ## The loop, as skills [#the-loop-as-skills] 1. Hooks capture every session; `capture` takes anything else: a thought, a file, a URL, a correction. 2. `knowledge-compile` distils raw capture into the wiki; `sync` runs it with every other maintenance pass. 3. `self-review` reads the accumulated feedback with you and changes the agent's own prompts. 4. `dashboard` renders the result as one page. - [The brain](/docs/platform/the-brain): Raw conversations are source; the wiki is the build. - [Capture](/docs/platform/capture): Every way to feed it. - [Self-evolution](/docs/platform/self-evolution): Feedback becomes learnings becomes prompt changes. - [Seed bundles](/docs/platform/seed-bundles): Hand an agent to a teammate. # Browser tools (/docs/modules/browser) Five `browser_*` tools run on a Chromium that `bun install` pulls once (\~150MB). Outputs land in `/reports/captures/-.`. Activate the Browser pack in `configure-skills` to pre-grant the permissions; without it, the first call confirms. | Tool | Output | Use it for | | -------------------- | -------- | -------------------------------------------------------------------------------------------- | | `browser_screenshot` | PNG | Any URL or local HTML / Markdown file; `fullPage` for the whole scroll | | `browser_pdf` | PDF (A4) | Markdown (Mermaid rendered) or HTML to print-styled PDF | | `browser_markdown` | Markdown | Any URL, including client-rendered SPAs, to clean LLM-friendly Markdown via Readability | | `browser_record` | WebM | Drive a page through `navigate` / `scroll` / `wait` steps and capture the run | | `browser_flows` | varies | Run a named, repeatable flow in a visible browser: scrape, fill a form, click through a task | All take the same `input`: a URL, a `file://` URL, or a path. `screenshot` and `pdf` render local Markdown through a styled CSS so Mermaid comes through; `markdown` does the reverse. ```text you > screenshot https://acme.com and call it acme-landing you > render ~/Documents/business-plan.md to PDF you > convert https://example.com to markdown, make sure the JS-rendered sections come through you > record a 15-second tour of acme.com: scroll halfway, wait 2s, scroll to the bottom ``` ## Web search [#web-search] The Browser pack also carries `web_search`, a direct call to the Perplexity Search API with citations. Activate it in `configure-skills`, then put `PERPLEXITY_API_KEY` in `.kevin/secrets/.env` in your editor. Pay-as-you-go; a $5 credit lasts most personal users days to weeks. See [Accounts](/docs/modules/accounts). ## Flows [#flows] `browser-flows` drives a visible browser through pluggable flows; `hacker-news` ships as the reference. Write your own for any repeatable multi-step task on a site you use. > **macOS sandbox** Browser launch can fail inside a host's sandboxed subprocesses. If it does, run `playwright install chromium` once from a normal terminal so the binary is cached. # Build and ship (/docs/modules/build-and-ship) The engineering loop: plan in a spec, work in a worktree, review the pull request, verify the deploy. Run a skill as `/agent-kevin:` in Claude Code or `$` in Codex. | Capability | What it does | Skills and tools | |---|---|---| | **Worktrees** | Parallel agents on one repo: sibling worktrees created, bootstrapped with your local config, and torn down. | setup-worktree, setup_worktree, list_worktrees, remove_worktree | | **Pull-request review** | An adversarial review of a teammate’s PR across correctness, security, regressions, and tests, verified against the code and the local build, with comments ready to paste at file and line. Reply mode judges every thread on your own PR. Once it lands, a deploy health check verifies the rollout. | pr-review, github_pr_view, github_pr_diff, github_pr_checks, github_pr_comments, github_run_log | | **API collections** | Requests drafted as Bruno collections, or plain curl, that you fire from your own client. | api-collections, curl_run | | **Deploy health check** (with a deployment) | Post-deploy verification anchored on the commit, with a canary traced through the changed code, or a standing sweep across the whole system. Pass, warn, or fail per check, read-only, saved as a report. | health-check | | **Plan specs** | An intent turned into a spec and a plan before any code is written. | plan-spec | | **Simplify** | A change or an area reviewed and made simpler, without changing what it does. | simple-simplify | | **Flow audits** (with a deployment) | A critical flow (onboarding, identity verification, a rate-limited endpoint) audited end to end against its spec and its live data, with findings and fix prompts. | kyc-flow-audit, rate-endpoint-audit | | **Tests, from the session** (with a deployment) | The repo’s own test commands discovered and run from inside the session, results read back. | testing_commands, testing_run | | **GitHub, from the session** | Issues, pull-request lists, workflow runs, and fast-forwards without leaving the terminal. | github_issue_list, github_issue_view, github_pr_list, github_run_list, github_fast_forward | | **Release and upgrade** | Versioned releases with an upgrade contract; a home reconciled after every update. | release, upgrade, run_upgrade | ## The loop, in order [#the-loop-in-order] 1. `plan-spec` turns an intent into a spec and a plan before code. 2. `setup-worktree` gives each stream of work its own bootstrapped checkout, so parallel agents never collide. 3. `pr-review` reviews a teammate's pull request adversarially, or replies to every thread on yours. 4. `health-check` verifies the rollout once it lands, with a canary traced through the changed code (with a deployment). 5. `release` and `upgrade` keep every home on the current plugin. - [Worktrees](/docs/agent/worktrees): Sibling worktrees, bootstrapped, zero collisions. - [Configuration](/docs/agent/configuration): The GitHub and Database packs and what they need. - [Hooks](/docs/agent/hooks): The guard that checks every shell command. # Modules are the powers (/docs/modules) A skill is a workflow the agent runs when you invoke it: a briefing, a release, a worktree, a plan. A tool is something it can reach: a pull request, a database, a browser, a search. Packs group the tools that need a credential and stay dormant until one is added. All of it ships in the open-source plugin; the [catalog on the site](/modules) shows the same set grouped by what it does. ## Four groups [#four-groups] The catalog is grouped by what a capability is for. Each page lists every skill and tool in the group with how to invoke it, and links to the deeper pages. - [Plan and run](/docs/modules/plan-and-run): Projects and tasks, roadmap, the goals ladder, briefings, the session radar. - [Build and ship](/docs/modules/build-and-ship): Worktrees, pull-request review, API collections, deploy checks, releases. - [Reach and see](/docs/modules/reach-and-see): Browser, logs, database, search, chat, support desk, SEO. - [Brain and memory](/docs/modules/brain-and-memory): Capture, compile, self-review, sync, dashboard, seed bundles. ## Packs [#packs] | Pack | Needs | Unlocks | | ------------ | ---------------------------------------------------- | ------------------------------------------------------------------------ | | **SEO** | Google OAuth, optional SerpAPI and OpenPageRank keys | Search Console, PageSpeed, SERP data, domain rank, WordPress content | | **Browser** | nothing beyond the install | screenshots, PDFs, page-to-Markdown, recordings, scripted flows | | **Database** | a connection string | read-only queries and schema against a replica or a fork | | **GitHub** | a token | pull requests, checks, run logs, issues, fast-forwards, the review skill | | **API** | nothing | request collections drafted as files for your own client | External accounts and what they cost are on [Accounts](/docs/modules/accounts). ## Industry modules [#industry-modules] An industry module is the same powers tuned to one sector: the packs it needs, the skills its workflows call for, and the regulatory knowledge that sector requires, deployed per customer on the same brain and the same agent. They are described on the [site](/modules#industry) rather than here; the open plugin is the horizontal layer they build on. - [Skills](/docs/modules/skills): All 39 skills, one line each. - [MCP tools](/docs/modules/mcp-tools): The 56 tools, grouped, with what is pre-granted. - [Browser tools](/docs/modules/browser): Screenshots, PDFs, Markdown, recordings, flows. - [SEO workflow](/docs/modules/seo): Search Console, PageSpeed, SerpAPI, OpenPageRank. - [Accounts and costs](/docs/modules/accounts): The core needs zero accounts; packs add optional ones. # MCP tools (/docs/modules/mcp-tools) The server runs outside the host's shell sandbox, which is how it reads the deny-gated secrets store, shells out to `gh`, and makes the git writes a worktree needs. Tool names are prefixed `mcp__plugin_agent-kevin_kevin__` in permission lists. | Group | Tools | | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Tasks** (7) | `task_query` · `task_get` · `task_create` · `task_update` · `task_close` · `task_thread` · `task_scan` | | **Knowledge** (7) | `capture` · `compile_status` · `compile_next` · `compile_write` · `knowledge_lint` · `links_rewrite` · `memory_prune` | | **Reports and surfaces** (2) | `report_write` · `dashboard` | | **Worktrees** (3) | `setup_worktree` · `list_worktrees` · `remove_worktree` | | **Upgrade and hosts** (2) | `run_upgrade` · `codex_setup` | | **Seed** (3) | `seed_scan` · `seed_export` · `seed_import` | | **Database** (4) | `database_list` · `database_schema` · `database_query` · `database_fork` | | **GitHub** (11) | `github_pr_list` · `github_pr_view` · `github_pr_comments` · `github_pr_diff` · `github_pr_checks` · `github_run_list` · `github_run_view` · `github_run_log` · `github_issue_list` · `github_issue_view` · `github_fast_forward` | | **Browser** (6) | `browser_screenshot` · `browser_pdf` · `browser_markdown` · `browser_record` · `browser_flows` · `web_search` | | **SEO** (8) | `serpapi_search` · `open_page_rank` · `google_auth` · `gsc_sites` · `gsc_query` · `gsc_inspect` · `page_speed_psi` · `page_speed_audit` | | **Utilities** (3) | `curl_run` · `video_frames` · `ping` | ## What is granted when [#what-is-granted-when] | Class | Tools | Granted | | ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ | | **Always-on core** | tasks, knowledge, `report_write`, `dashboard`, `setup_worktree`, `run_upgrade`, `codex_setup`, `seed_scan`, `seed_export`, `video_frames`, `ping` | At init, in `permissions.allow` | | **Pack-gated** | SEO, Browser, Database, GitHub groups | When you activate the pack in `configure-skills` | | **Always ask** | `remove_worktree` (deletes a worktree), `seed_import` (overwrites identity files, merges permissions and MCP registrations), `curl_run` (leaves the machine) | In `permissions.ask`, so no mode can auto-approve them | | **Prompt on use** | `list_worktrees`, and any pack tool whose pack is not active | Default host behaviour | This keeps `settings.json` an accurate audit trail: it advertises only the packs you opted into. ## Notes on a few [#notes-on-a-few] * **`compile_*`** return prompts; your session does the synthesis; `compile_write` confirms. See [The brain](/docs/platform/the-brain). * **`database_*`** read tools run inside a `BEGIN READ ONLY` transaction with a statement timeout, then roll back, so Postgres itself rejects writes. `database_fork` is the one write: it clones a local database via `CREATE DATABASE … TEMPLATE …` for risky schema work. * **`github_*`** wrap the `gh` CLI with a read-only fine-grained token. There are no write subcommands; commenting, merging, and re-running workflows stay a human-in-terminal activity. `github_fast_forward` is the one git write: a forward-only fetch of your local default branches during sync. * **`web_search`** is a direct call to the Perplexity Search API with citations. * **`curl_run`** runs outside the sandbox with a host-scoped grant; `video_frames` extracts stills from a recording. # Plan and run (/docs/modules/plan-and-run) Everything here reads and writes the home: tasks are files, goals live in the board, briefings are reports. Run a skill as `/agent-kevin:` in Claude Code or `$` in Codex; the agent calls tools on its own when a request needs them. | Capability | What it does | Skills and tools | |---|---|---| | **Projects and tasks** | One markdown file per task with frontmatter and a thread. A board that regenerates from them. | create-project, archive-project, task_create, task_update, task_thread, task_query, task_close, task_scan | | **Roadmap** | A north-star plan rendered as one self-contained HTML page: lanes, milestones, horizons. | roadmap | | **Goals ladder** | Yearly, monthly, and weekly goals set by interview and tied to real tasks. | yearly-goals, monthly-goals, weekly-goals | | **Flywheel** | A cross-project working session: triage every active task against the roadmap, advance each project. | flywheel | | **Briefings and pulses** | Morning and evening briefings, a one-minute pulse, a standup built from git and sessions. | morning-briefing, evening-briefing, quick-pulse, standup | | **Session radar** | What every session worked on, where it left off, and its resume command. Find one by what it did. | where-am-i, find-session | | **Customer bugs and requests** (with a deployment) | Your support channels mined for reported defects and feature asks: a severity-ranked bug report and a voice-of-customer report, both mapped to the backlog. | customer-bugs, customer-feature-requests | | **Itineraries** | A trip planned end to end into a print-ready HTML itinerary. | itinerary | ## A day with it [#a-day-with-it] 1. `morning-briefing` at the start: priorities, drafted artifacts, the goals delta, a per-project pulse. 2. `where-am-i` when you have been away: every session, where it left off, the resume command. 3. `weekly-goals` on Monday, `monthly-goals` on the first, `yearly-goals` each quarter. Each one interviews you before drafting. 4. `flywheel` when several projects need a push in one sitting. 5. `evening-briefing` at the end: what shipped, what stalled, tomorrow's first move. - [Tasks and projects](/docs/agent/tasks): One file per task, frontmatter, threads, the generated board. - [Daily rhythm](/docs/agent/daily-rhythm): The cadence skills in detail. - [Dashboard](/docs/dashboard): Where all of it renders as one page. # Reach and see (/docs/modules/reach-and-see) Access, not guesses. Every capability here is read-only against the system it reaches; nothing writes to production. Packs switch on when a credential is added, and the ones marked *with a deployment* come with a forward-deployed setup because they need your systems to exist. | Capability | What it does | Skills and tools | |---|---|---| | **Browser** | A bundled headless browser for screenshots, styled PDFs, page-to-Markdown, and recordings, plus scripted flows that sign in and click through real pages. | browser-flows, browser_flows, browser_screenshot, browser_pdf, browser_markdown, browser_record, video_frames | | **Logs and uptime** (with a deployment) | Your telemetry, queried from the session: a request timeline by correlation ID, error rates, incidents, and the log lines behind a customer report. | betterstack | | **Database, read-only** | Queries and schema against a production replica, or a fork you can break. | database_query, database_schema, database_list, database_fork | | **Investigate** (with a deployment) | A ticket, a production anomaly, or a bug traced across logs, the database, the codebase, and git history into a structured brief. Read-only. | investigate | | **Web search** | Live search results with sources, from inside the session. | web_search | | **Chat, read-only** (with a deployment) | Multi-channel summaries, thread pulls, and workspace search over the channels the team works in. | slack, slack_channels, slack_history, slack_thread, slack_search | | **Support desk, read-only** (with a deployment) | Queue pulses, issue deep-dives, and account lookups from the desk your support team runs. | pylon, pylon_issues, pylon_issue, pylon_account | | **Search Console and PageSpeed** | Queries, impressions, indexing, and Core Web Vitals for any site you own. | google-search-console, google-page-speed, gsc_query, gsc_inspect, page_speed_audit | | **SERP and rank** | Real Google results, AI overviews, and a domain-authority proxy for trend tracking. | serpapi, open-page-rank, serpapi_search, open_page_rank | | **SEO audit and WordPress** | A read-only audit across every SEO source, and WordPress content through its public API. | google-search-audit, wordpress-rest | ## Investigating something [#investigating-something] A customer report becomes a timeline by correlation ID from the logs, the affected rows from the read-only replica, the commit that introduced the change from git, and a draft fix with a test that replays the failing request. `investigate` runs that end to end; the pieces are available on their own. - [Browser tools](/docs/modules/browser): Screenshots, PDFs, Markdown, recordings, flows. - [SEO workflow](/docs/modules/seo): Search Console, PageSpeed, SerpAPI, OpenPageRank. - [Accounts and costs](/docs/modules/accounts): What each pack needs and what it costs. # SEO workflow (/docs/modules/seo) The SEO pack ships with the plugin and activates through `configure-skills`. Every skill is read-only against the services it queries. | Skill | Source | What it answers | | ----------------------- | ------------------ | -------------------------------------------------------------------------------------------------- | | `google-search-console` | GSC API | Queries, impressions, clicks, CTR, average position, indexing status | | `google-page-speed` | PageSpeed Insights | Lighthouse plus Core Web Vitals (LCP, CLS, INP, FCP, TBT, SI) for any public URL | | `serpapi` | SerpAPI | Live Google SERP: organic, AI overview, shopping, people-also-ask, knowledge graph | | `open-page-rank` | Open Page Rank | A free domain-authority proxy, 0 to 10, for trend tracking | | `wordpress-rest` | Public WP REST API | Posts, pages, custom types, categories, tags, media, modified dates for the site at `GSC_SITE_URL` | | `google-search-audit` | All of the above | Four audit rules, findings ranked by impact, a Markdown report, matches threaded into open tasks | ## The weekly loop [#the-weekly-loop] Configure the keys once. Run `google-search-audit` weekly. The audit pulls 28 days of Search Console data, runs PageSpeed on the top pages, applies the rules, and writes the report to the project's `audits/` folder. Findings that match an open task get threaded onto it. Pair with the optional third-party libraries for content drafting and EEAT scoring: `aaron-he-zhu/seo-geo-claude-skills` (20 skills) and `coreyhaines31/marketingskills` (23 playbooks) install through `configure-skills` via skills.sh, as symlinks into the skills.sh cache so upstream updates propagate. ## Setup [#setup] Four of the six need credentials: SerpAPI and OpenPageRank keys, and a Google OAuth client plus `GSC_SITE_URL` for the two Google skills. `wordpress-rest` needs only the site URL. Account signup, quotas, and costs: [Accounts](/docs/modules/accounts). A typical personal setup runs on free tiers. # Skills (/docs/modules/skills) Every skill runs as `/agent-kevin:` in Claude Code and `$` in Codex; these docs use the bare name. Skills marked **auto** may run on their own when the request clearly calls for them; they are read-only and never mutate knowledge or task state. Everything else waits for you to ask. ## Core (30) [#core-30] ### Setup and lifecycle [#setup-and-lifecycle] | Skill | What it does | | ------------------------------------ | ----------------------------------------------------------------------------------------------------------------- | | `init` | Guided first-run onboarding: name, SOUL, IDENTITY, your basics, optional web pull, packs; scaffolds the home | | `configure-skills` | Activate the SEO, Browser, Database, GitHub, or API pack, install third-party libraries, or author a custom skill | | `rename-agent` | Change the agent's display name across an existing home without forking the plugin | | `upgrade` | Apply pending home migrations after a plugin code update | | `release` | Maintainer only: cut a versioned release with a CHANGELOG entry and Upgrade block | | `create-project` / `archive-project` | Project lifecycle | | `seed-export` / `seed-import` | Hand a persona and setup to a teammate as a zip; import one with fork semantics. Import is **auto** | ### Knowledge and maintenance [#knowledge-and-maintenance] | Skill | What it does | | ------------------- | ------------------------------------------------------------------------------------- | | `knowledge-compile` | Compile raw sessions, feedback, and inbox items into wiki articles | | `sync` | End-to-end maintenance in one pass, ending in a status line and an optional next move | | `flywheel` | Cross-project work session framed by the north-star roadmap | | `self-review` | Turn accumulated feedback into prompt and skill edits | | `mermaid` | Parse-check and visually critique a Mermaid diagram before it ships | | `humanizer` | Strip the tells of AI-generated prose | | `simple-simplify` | Review a script, app, or change and simplify it | ### Cadences [#cadences] | Skill | What it does | | ------------------------------------------------- | ------------------------------------------ | | `morning-briefing` / `evening-briefing` | Daily orient and wrap | | `quick-pulse` | A one-minute status scan | | `standup` **auto** | Did / next / blocked for the last 24 hours | | `weekly-goals` / `monthly-goals` / `yearly-goals` | The goals ladder in `TASKS.md` | ### Navigation and surfaces [#navigation-and-surfaces] | Skill | What it does | | ----------------------- | --------------------------------------------------------------------------- | | `dashboard` **auto** | Refresh and open the Agent OS dashboard | | `where-am-i` **auto** | Recent sessions radar with resume commands; `triage` and `checkpoint` modes | | `find-session` **auto** | Find a past session by what it worked on | | `roadmap` **auto** | Build or update a strategic roadmap as a self-contained HTML surface | | `itinerary` | Plan a trip and render an interactive, print-ready HTML itinerary | | `plan-spec` | Socratic interview into a standalone, plan-compatible spec | ### Code [#code] | Skill | What it does | | ---------------- | --------------------------------------------------------------------------------- | | `setup-worktree` | Create a sibling git worktree and bootstrap it; also the read-only worktree audit | ## SEO pack (6) [#seo-pack-6] `google-search-console` · `google-page-speed` · `serpapi` · `open-page-rank` · `wordpress-rest` · `google-search-audit`. Details on the [SEO workflow](/docs/modules/seo) page. ## Browser pack (1 skill, 6 tools) [#browser-pack-1-skill-6-tools] `browser-flows` drives a visible browser through repeatable flows. The pack also grants the `browser_*` tools and `web_search`. See [Browser tools](/docs/modules/browser). ## API pack (1) [#api-pack-1] `api-collections` **auto** drafts API requests as collection files you open and fire in your own client (Bruno adapter shipped, plain-curl fallback). Authoring only; Kevin never sends. ## GitHub pack (1) [#github-pack-1] `pr-review` reviews a teammate's PR adversarially (seven parallel lanes, every finding verified, build and tests in a throwaway worktree, paste-ready comments with committable suggestions) or, on your own PR, judges each review thread against the code, applies the accurate fixes uncommitted, and drafts the replies. Read-only against GitHub; you paste. Tools in [Configuration](/docs/agent/configuration#github-pack). ## Database pack [#database-pack] Tool-only, no skills. See [Configuration](/docs/agent/configuration). ## Third-party libraries [#third-party-libraries] Pure-prompt content and marketing libraries are not bundled. `configure-skills` installs them from [skills.sh](https://skills.sh) into `/.claude/skills/` as symlinks, so upstream updates propagate. Currently offered: `aaron-he-zhu/seo-geo-claude-skills` (20 skills, Apache-2.0) and `coreyhaines31/marketingskills` (23 playbooks). > **Writing your own** Custom-skill authoring is not a Kevin skill. `configure-skills` points you at your host's skill-authoring tooling (Claude Code ships a `skill-creator` plugin). # The agent home (/docs/platform/agent-home) The home is the directory you launch from. It is the brain, the work, and the runtime state, all as files. ```text / ├── .claude/ │ ├── CLAUDE.md # Claude Code bridge: @-imports AGENTS.md + the identity stack │ ├── assets/ # Kevin's avatar │ ├── skills/ # third-party skill libraries (skills.sh), lazy │ ├── settings.json # enabledPlugins + pre-granted permissions │ └── settings.local.json # non-secret env (GSC_SITE_URL, AGENT_CODE_PATH), gitignored ├── .codex/ # Codex wiring, only on homes that run Codex: hooks, MCP server, profile ├── .kevin/ # plugin runtime state (hidden) │ ├── secrets/ # deny-gated credential store, gitignored, Kevin can't read it │ │ ├── .env # API keys + AGENT_DB_ connection strings │ │ └── google/ # Google OAuth client JSON + cached tokens │ ├── updates/ # per-upgrade file backups │ ├── logs/ │ ├── version.json # template baseline (drives upgrade tracking) │ └── knowledge.json # compile state ├── knowledge/ # (or AGENT_KNOWLEDGE elsewhere) │ ├── concepts/ # cross-cutting articles │ ├── memory/ # hot context: threads, decisions, learnings │ ├── raw/ # unprocessed inputs to compile │ │ ├── sessions/ # auto-captured conversations │ │ ├── inbox/ # anything you drop in for distillation │ │ ├── archive/ # compiled inbox items land here │ │ └── user/feedback.md # corrections log, append-only │ ├── user/ # long-form knowledge about you │ └── index.md # master catalog ├── projects/ # (or AGENT_PROJECTS elsewhere) │ ├── / │ │ ├── README.md │ │ └── tasks/-.md │ └── TASKS.md # generated dashboard ├── reports/ # transient skill outputs │ ├── index.md # newest-first log; today's entries reach SessionStart │ ├── briefings/ # morning/evening, goals, self-review │ ├── captures/ # browser-tool artifacts, gitignored │ └── plans/ # self-review proposals + plan-mode saves ├── AGENTS.md # operating manual, harness-neutral ├── IDENTITY.md # Kevin's role + evolving self-description ├── SOUL.md # Kevin's character └── USER.md # your headline + links to knowledge/user/ ``` ## The identity stack [#the-identity-stack] Four files load at the start of every session and set the tone for everything else. | File | Voice | What it holds | | ------------- | -------------- | -------------------------------------------------------------------------------------------------- | | `SOUL.md` | Kevin's | Character: how it talks, what it values, where it pushes back | | `IDENTITY.md` | Kevin's | Name, avatar, role, and a self-description that grows as cadences land | | `USER.md` | Yours | Headline facts about you, timezone, links to the deeper user facets | | `AGENTS.md` | The operator's | The operating manual: context loading, memory routing, task rules, workflow, engineering standards | `AGENTS.md` is harness-neutral. Codex reads it natively. Claude Code reaches it through `.claude/CLAUDE.md`, a short bridge that `@`-imports the manual and the identity stack and holds the few rules that only apply there. The home's settings live under `.claude/` too and are read by every host, Codex through wiring generated from them. See [Hosts](/docs/agent/hosts). ## Three kinds of state [#three-kinds-of-state] * **Knowledge** is compiled and durable: user facets, concept articles, active memory. See [The brain](/docs/platform/the-brain). * **Projects** are operational: a README per project plus one markdown file per task. See [Tasks](/docs/agent/tasks). * **Reports** are transient skill outputs: briefings, audits, plans, captures. Read-only network of links; promote anything durable into the knowledge tree. ## Where the home is found [#where-the-home-is-found] In order: an explicit `KEVIN_HOME` / `AGENT_HOME`; the nearest ancestor of the working directory carrying `.kevin/`; the same walk from the launch directory (which the host exports to hooks and MCP servers and which never moves); then the working directory as a last resort. Launch from the home and the middle two cover you for the whole session, even after you `cd` into a repo. The marker is the data dir, never `SOUL.md`. Every agent's home has a `SOUL.md`, so testing for it would answer "some agent lives here" rather than "this agent lives here", and with the fallback to the working directory that would let one agent write inside another's brain. Open the home in Obsidian and the whole tree comes alive with working wikilinks. `.claude/` and `.kevin/` stay hidden. # Capture (/docs/platform/capture) Sessions are captured automatically. Everything else goes in through `capture`: same destination, same compile pipeline, you initiate it. ## In conversation [#in-conversation] Drop a URL, paste a snippet, or hand Kevin a file path. It routes to the `capture` tool on its own. ```text you > capture this for the inbox: https://thenewstack.io/hidden-agentic-technical-debt/ kevin > wrote knowledge/raw/inbox/2026-05-29-1430-hidden-agentic-technical-debt.md you > save as feedback: when refactoring, don't touch adjacent code I didn't ask about kevin > appended to knowledge/raw/user/feedback.md you > here's my standup notes, capture with title "Standup 2026-05-28": kevin > wrote inbox you > pull in ~/notes/board-meeting.md kevin > wrote inbox ``` URL fetches run through Mozilla Readability and Turndown: the article body is extracted, nav and footer noise dropped, and the result is clean Markdown. ## From the terminal [#from-the-terminal] ```bash kevin capture "remember to follow up with tracy on constitution lodgement" kevin capture --file=~/notes/board-meeting.md --title="Board meeting 2026-05-28" kevin capture --url=https://docs.anthropic.com/en/docs/claude-code/overview pbpaste | kevin capture --stdin --title="Clipped article" kevin capture --kind=feedback "don't propose git push for local-only repos" kevin capture --file=~/spec.md --label="design-spec" ``` | Flag | Behaviour | | ----------------------- | --------------------------------------------------------------------------------------------------- | | positional or `--text=` | Inline text. The default source | | `--file=PATH` | A local file, up to 512 KB | | `--url=URL` | Fetch up to 5 MB, extract the article body, convert to Markdown. Provenance recorded in frontmatter | | `--stdin` | Read stdin. Auto-enabled when stdin is a pipe | | `--kind=inbox` | Default. Writes `knowledge/raw/inbox/-.md`, compiled into concepts and user facets | | `--kind=feedback` | Appends to `knowledge/raw/user/feedback.md`, compiled into memory Learnings | | `--title=` | Filename slug and frontmatter title. Without it, the first heading or line | | `--label=` | Free-form tag stored in frontmatter or the feedback header | Local-only, secret-redacted, atomic, content-hash deduped: re-capturing identical input short-circuits to the existing file. ## Two kinds [#two-kinds] **Inbox** is material about the world: articles, notes, specs. It distills into concept articles and user facets, then archives to `raw/archive/`. **Feedback** is material about Kevin: corrections, rules, preferences. It compiles into the Learnings block that loads every session. See [Self-evolution](/docs/platform/self-evolution). Drop a design doc into `knowledge/raw/specs/` and compile distills it into a concept too. # The platform is the brain (/docs/platform) The platform is the context layer: a folder of plain markdown that holds who the agent is, who you are, what is active, what was decided and why. Nothing here needs a server. Every host reads files, so the brain needs no integration and survives a change of model or tool. It is not a search box over your documents. Retrieval finds fragments each time it is asked; the brain keeps a continuously compiled understanding so the answer already exists before the question. That understanding compounds daily, and it is the part no one can buy their way past. ## What lives where [#what-lives-where] | Piece | Where | Page | | ---------------------------------------------------------------------- | ------------------------------------------------ | ------------------------------------------- | | The identity stack: character, role, who you are, the operating manual | `SOUL.md`, `IDENTITY.md`, `USER.md`, `AGENTS.md` | [The agent home](/docs/platform/agent-home) | | The compiled wiki: user facets, concept articles, active memory | `knowledge/` | [The brain](/docs/platform/the-brain) | | Raw intake: captured sessions, the inbox, the feedback log | `knowledge/raw/` | [Capture](/docs/platform/capture) | | Projects and tasks, one file each | `projects/` | [Tasks](/docs/agent/tasks) | | Transient outputs: briefings, plans, audits | `reports/` | [Daily rhythm](/docs/agent/daily-rhythm) | ## The loop [#the-loop] ```mermaid graph LR A[Capture] --> B[Compile] B --> C[Serve] C --> D[Feedback] D --> A ``` 1. **Capture.** Hooks record every session raw on exit. Commits, tasks, and dropped documents land in the same intake. Nothing depends on anyone remembering to write things down. 2. **Compile.** A compile pass distils raw capture into the wiki. Stale entries are pruned; the index stays small enough to load every session. See [The brain](/docs/platform/the-brain) and [Sync](/docs/platform/sync). 3. **Serve.** The wiki loads before the first prompt of the next session, on either host. 4. **Feedback.** Corrections become learnings that load every session, and a review skill turns them into changes to the agent itself. See [Self-evolution](/docs/platform/self-evolution). ## Seeded, then yours [#seeded-then-yours] The brain architecture and the compile pipeline are the open head start, identical for every home. What goes into a specific brain is that company's own: its corpus, its rules, its decisions. A [seed bundle](/docs/platform/seed-bundles) carries a persona and a curated starting point to a teammate; [multiple homes](/docs/platform/multiple-agents) keep separate brains apart on one machine. - [The agent home](/docs/platform/agent-home): One folder, what lives where, how it is found. - [The brain](/docs/platform/the-brain): Raw conversations are source; the wiki is the build. - [Capture](/docs/platform/capture): Feed it a thought, a file, a URL, a correction. - [Sync](/docs/platform/sync): Every maintenance operation in one pass. - [Self-evolution](/docs/platform/self-evolution): Feedback becomes learnings becomes prompt changes. - [Seed bundles](/docs/platform/seed-bundles): Hand an agent's persona and setup to a teammate. # Multiple agents (/docs/platform/multiple-agents) ## Several homes, one plugin [#several-homes-one-plugin] ```text ~/Documents/Agents/Kevin/ # personal projects, journals, life ops ~/Documents/Agents/Scout/ # client work, professional persona ~/Documents/Agents/Sage/ # SEO-focused, only the SEO pack configured ``` The plugin code lives once on disk; each home is independent. Switch by launching from the one you want. The home is resolved from where you launched, so nothing needs configuring to keep them apart. Give each its own name with the `rename-agent` skill (see [Naming](/docs/reference/naming)); they still share the plugin's command namespace, which is plumbing you never see once each `IDENTITY.md` carries its own name. > **The one rule** No `KEVIN_*` variable in a user-level settings file or your shell rc. It is machine-wide and outranks launch-directory resolution, so one value captures every session for one brain. Per-home config goes in that home's `settings.local.json` under the neutral `AGENT_*` names. Under Claude Code each home can even bill against its own account. See [Multiple accounts](/docs/agent/claude-code#multiple-accounts). ## Augmenting an existing project [#augmenting-an-existing-project] You already have a repo with its own `AGENTS.md` or `CLAUDE.md` and want Kevin's memory and task system layered on top. Launch your host from the repo and run the `init` skill there. Init never touches a root `CLAUDE.md` (Kevin's Claude Code bridge is `.claude/CLAUDE.md`, and both load) and appends its manual to a pre-existing `AGENTS.md` rather than replacing it. Your project context and Kevin's identity coexist. ## A team-shared agent [#a-team-shared-agent] Drop Kevin into a team repo, commit the identity stack (`AGENTS.md`, `SOUL.md`, `IDENTITY.md`, `.claude/`, `knowledge/`), and gitignore `settings.local.json`. Every teammate gets the same agent identity and trusts the plugin once on their host. For a teammate who should start from your agent but then diverge freely, use a [seed bundle](/docs/platform/seed-bundles) instead. A team with no agent yet can start every member from the same wizard bundle. ## Keeping brains and code apart [#keeping-brains-and-code-apart] Brains under `~/Documents/Agents/`, code flat under `~/Developer/`, never nested. The brain opens cleanly as an Obsidian vault, many brains can run against one code tree, and cloud sync never drags repos along. See [Workstation](/docs/workstation) for the full layout. # Seed bundles (/docs/platform/seed-bundles) A seed bundle is a plain zip: a `manifest.json` plus `files/` payloads. It is a one-shot handoff with fork semantics. Everything imported becomes the recipient's own; nothing stays linked to the source, and nothing syncs afterwards. Two producers make them: the `seed-export` skill from an existing agent, and the [wizard](#the-wizard) on dev.agentlayer.one from a short interview. One consumer reads them: the importer built into `init` and the `seed-import` skill. ## What travels [#what-travels] | Travels | Never travels | | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------- | | `IDENTITY.md`, `SOUL.md`, the avatar | `USER.md`, `knowledge/user/`, memory, sessions, feedback | | Curated operating-manual sections, appended to the recipient's `AGENTS.md` | The scaffolded manual itself, `.claude/CLAUDE.md` | | Selected `knowledge/concepts/` articles, `roadmap.html` | Task files (only `projects//README.md` and `roadmap.html` travel) | | Custom skills and rules under `.claude/` | Secret **values**, `.kevin/` state, machine-specific paths | | Permission grants (`allow` and `ask`), MCP server entries, credential key **names** | | The importer validates every path against that allow-list before writing, so a hostile bundle cannot reach settings, secrets, or anything else in the home. Key names arrive as an empty checklist; you fill the values in your editor. ## Exporting [#exporting] Run `seed-export`. It scans the home, then runs two mandatory stages: **Interview.** Scope (whole agent, a project slice, or identity only), whether the persona travels, which concepts, surfaces, custom skills, MCP servers, rules, packs, and env key names go along. Template-identical files and machine-specific paths default to excluded. **Review gate.** Every file, grant, and key name is shown before anything is zipped. Client names and personal context are yours to catch here. The zip lands in `reports/seeds/`. ## Importing [#importing] The recipient's home must already be initialised. Two ways in: * **During `init`.** The wizard asks whether you are starting from a teammate's seed bundle. Say yes and point at the zip; it is applied after the scaffold, and the remaining questions skip what the seed already answers. * **Later, with `seed-import`.** Hand over the zip path. The skill dry-runs first and shows the plan: files by category, the manual section to append, conflicts, setup merges, and the credential names. Then it asks whether to overwrite the conflicting files. On a fresh home the expected conflicts are `IDENTITY.md` and `SOUL.md`: init scaffolded them, the seed replaces them, which is the point. Anything else diverging deserves a look. Re-importing the same bundle skips the manual section it already appended. > **Codex homes** If the bundle added `ask` entries and the home runs Codex, the import regenerates the Codex rules file, since those prompts are generated from the ask list. Restart any open session on either host afterwards so the new identity, permissions, and MCP servers load. ## The wizard [#the-wizard] The wizard at [dev.agentlayer.one](https://dev.agentlayer.one/#wizard) asks eleven prompts about a company and produces the same bundle format with no source home: `IDENTITY.md`, `SOUL.md`, a day-zero section for `AGENTS.md`, a company-profile concept, an optional roadmap draft and pasted notes, and one README per seeded project. Download it, install the plugin, run `init`, and point it at the zip. The agent wakes up named, characterised, and briefed, and its first sessions absorb the listed links into the knowledge base. ## From the terminal [#from-the-terminal] The CLI has the same surface without the interview or review gate; you are the gate. ```bash kevin seed scan kevin seed export --include=IDENTITY.md,SOUL.md,knowledge/concepts/flywheel.md --name=Scout kevin seed import ~/Downloads/scout-seed.zip --dry-run ``` For ongoing knowledge sync between agents this is the wrong tool; use a [shared repo](/docs/platform/multiple-agents#a-team-shared-agent). # Self-evolution (/docs/platform/self-evolution) ```mermaid graph LR CAP["Reactions + corrections in chat"] FB["raw/user/feedback.md"] SYN["compile: feedback synthesis"] LN["memory/index.md · Learnings"] NEXT["next session"] REV["self-review skill"] EDIT["edits to SOUL, AGENTS.md, skills"] PLANS["plans to reports/plans/"] CAP --> FB FB --> SYN SYN --> LN LN -.->|loaded every session| NEXT FB --> REV REV --> EDIT REV --> PLANS ``` ## Feedback is durable [#feedback-is-durable] Every correction you give mid-conversation ("don't do that", "actually, that's wrong") lands in `knowledge/raw/user/feedback.md`, append-only. The next compile synthesizes all feedback into a Learnings block in `knowledge/memory/index.md`, which loads at the start of every future session. Kevin sees its own past misses while it works. ## Self-review [#self-review] When you have ten minutes, run `self-review`. It casts a wide net across eight sources: the Learnings synthesis, the full feedback log, the last seven days of sessions and task threads, git history, concept articles, in-flight plans, and installed skills. It greps for both correction and confirmation phrases; wins validate non-obvious choices. Each theme is classified as **missing**, **buried**, **present but violated**, or **present and working**. The point is catching rules that landed but did not stick. Themes rank by severity × instances × cycles; anything with fewer than two independent signals is dropped. If nothing clears the bar, Kevin says so and stops. Proposals come in three tracks: | Track | What | Applied | | ----- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | | **A** | Prompt or skill edits. Identity → `SOUL.md`, procedural → `AGENTS.md`, skill-specific → that skill | In session, you pick which to accept | | **B** | Code-change plans written to `reports/plans/` | Never auto-applied; you implement them in a separate session | | **C** | Install or create a skill, only for a recurring multi-step procedure | Explicit approval required | Aging proposals (over 14 days, no follow-through) get re-surfaced, downgraded, or closed. A quality gate runs before anything lands: every target file actually read, specific evidence with timestamps and quotes, and for any pre-existing rule, violations counted after it was introduced. Three stages, loosely coupled: capture is automatic, compile is on demand, review is manual. No ceremony. # Sync (/docs/platform/sync) `sync` brings every derived view current at once. Heavier than `quick-pulse`, lighter than running each skill by hand. Run it when you have been away, when you want to start fresh, or when something feels stale. ```mermaid flowchart TD SES[/raw/sessions/] -.pending.-> C1 INB[/raw/inbox/] -.pending.-> C1 FB[/raw/user/feedback.md/] -.pending.-> C1 START([sync]) --> C1[1. Compile pending raw inputs] C1 --> C2[2. Lint + auto-fix] C2 --> C3[3. Prune transient memory] C3 --> C4[4. Rewrite stale wikilinks] C4 --> C5[5. Flywheel: advance · archive · persist] C5 --> C6[6. Scan for overdue and stale] C6 --> C7[7. Refresh both dashboards] C7 --> OUT([Status block]) OUT --> GATE{Anything actionable?} GATE -->|clean bill| DONE([done]) GATE -->|yes| ASK[8. Closing interview: act now or queue] C1 -.synthesis in your turn.-> WIKI[(knowledge/)] C5 -.advance · update · close.-> TASKMUT[(task files)] C7 -.one call, both views.-> TASKS[/TASKS.md + dashboard.html/] ``` ## Why the order matters [#why-the-order-matters] Compile feeds the wiki state that lint operates on. Lint's auto-fix touches the same articles the dashboard's link rewriter needs clean. Flywheel runs after the wiki is clean, so it reads a current memory index, and before scan and dashboard refresh, so both views reflect post-flywheel task state. Out of order, you re-reconcile. ## What flywheel does [#what-flywheel-does] Flywheel is a cross-project work session framed by your north-star roadmap. It advances tasks, updates threads, closes what is done, and keeps milestone statuses honest. Two sub-steps run every sync unconditionally: the archive sweep (closed tasks into `tasks/archive/`) and a snapshot to `reports/briefings/flywheel/` so the next morning brief can pick up the trail. ## The closing interview [#the-closing-interview] Only when sync surfaced something to act on (an overdue item, a due cadence skill, a pending upgrade, a concrete next move) does it end with a single question: pick what to tackle, then act on it now or queue it as a task. On a clean bill, the status block is the end. ## Chaining a briefing [#chaining-a-briefing] `sync morning` or `sync evening` runs the matching briefing after the maintenance pass. With no argument, sync picks: a forgotten morning brief still runs in the afternoon instead of silently becoming an evening one. The status block reads from artifacts on disk (`projects/TASKS.md`, `.kevin/lint.md`, `knowledge/memory/index.md`), not from per-tool return values, so the summary reflects what actually landed. # The brain (/docs/platform/the-brain) Kevin's long-term memory follows Andrej Karpathy's [LLM Wiki](https://gist.github.com/karpathy/442a6bf555914893e9891c11519de94f) pattern. ```mermaid graph LR HOOK[SessionEnd hook] --> SES[raw/sessions/] PRE[PreCompact hook] --> SES SES --> C[knowledge-compile] FB[raw/user/feedback.md] --> C INBOX[raw/inbox/] --> C C --> USER[user/] C --> CON[concepts/] C --> MEM[memory/] USER -.-> NEXT[next session] CON -.-> NEXT MEM -.-> NEXT ``` ## Capture is automatic [#capture-is-automatic] Every time you exit a session, or the host compacts mid-session, a hook calls `kevin session-capture`. It reads the host's transcript and appends it to today's log at `knowledge/raw/sessions/YYYY-MM-DD.md`. Secrets are redacted before anything is written: exact matches against every value in `.kevin/secrets/.env` and `settings.local.json`, plus prefix heuristics for common key formats (`sk-`, `pplx-`, `AIza`, `sk-ant-`, `gh[pous]_`). Each host's transcript format has a small adapter inside the capture module. Adding a host is a new adapter, not a new hook script. ## Capture anything else by hand [#capture-anything-else-by-hand] A thought, a meeting note, a clipped article, a file, a URL, a correction. Same destination, same pipeline, you just initiate it. In conversation, just ask: ```text you > capture this for the inbox: https://example.com/some-article kevin > wrote knowledge/raw/inbox/2026-05-29-1430-some-article.md you > save as feedback: when refactoring, don't touch adjacent code I didn't ask about kevin > appended to knowledge/raw/user/feedback.md ``` The CLI flags and the two capture kinds are on the [Capture](/docs/platform/capture) page. ## Compile is on demand [#compile-is-on-demand] `knowledge-compile` picks up every session log whose hash changed since the last compile, every inbox item, and every new feedback entry. The MCP server returns a synthesis prompt; **you**, in your own session, synthesize; the server confirms the write. Idempotent, hash-tracked, interruptible. | Output | Lifecycle | What lives there | | --------------------- | -------------------------------- | -------------------------------------------------------------------------------------------- | | `knowledge/user/` | Permanent, evolves with you | profile, skills, preferences, career, interests | | `knowledge/concepts/` | Permanent, cross-cutting | patterns spanning several projects; specs distill here | | `knowledge/memory/` | Hot context, loads every session | active threads, recent decisions, learnings from feedback. Daily entries prune after 14 days | > **Why this stays cheap** The compile tool returns a prompt. Your session runs the synthesis on your host's plan. The result is written back through another tool call. No LLM-as-a-service inside the plugin, no API billing. ## Three stages, loosely coupled [#three-stages-loosely-coupled] Capture is automatic. Compile is on demand. Review is manual. `sync` runs compile as its first step, so most people never call compile directly. See [Sync](/docs/platform/sync). # CLI (/docs/reference/cli) ```bash export PATH="$HOME/Developer/agent-kevin/bin:$PATH" # a clone; a marketplace install lives in your host's plugin cache kevin help ``` `kevin help` prints every group, command, flag, env var, and example. The major groups: | Group | What it does | | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | `kevin task ` | Query, get, create, update, close, thread, scan tasks | | `kevin capture` | Feed the inbox or the feedback log. See [Capture](/docs/platform/capture) | | `kevin dashboard` | Rebuild `projects/TASKS.md` and `dashboard.html` | | `kevin knowledge lint [--fix]` | Structural wiki check: broken links, orphans, missing backlinks, invalid frontmatter. `--fix` rewrites links and inserts backlinks | | `kevin compile ` | `status` (queue), `next` (peek), `write ` (mark complete). Synthesis itself needs a session | | `kevin prune` | Delete daily memory older than the retention window (14 days) | | `kevin links` | Rewrite bare task ids and shorthand into wikilinks across the wiki | | `kevin seed ` | `scan`, `export`, `import [--dry-run] [--overwrite]` | | `kevin worktree --branch=` · `worktree list` · `worktree remove` | Create and bootstrap a sibling worktree; audit every worktree with a verdict; remove one safely | | `kevin database ` | `list`, `schema`, `query`, `fork` against the configured Postgres connections | | `kevin session-start` · `session-capture` · `guard` | The hook entry points | | `kevin ping` | Print resolved paths and timezone | ```bash kevin task query --status=active kevin task create --project=blog-dev --title="Draft launch post" --priority=P1 --type=task kevin task thread bd-004 --message="Outline drafted" --type=info kevin knowledge lint --fix kevin compile status ``` ## Running outside a session [#running-outside-a-session] The CLI resolves its home from the current directory, and a plain terminal has no launch directory to fall back on. Run it from inside the home, or point it at one: ```bash KEVIN_HOME=~/Documents/Agents/Kevin kevin task query --status=active ``` Anywhere else it refuses and tells you what it resolved, rather than scaffolding a `knowledge/` tree into whatever repo you were standing in. > **Compile still needs a session** The compile pipeline returns prompts, not synthesized output, so full evolution runs through `knowledge-compile` or `sync` inside a session. The CLI prepares and inspects; it does not think. # Naming your agent (/docs/reference/naming) Two separate things: | | Lives in | Changeable | | -------------------------------------------------------------------------------------------------------- | ----------------------------- | ---------------- | | **Display name**: what it calls itself, what the dashboard shows | `IDENTITY.md` → `- **Name:**` | Freely, any time | | **Namespace**: the `agent-kevin` command prefix on every host, `KEVIN_*` vars, `.kevin/`, MCP tool names | The plugin manifests | Only by forking | `init` asks for a name, an emoji, and an avatar up front. Everything downstream reads the answer: templates are written in that name, the session banner and `TASKS.md` header render it, and the compile prompts refer to it, so your compiled memory speaks about the agent you actually named. ## Renaming an existing home [#renaming-an-existing-home] `rename-agent` does the migration. It runs only when you type the command and asks for permission even then, because it rewrites files across the whole brain: persona fields, the avatar, and the prose across `SOUL.md`, `AGENTS.md`, `USER.md`, knowledge, and projects. It leaves the plumbing and your home directory path alone. It is also the repair path for a half-finished rename. Renaming survives updates: the upgrade skill resolves the name from your `IDENTITY.md` before diffing templates. ## Forking is a different decision [#forking-is-a-different-decision] Change `name` in the plugin manifests (`.claude-plugin/plugin.json`, `.codex-plugin/plugin.json`) and the env prefix follows (`agent-scout` reads `SCOUT_*`), giving you your own command namespace. The price is merging from upstream on every release, forever. If you only want the agent to feel like yours, rename it and skip the fork. # Upgrades and releases (/docs/reference/upgrades) ```mermaid graph LR A["release
(maintainer)"] -->|CHANGELOG + tag| B["plugin update
on your host"] B -->|upgrade skill| C["your home
reconciled"] ``` A plugin update replaces files in the plugin directory. Your home was copied out of `templates/` once at init and has been yours to edit ever since, so a code update cannot safely overwrite it. The home is reconciled separately, on your terms. ## Detecting "behind", locally [#detecting-behind-locally] The home records its template version in `.kevin/version.json` (git-tracked, so it survives a clone). Compared against the installed `plugin.json`, that yields three states, shown on the SessionStart banner and the dashboard badge: | State | Meaning | Signal | | --------- | ------------------------------------------- | ----------------------------------- | | `current` | baseline equals installed | nothing | | `pending` | baseline behind installed; migrations await | amber badge "upgrade available · N" | | `onboard` | no `version.json` yet | "enable update tracking" | ## The consumer flow [#the-consumer-flow] **Preflight.** Checks the plugin's registration: a checkout registered under a name its catalog no longer carries, a retired marketplace repo, or a stale Codex registration, each with the exact commands that fix it. **Scope.** Reads the Upgrade blocks for every release between your baseline and the installed version, or all of them on a first run. Many versions behind is one pass. **Coalesce.** Merges the actions, latest wins. The target is the current template state, not a replay of every intermediate edit. **Back up.** Snapshots every file it will touch into `.kevin/updates/-to-/` . **Apply.** `deps` runs `bun install` ; `settings` merges missing permission entries and never removes yours; `file` copies new files only if absent; `template/` section-merges `AGENTS.md` , `SOUL.md` , and friends: new sections added, changed ones updated, sections you added preserved. Optional changes ask first, with a diff. **Stamp and sync.** Writes the new baseline, then runs sync so the dashboard and knowledge reflect the new state. Guarantees: always backs up first, never overwrites a file wholesale, never deletes a section it does not recognize, only auto-applies what the release marked mandatory or additive, idempotent. Renaming survives upgrades: the skill resolves the agent's name from your `IDENTITY.md` before diffing, so template changes arrive phrased in your agent's name. ## The maintainer flow [#the-maintainer-flow] `release` diffs everything since the last tag, groups it into Added / Changed / Fixed, detects what consumers need by inspecting the diff (dependency changes, touched templates, new skills or tools needing permissions), writes the Upgrade block, bumps the version, prepends the CHANGELOG entry, and stages a commit and tag for approval. It never commits or pushes on its own. ## The Upgrade-block format [#the-upgrade-block-format] Each release carries an `### Upgrade` section. Every actionable line is a backticked tag plus a note: ```text - `: ` — ``` | kind | severity | what the upgrade does | | -------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------- | | `deps` | `required` | runs `bun install` | | `settings` | `mandatory` | adds the named permission, hook, or env entries | | `file` | `additive` | copies a new file if absent | | `template/` | `mandatory` | section-merges, applied automatically | | `template/` | `optional` | section-merges, asks first with a diff | | `script` | `required` | runs a one-time migration at `skills/upgrade/scripts/.ts` through the `run_upgrade` tool, outside the sandbox | | `manual` | any | a step only you can do; surfaced, never silent | A code-only release writes one line: `None — code-only, no bun install or HOME changes.` # cmux (/docs/workstation/cmux) [cmux](https://cmux.com) renders through `libghostty` and reads your existing Ghostty config, so the look and keybindings carry straight over. It is built for the parallel-agent era: instead of one terminal with one session, you get **workspaces** in a vertical sidebar, each showing its git branch, PR status, working directory, and the latest agent notification. ## Why it fits Kevin [#why-it-fits-kevin] * **One workspace per agent task.** Kevin in one, a coding agent in another, a long research run in a third. Split panes within a workspace for editor, logs, and agent. * **Notifications that tell you who is waiting.** When an agent finishes or needs input, its pane rings and the sidebar tab lights up. You know which of your six running agents wants attention without staring. * **Organize like a file system.** Group workspaces into folders, colour-code by project, and the sidebar becomes a live map of everything in flight. * **Session restore.** Layouts, directories, and scrollback survive closing the lid. ## Pairing with worktrees and Kevin [#pairing-with-worktrees-and-kevin] One workspace per worktree, one agent per workspace. See [Worktrees](/docs/agent/worktrees). Kevin's `where-am-i` skill reads cmux's structured state where it is available, so the session radar can say which workspace a session lives in rather than guessing from rendered text. > **Launch from the home** A multiplexer that opens workspaces at repo paths will start sessions outside the agent home, and those sessions are not captured. Open the Kevin workspace at `~/Documents/Agents/Kevin` and reach repos through `additionalDirectories`. See [Onboarding](/docs/getting-started/onboarding#the-one-convention). cmux is open source (AGPL-3.0, by Manaflow AI). # Editor and tools (/docs/workstation/editor-and-tools) ## VS Code, not Cursor [#vs-code-not-cursor] If the terminal is now where agents do the work, Cursor is overkill: its whole pitch is an AI layer in the editor, a second AI surface you do not use. Plain [VS Code](https://code.visualstudio.com) is enough for reading diffs, quick manual edits, and extensions. The editor becomes a viewer and tweaker; the terminal is the cockpit. ## Obsidian [#obsidian] Kevin's memory is markdown with `[[wikilinks]]`, and so is almost everything an agent touches: tasks, READMEs, plans, reports, articles. Open `/` as an [Obsidian](https://obsidian.md) vault and the tree comes alive. * **A real markdown workspace.** Browse and edit `projects/`, `knowledge/`, reports, and daily memory with rendering, outline, search, and tags. * **Graph view** turns the knowledge base into a visual map. You can see what is densely connected and what is orphaned. * **Wikilinks and backlinks** work the way Kevin wrote them. * **HTML-viewer plugins** open the [dashboard](/docs/dashboard) rendered inside Obsidian, next to the notes it summarizes. With `MARKDOWN_URL` at its default, dashboard links open notes in a new Obsidian tab. Brain graph in Obsidian ## MarkEdit [#markedit] [MarkEdit](https://github.com/MarkEdit-app/MarkEdit) is a free, open-source, native-Mac markdown editor with Quick Open, Quick Look, and a live preview pane through the markedit-preview extension. The payoff is a clean Markdown → HTML → PDF pipeline for anything that should look designed: a business plan, a one-pager, a report Kevin generated. Style the exported HTML with your own stylesheet, then print to PDF, or hand the HTML to Kevin's `browser_pdf` tool with the CSS applied. ## Tower [#tower] VS Code's built-in git is fine for staging a quick commit. For reviewing history, diffs, and branch topology it is cramped. [Tower](https://www.git-tower.com) gives a clear commit graph, readable side-by-side diffs, stage-by-hunk, fast branch navigation, and a first-class worktree manager. When you are reviewing what three agents did across three worktrees before merging, a real git client earns its keep. # The rig (/docs/workstation) > **Optional and opinionated** Kevin runs anywhere its host does. This section is the setup the author actually uses on a Mac, offered as a starting point. Linux and Windows have equivalents for most of it. | Piece | Pick | Why | | ------------ | ------------------------------------------------------- | -------------------------------------------------------------- | | Terminal | [Ghostty](/docs/workstation/terminal) | Native, fast, a single readable config, 25MB scrollback | | Multiplexer | [cmux](/docs/workstation/cmux) | One workspace per agent, notifications that say who is waiting | | Isolation | [Worktrees](/docs/agent/worktrees) | Parallel agents on one repo, no collisions | | Editor | [VS Code](/docs/workstation/editor-and-tools) | A viewer and tweaker; the terminal is the cockpit | | Brain reader | [Obsidian](/docs/workstation/editor-and-tools#obsidian) | Wikilinks, backlinks, graph view over the home | | Documents | [MarkEdit](/docs/workstation/editor-and-tools#markedit) | Markdown to styled PDF | | Git review | [Tower](/docs/workstation/editor-and-tools#tower) | Reviewing what three agents did across three worktrees | ## Folder structure [#folder-structure] Agent brains are standalone vaults under `~/Documents/Agents/`. Code lives flat under `~/Developer/`. Never nest one inside the other. ```text ~/Documents/Agents/ # every agent brain lives here ├── Kevin/ # the personal agent: knowledge + projects, no code │ ├── knowledge/ projects/ reports/ │ ├── SOUL.md / IDENTITY.md / USER.md │ └── .git → gitdir pointer (internals live in the code tree) └── Acme/ # a forked company agent, same shape ~/Developer/Acme/ # that company's code root: flat, no brain ├── repo-one/ # main checkout ├── repo-one-my-feature/ # worktrees as siblings └── agent-acme-data.git # the brain's git internals, out of the vault ``` The brain opens cleanly as an Obsidian vault with no source tree to index, many brains can run against one code tree, and `~/Documents` sync never drags repos along. The brain's git internals sit outside the vault via `git init --separate-git-dir`, so the vault keeps a one-line `.git` pointer and sync tools only ever see markdown. Wake an agent by launching your host from `~/Documents/Agents/`. Point it at code through `additionalDirectories`, not by launching from the repo. See [Onboarding](/docs/getting-started/onboarding#the-one-convention). # Terminal (/docs/workstation/terminal) ## Ghostty [#ghostty] [Ghostty](https://ghostty.org) is a GPU-accelerated, native-Mac terminal: 120fps with zero input lag while agents stream walls of output, native AppKit, and a single readable config file. The 25MB scrollback alone earns its keep when an agent dumps a long trace. ### A starting config (~/.config/ghostty/config) ```ini # Typography font-family = JetBrainsMonoNerdFont font-size = 14 font-thicken = true adjust-cell-height = 2 # Theme: Catppuccin with automatic light/dark switching theme = light:Catppuccin Latte,dark:Catppuccin Mocha # Window background-opacity = 0.9 background-blur-radius = 20 macos-titlebar-style = transparent window-padding-x = 10 window-padding-y = 8 window-save-state = never quit-after-last-window-closed = true window-theme = auto # Cursor and mouse cursor-opacity = 0.8 mouse-hide-while-typing = true # Security clipboard-paste-protection = true clipboard-paste-bracketed-safe = true # Shell integration shell-integration = detect # Tabs keybind = cmd+t=new_tab keybind = cmd+shift+left=previous_tab keybind = cmd+shift+right=next_tab keybind = cmd+w=close_surface # Splits keybind = cmd+d=new_split:right keybind = cmd+shift+d=new_split:down keybind = cmd+alt+left=goto_split:left keybind = cmd+alt+right=goto_split:right keybind = cmd+alt+up=goto_split:top keybind = cmd+alt+down=goto_split:bottom keybind = cmd+shift+e=equalize_splits keybind = cmd+shift+f=toggle_split_zoom # Font size keybind = cmd+plus=increase_font_size:1 keybind = cmd+minus=decrease_font_size:1 keybind = cmd+zero=reset_font_size # Reload config keybind = cmd+shift+comma=reload_config # Scrollback (25MB) scrollback-limit = 25000000 # Command finished notifications notify-on-command-finish = unfocused notify-on-command-finish-action = no-bell,notify notify-on-command-finish-after = 30s # Working directory inheritance window-inherit-working-directory = false tab-inherit-working-directory = true split-inherit-working-directory = true ``` ## Keybindings [#keybindings] Readline bindings that work in the host's prompt and in your shell. Internalize them and you stop reaching for arrow keys. | Keys | Does | | --------------------------- | --------------------------------- | | `Cmd + ←` / `Cmd + →` | Start / end of line | | `Ctrl + A` / `Ctrl + E` | Start / end of line (readline) | | `Ctrl + W` | Delete the word before the cursor | | `Ctrl + K` | Kill from cursor to end of line | | `Ctrl + U` | Clear the whole line | | `Option + ←` / `Option + →` | Move one word at a time | `Ctrl + W` and `Ctrl + K` are the two that pay for themselves daily. ## Claude Code's fullscreen renderer [#claude-codes-fullscreen-renderer] Claude Code only. Add this to your user-level `~/.claude/settings.json`: ```json { "env": { "CLAUDE_CODE_NO_FLICKER": "1" } } ``` It fixes more than the name suggests: * **Click-to-position in the prompt.** Fullscreen mode enables mouse tracking, so you can click anywhere in your prompt text to move the cursor instead of arrow-keying across a long instruction. * **No flicker.** It draws on the alternate screen buffer and pins the input box to the bottom. * **Flat memory in long sessions.** Only visible messages render.