The agent home
One folder holds everything that makes Kevin yours. Here is what lives where.
The home is the directory you launch from. It is the brain, the work, and the runtime state, all as files.
<HOME>/
├── .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_<NAME> 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)
│ ├── <slug>/
│ │ ├── README.md
│ │ └── tasks/<id>-<slug>.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
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.
Three kinds of state
- Knowledge is compiled and durable: user facets, concept articles, active memory. See The brain.
- Projects are operational: a README per project plus one markdown file per task. See 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
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.