Architecture
The brain is portable markdown. The host is the runtime. The plugin is the glue.
| 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 | <HOME>/, portable markdown |
| Obsidian | Human-facing browser for the brain | <HOME>/ 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
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 and History.
The plugin repo
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 <HOME>
├── CHANGELOG.md # release contract: Upgrade blocks drive /upgrade
└── LICENSE · NOTICE # Apache 2.0Two 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.