Workspace Resolver

A workspace is a registered project root. AGH stores the registration in the global database, but the filesystem remains the source of truth. Each session starts by resolving a workspace snapshot: the canonical root directory, optional additional roots, effective configuration, visible agents, and visible skill directories.

That is the portability model: copy the project directory with its .agh/ directory, register the new path, and the same project agents, skills, memory files, and config overlay travel with it.

What Gets Stored

AGH stores workspace registrations in the global catalog database at ~/.agh/agh.db. The workspaces table stores:

The ID is random and stable. The default name comes from the root directory basename, and AGH adds numeric suffixes such as repo-2 when another workspace already has the same name.

Typical .agh/ Layout

my-repo/
  .env
  .agh/
    config.toml
    mcp.json
    agents/
      reviewer/
        AGENT.md
        mcp.json
    skills/
      repo-map/
        SKILL.md
        mcp.json
        references/
          architecture.md
    memory/
      MEMORY.md
      release-rules.md

The resolver directly snapshots config, MCP sidecars, agent definitions, and skill definitions. Workspace memory uses the resolved root, but memory files are managed by the memory runtime instead of by the workspace resolver.

Resolution Inputs

AGH resolves workspaces from three kinds of input:

Relative paths are not accepted by API workspace create/resolve requests or by agh session new --cwd. The resolver itself also requires the path to exist and to be a directory.

Register A Workspace

Use agh workspace add when you want the directory to appear in agh workspace list and to have a stable name:

agh workspace add /Users/you/src/checkout-api --name checkout-api

Add a workspace-local default agent when this project should start a different agent from your global default:

agh workspace add /Users/you/src/checkout-api \
  --name checkout-api \
  --default-agent reviewer

The command writes one registration row and immediately resolves it. If the root is missing, is not a directory, or contains invalid workspace config or agent definitions, the registration is rolled back.

Auto-Registration

AGH can also register a workspace on demand:

agh session new --cwd /Users/you/src/checkout-api --agent reviewer

When --cwd points to a path that is not registered yet, ResolveOrRegister canonicalizes the path, creates a registration, and resolves the new workspace before starting the session.

The CLI default is also path-based. If you run agh session new without --workspace or --cwd, the CLI sends its current working directory as workspace_path, so that directory is resolved or registered automatically.

Use --workspace when you want to target an existing registration by name or ID:

agh session new --workspace checkout-api --agent reviewer

--workspace and --cwd are mutually exclusive. The HTTP and UDS create-session contract mirrors that rule: send either workspace or workspace_path, not both.

Resolution Cascade

For this setup:

~/.agh/
  config.toml
  agents/
    general/AGENT.md
    reviewer/AGENT.md
  skills/
    repo-map/SKILL.md

/Users/you/src/checkout-api/
  .agh/
    config.toml
    agents/
      reviewer/AGENT.md
    skills/
      repo-map/SKILL.md
      payment-rules/SKILL.md

Running this command:

agh session new --workspace checkout-api --agent reviewer

produces this cascade:

1. checkout-api is looked up as a registered workspace name.
2. The stored root_dir is checked with os.Stat.
3. The root is canonicalized again with EvalSymlinks. If the canonical target changed, AGH updates the stored root_dir.
4. Config is loaded as built-in defaults, then ~/.agh/config.toml, then ~/.agh/mcp.json, then <workspace>/.agh/config.toml, then <workspace>/.agh/mcp.json.
5. Agents are discovered from <workspace>/.agh/agents/ first, then global ~/.agh/agents/.
6. Skills are discovered from <workspace>/.agh/skills/ first, then global ~/.agh/skills/.
7. Same-name agents and skills use first-wins precedence, so the workspace reviewer and repo-map override the global ones.
8. The session starts with cwd set to the workspace root and the resolved agent prompt.

Cache And Refresh Behavior

Resolved workspace snapshots are cached in memory by workspace ID. A cached snapshot is reused only when all watched file snapshots still match and the stored workspace fields still match.

The resolver watches:

Cache entries expire after 10 minutes of inactivity. The resolver also exposes an internal Invalidate(workspaceID) method used by update and unregister flows. There is no public --force-refresh CLI flag today.

Errors To Expect

Related Pages

• Config Overlays explains the workspace TOML and MCP merge rules.
• Multi-Root Workspaces shows how --add-dir changes discovery.
• Agent Definitions documents the current AGENT.md parser.
• Skills Overview explains skill precedence after workspace resolution.
• Global vs Workspace Memory explains workspace memory files.