Agent home
One folder holds everything that makes the agent yours. What lives where, what loads at session start, and how the home is found.
The home is the folder you launch from. It is the brain, the work, and the runtime state, all as files.
<HOME>/
├── .claude/ # only what Claude Code itself reads
│ ├── CLAUDE.md # Claude Code bridge: @-imports AGENTS.md + the identity stack
│ ├── rules/ # path-scoped coding rules (TypeScript, Swift), applied by file glob
│ ├── skills/ # your own skills and third-party libraries (skills.sh), lazy
│ ├── settings.json # shared policy: pre-granted permissions, deny list, sandbox
│ └── settings.local.json # this machine's: enabledPlugins, status line, non-secret env (GSC_SITE_URL, AGENT_CODE_PATH), gitignored
├── .codex/ # Codex wiring, only on homes that run Codex: hooks, MCP server, profile
├── .state/ # plugin runtime state (hidden)
│ ├── secrets/ # deny-gated credential store, gitignored, the agent 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
├── assets/ # the agent's avatar and other home-wide media
├── extensions/
│ └── skills/<skill>.md # how this home changes a plugin skill; read before that skill runs
├── 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
│ │ ├── helpdesk.md # optional queue profile for the project's support
│ │ └── 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
│ ├── plans/ # specs, self-review proposals + plan-mode saves
│ ├── radar/ # checkpoint all session snapshots
│ ├── api/ # api-collections request collections
│ ├── reviews/ # PR reviews, replies, walkthroughs + second-model dossiers
│ ├── helpdesk/ # helpdesk pulses and routines
│ ├── slack/ # slack pulses
│ ├── <your-own>/ # any folder a skill of your own files reports under
│ └── captures/ # browser-tool artifacts, gitignored
├── scripts/ # your own scripts for ongoing tasks
│ └── browser/ # your browser flows, one folder each
├── AGENTS.md # operating manual, the same for every host
├── IDENTITY.md # the agent's role + evolving self-description
├── SOUL.md # the agent's character
└── USER.md # your headline + links to knowledge/user/Open the home in Obsidian and the whole tree comes alive with working wikilinks. .claude/ and .state/ stay hidden.
Three kinds of state
| Kind | Folder | What it is |
|---|---|---|
| Knowledge | knowledge/ | Compiled and durable: user facets, concept articles, active memory. See The brain |
| Projects | projects/ | Operational: a README per project plus one markdown file per task. See Tasks |
| Reports | reports/ | Transient skill outputs: briefings, audits, plans, captures. A read-only network of links; promote anything durable into the knowledge tree |
The identity stack
Four files set the tone for everything else.
| File | Voice | What it holds |
|---|---|---|
SOUL.md | The agent's | Character: how it talks, what it values, where it pushes back |
IDENTITY.md | The agent'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 and the index of engineering principles |
AGENTS.md is written for every host. 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 apply only there. The home's settings live under .claude/ too and are read by every host, Codex through wiring generated from them. See Hosts.
What loads at session start
| Lane | What | How it arrives |
|---|---|---|
| Static, every session | SOUL.md, IDENTITY.md, USER.md, AGENTS.md, knowledge/index.md, knowledge/memory/index.md, projects/TASKS.md | Claude Code: the @-imports in .claude/CLAUDE.md. Codex: the SessionStart hook's payload |
| Dynamic, per session, capped at 10KB | The list of your skill extensions, today's date in your timezone, the last session tail, today's reports, your pinned reports, and recent git activity in the knowledge folder and your configured code repos | The SessionStart hook, on both hosts |
| By file, when a matching file is touched | .claude/rules/*.md | Claude Code, by each rule's file glob |
| On demand, never loaded for you | knowledge/user/*.md, concept articles, a project's README and tasks, a code repo's AGENTS.md | The agent reads them when the work calls for it |
To see it on your own home, run /context in Claude Code, or open the dashboard's Brain page, which lists every file with its size.
Where the home is found
The plugin looks in this order and takes the first that answers:
- An explicit
AGENT_HOME. - The nearest folder at or above the working directory that carries this agent's
.state/. - The same walk from the launch directory, which the host hands to hooks and MCP servers and which never moves.
- The working directory, as a last resort.
Launch from the home and steps 2 and 3 cover you for the whole session, even after you cd into a repo.
What marks a home is .state/version.json, which records which plugin owns the folder. A SOUL.md is not enough, since every agent has one, and neither is a .state/ that records another plugin or none: that is not this agent's home, and its secrets are never read. This is what stops one agent writing inside another's brain. A home that still has the older .kevin/ folder is on an old agent-kevin: it runs agent-kevin's upgrade first, then moves here with /agent-kevin:move. See Moving from agent-kevin.