Workspace Config Overlays

Workspace config lets one project change runtime behavior without changing every AGH session on the machine. The loader starts from built-in defaults, applies global config, then applies the resolved workspace root overlay.

This keeps project behavior portable. Copy a repository with .agh/config.toml, .agh/agents/, .agh/skills/, and .agh/memory/, register the copied path, and the project-level runtime context comes with it.

Load Order

The effective config for a resolved workspace is built in this order:

Workspace additional roots do not contribute config. They can contribute agents and skills, but only the primary root contributes config.toml and top-level mcp.json.

Create A Workspace Overlay

Create the config file under the project root:

mkdir -p /Users/you/src/checkout-api/.agh

# /Users/you/src/checkout-api/.agh/config.toml
[defaults]
agent = "reviewer"
provider = "claude"

[permissions]
mode = "approve-reads"

[limits]
max_sessions = 4

[skills]
disabled_skills = ["public-cloud-deploy"]

[[mcp_servers]]
name = "repo-fs"
command = "npx"
args = ["-y", "@modelcontextprotocol/server-filesystem", "/Users/you/src/checkout-api"]

Then register the workspace:

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

Sessions that target checkout-api now inherit the overlay:

agh session new --workspace checkout-api

The command uses reviewer as the default agent unless you pass --agent.

Merge Rules

TOML overlays are field-aware. A field changes only when the overlay provides that field.

This example keeps the global marketplace URL while changing only skill enablement:

# ~/.agh/config.toml
[skills.marketplace]
registry = "clawhub"
base_url = "https://registry.example.test/api/v1"

# <workspace>/.agh/config.toml
[skills]
enabled = false

The final config has skills.enabled = false, but keeps the global marketplace registry and base_url.

MCP Sidecars

Top-level mcp.json files are optional. They may use either mcpServers or mcp_servers.

{
  "mcpServers": {
    "repo-db": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {
        "DATABASE_URL": "postgres://localhost/checkout"
      }
    }
  }
}

When both key styles appear in the same mcp.json, mcp_servers replaces same-name entries from mcpServers. When a TOML MCP server and an mcp.json server have the same name, the JSON sidecar replaces the whole server object at that scope.

Across the session start path, MCP servers are then resolved in this order:

1. top-level config MCP servers
2. provider MCP servers
3. agent MCP servers
4. active skill MCP servers

Workspace Agents And Skills

Config overlays do not define agents or skills directly. They change the runtime defaults around the agents and skills discovered by the resolver.

Workspace registration has one extra override: default_agent. When it is set on the workspace row, the resolver applies it after loading config by setting defaults.agent for the resolved snapshot.

agh workspace edit checkout-api --default-agent reviewer

Set it to an empty value to clear it:

agh workspace edit checkout-api --default-agent ""

Concrete Overlay Walkthrough

Global config:

# ~/.agh/config.toml
[defaults]
agent = "general"
provider = "codex"

[permissions]
mode = "approve-all"

[limits]
max_sessions = 10

[skills]
disabled_skills = ["legacy-notes"]

Workspace config:

# <workspace>/.agh/config.toml
[defaults]
agent = "reviewer"

[permissions]
mode = "approve-reads"

[skills]
disabled_skills = ["deploy-production", "legacy-notes"]

Effective result for the workspace:

.env And AGH_HOME

If a workspace root contains .env, AGH loads it before resolving the AGH home layout for that config load. That means a workspace can set AGH_HOME for sessions that resolve that workspace:

AGH_HOME=/Users/you/.agh-checkout

Use this carefully. It changes the global config, agents, skills, memory, sessions, logs, socket, and database locations for that resolved workspace config load. Most projects should prefer <workspace>/.agh/config.toml for project-specific behavior and keep AGH_HOME stable.

Failure Behavior

Related Pages

• Workspace Resolver explains when config loading happens.
• Multi-Root Workspaces explains why additional roots do not add config overlays.
• Agent Definitions documents agent-local MCP sidecars.
• Skills Overview documents skill-local MCP sidecars and disabled skill behavior.