AgentLayer▸docs
Reference

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

KindFolderWhat it is
Knowledgeknowledge/Compiled and durable: user facets, concept articles, active memory. See The brain
Projectsprojects/Operational: a README per project plus one markdown file per task. See Tasks
Reportsreports/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.

FileVoiceWhat it holds
SOUL.mdThe agent'sCharacter: how it talks, what it values, where it pushes back
IDENTITY.mdThe agent'sName, avatar, role, and a self-description that grows as cadences land
USER.mdYoursHeadline facts about you, timezone, links to the deeper user facets
AGENTS.mdThe operator'sThe 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

LaneWhatHow it arrives
Static, every sessionSOUL.md, IDENTITY.md, USER.md, AGENTS.md, knowledge/index.md, knowledge/memory/index.md, projects/TASKS.mdClaude Code: the @-imports in .claude/CLAUDE.md. Codex: the SessionStart hook's payload
Dynamic, per session, capped at 10KBThe 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 reposThe SessionStart hook, on both hosts
By file, when a matching file is touched.claude/rules/*.mdClaude Code, by each rule's file glob
On demand, never loaded for youknowledge/user/*.md, concept articles, a project's README and tasks, a code repo's AGENTS.mdThe 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:

  1. An explicit AGENT_HOME.
  2. The nearest folder at or above the working directory that carries this agent's .state/.
  3. The same walk from the launch directory, which the host hands to hooks and MCP servers and which never moves.
  4. 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.

On this page