File Locations

AGH uses one global home directory plus optional workspace-local .agh/ directories. The global home defaults to ~/.agh and can be changed with AGH_HOME.

Quick Reference

Path	Scope	Purpose
`$AGH_HOME`	Global	AGH home root. Defaults to `~/.agh`.
`$AGH_HOME/config.toml`	Global	Global runtime config.
`$AGH_HOME/mcp.json`	Global	Global top-level MCP sidecar.
`$AGH_HOME/agh.db`	Global	Global SQLite catalog.
`$AGH_HOME/daemon.sock`	Global	Default Unix domain socket.
`$AGH_HOME/daemon.lock`	Global	Daemon lock file.
`$AGH_HOME/daemon.json`	Global	Daemon discovery metadata.
`$AGH_HOME/logs/agh.log`	Global	Structured daemon log file.
`$AGH_HOME/logs/network.audit`	Global	Append-only network audit file.
`$AGH_HOME/sessions/<session-id>/events.db`	Session	Per-session event database.
`$AGH_HOME/sessions/<session-id>/meta.json`	Session	Per-session metadata.
`$AGH_HOME/agents/<name>/AGENT.md`	Global agent	User-wide agent definition.
`$AGH_HOME/skills/<name>/SKILL.md`	Global skill	User or marketplace skill definition.
`<workspace>/.env`	Workspace	Optional dotenv file loaded before workspace config.
`<workspace>/.agh/config.toml`	Workspace	Workspace config overlay.
`<workspace>/.agh/mcp.json`	Workspace	Workspace top-level MCP sidecar.
`<workspace>/.agh/agents/<name>/AGENT.md`	Workspace agent	Workspace-local agent definition.
`<workspace>/.agh/skills/<name>/SKILL.md`	Workspace skill	Workspace-local skill definition.
`<workspace>/.agh/memory/`	Workspace memory	Workspace-scoped memory files.

Global Home

Path	Created by home layout	Description
`$AGH_HOME`	yes	Home root. Defaults to `~/.agh`; `AGH_HOME` overrides it.
`$AGH_HOME/config.toml`	no	Global TOML config file.
`$AGH_HOME/mcp.json`	no	Global MCP sidecar loaded after global TOML by the general config loader.
`$AGH_HOME/agents/`	yes	Global agent definitions.
`$AGH_HOME/skills/`	yes	Global user and marketplace skills.
`$AGH_HOME/memory/`	yes	Default global memory directory. Can be overridden by `[memory].global_dir`.
`$AGH_HOME/sessions/`	yes	Parent directory for per-session state.
`$AGH_HOME/logs/`	yes	Parent directory for daemon logs and network audit output.
`$AGH_HOME/extensions/`	no	Managed installed extension root. Created when installing managed extensions.

EnsureHomeLayout creates the root, agents, skills, memory, sessions, and logs directories. Individual files are created by the features that own them.

Global Runtime Files

Path	Format	Description
`$AGH_HOME/agh.db`	SQLite	Global catalog database for sessions, workspace registrations, observability summaries, extension records, automation state, and network records. SQLite may create `agh.db-wal` and `agh.db-shm` sidecars.
`$AGH_HOME/daemon.sock`	Unix domain socket	Default CLI and UDS API socket. `[daemon].socket` can point elsewhere.
`$AGH_HOME/daemon.lock`	Lock file	Daemon process lock.
`$AGH_HOME/daemon.json`	JSON	Discovery file containing daemon PID, HTTP port, start time, and optional network diagnostics.
`$AGH_HOME/logs/agh.log`	log file	Structured daemon log file path from the home layout.
`$AGH_HOME/logs/network.audit`	log file	Append-only network audit file.

Session Files

Every durable session owns a directory under $AGH_HOME/sessions/.

~/.agh/sessions/<session-id>/
  events.db
  meta.json

Path	Format	Description
`$AGH_HOME/sessions/<session-id>/events.db`	SQLite	Per-session event store for ACP events, turns, token usage, permission decisions, and hook run history.
`$AGH_HOME/sessions/<session-id>/meta.json`	JSON	Quick metadata used by session listing and reconciliation paths.

Agent Files

Path	Scope	Description
`$AGH_HOME/agents/<name>/AGENT.md`	Global	Agent available across workspaces.
`$AGH_HOME/agents/<name>/mcp.json`	Global agent	Optional agent-local MCP sidecar.
`<workspace>/.agh/agents/<name>/AGENT.md`	Workspace	Agent available to sessions in that workspace.
`<workspace>/.agh/agents/<name>/mcp.json`	Workspace agent	Optional agent-local MCP sidecar.
`<additional-root>/.agh/agents/<name>/AGENT.md`	Additional root	Agent available when the workspace has that additional root registered.

Agent discovery order is workspace root, additional roots in registered order, then global home. First name wins. AGH does not use .agents/<name>/AGENT.md as a current runtime path; that appears only in draft RFC material.

Skill Files

Path	Scope	Description
`$AGH_HOME/skills/<name>/SKILL.md`	Global user or marketplace	User-wide or marketplace-installed skill.
`$AGH_HOME/skills/<name>/mcp.json`	Skill sidecar	Optional skill MCP sidecar.
`$AGH_HOME/skills/<name>/.agh-meta.json`	Marketplace sidecar	Managed provenance metadata for marketplace skills.
`$HOME/.agents/skills/<name>/SKILL.md`	User AgentSkills convention	Additional user-level skill source resolved from `HOME`.
`<workspace>/.agh/skills/<name>/SKILL.md`	Workspace	Workspace-local skill.
`<workspace>/.agh/skills/<name>/mcp.json`	Workspace skill sidecar	Optional skill MCP sidecar.
`<additional-root>/.agh/skills/<name>/SKILL.md`	Additional root	Skill available when the workspace has that additional root registered.

Skill filesystem precedence is bundled, marketplace, user, additional root, then workspace. Enabled extensions can also register runtime-owned skills into the live registry. Those overlays do not come from a filesystem path, so they are documented in Skills Overview rather than in this file-path table.

Workspace Files

my-project/
  .env
  .agh/
    config.toml
    mcp.json
    agents/
    skills/
    memory/

Path	Description
`<workspace>/.env`	Optional dotenv file loaded before home path resolution when config is loaded with a workspace root.
`<workspace>/.agh/config.toml`	Workspace TOML overlay. Loaded after global config.
`<workspace>/.agh/mcp.json`	Workspace MCP sidecar. Loaded after workspace TOML.
`<workspace>/.agh/agents/`	Workspace agent definitions.
`<workspace>/.agh/skills/`	Workspace skill definitions.
`<workspace>/.agh/memory/`	Workspace-scoped memory files.

AGH only loads the .agh/config.toml for the resolved primary workspace root. Additional roots are resource discovery roots for agents and skills; they do not contribute config overlays.

Extension Files

Path	Format	Description
`$AGH_HOME/extensions/<name>/`	directory	Managed installed extension root.
`$AGH_HOME/extensions/.agh-extension-stage-*`	temporary directory	Staging directory used while installing managed extensions.

Extension registry records are stored in the global database, not in a separate user-authored config file.

Path Overrides

Setting	Affects	Notes
`AGH_HOME`	All global home paths.	Resolved before global config is loaded. Workspace `.env` can set it for workspace config loads.
`[daemon].socket`	Daemon socket path.	`~` is expanded. Daemon boot resolves the final socket path to an absolute path.
`[memory].global_dir`	Global memory directory.	`~` is expanded. Empty overlay values are ignored and keep the previous directory.
`[http].host` and `[http].port`	HTTP/SSE bind address.	These are not file paths but affect browser/API endpoint locations.

Special Cases

Case	Behavior
Missing `config.toml`	Treated as absent. Built-in defaults remain active.
Missing `mcp.json`	Treated as absent.
Unknown TOML key	Config load fails.
Unknown JSON field in `mcp.json`	Sidecar parse fails.
Daemon boot config	Daemon startup uses the home config for boot settings. The general config loader applies MCP sidecars for session/runtime resolution.
`~` expansion	Implemented for `daemon.socket` and `memory.global_dir`; home paths are resolved from `AGH_HOME` or OS user home.

config.toml documents the schema for global and workspace config files.
mcp.json documents JSON sidecars.
Workspace Resolver explains how AGH finds the primary workspace root.

On this page