Multi-Root Workspaces

A multi-root workspace has one primary root and zero or more additional roots. The primary root owns the workspace config. All roots can contribute agents and skills.

Use multi-root when one session should operate from a main repository while also seeing reusable project-local agents or skills from nearby directories. Compozy starts the agent in the primary root and sends the additional roots to ACP as additional_dirs.

Register Additional Roots

compozy workspace add /Users/you/src/acme/checkout \
  --name checkout \
  --add-dir /Users/you/src/acme/shared-agents \
  --add-dir /Users/you/src/acme/platform

Add or remove roots later:

compozy workspace edit checkout \
  --add-dir /Users/you/src/acme/ops-notes

compozy workspace edit checkout \
  --remove-dir /Users/you/src/acme/platform

The CLI prevents adding and removing the same directory in one edit command.

What Multi-Root Changes

The session start options use:

cwd = <workspace root>
additional_dirs = [<additional root 1>, <additional root 2>, ...]

That means provider support for additional_dirs depends on the ACP-compatible agent. Compozy still uses the additional roots for its own agent and skill discovery before the subprocess starts.

Precedence

Discovery order is first-wins:

1. Primary workspace root
2. Additional roots, in the order stored on the workspace
3. Global Compozy home

For agents, the first AGENT.md whose parsed name matches wins. Compozy does not merge two agent definitions with the same name.

For skills, the first skill directory name wins. Compozy does not merge two SKILL.md files with the same directory name.

Monorepo Pattern

Use the repository root as the workspace root when one .compozy/config.toml should govern the whole monorepo:

acme-platform/
  .compozy/
    config.toml
    agents/
      monorepo-maintainer/AGENT.md
    skills/
      architecture-map/SKILL.md
  services/
    checkout/
    billing/
  packages/
    ui/

Register once:

compozy workspace add /Users/you/src/acme-platform --name acme-platform

Start sessions from the named workspace:

compozy session new --workspace acme-platform --agent monorepo-maintainer

This keeps one config overlay and one workspace memory scope for the whole monorepo.

Shared Resource Pattern

Use additional roots when each project needs its own config and memory, but the team wants shared agents or skills:

acme/
  checkout/
    .compozy/
      config.toml
      memory/
        MEMORY.md
  billing/
    .compozy/
      config.toml
      memory/
        MEMORY.md
  shared-agent-kit/
    .compozy/
      agents/
        incident-reviewer/AGENT.md
      skills/
        runbook-reader/SKILL.md

Register each project with the same shared root:

compozy workspace add /Users/you/src/acme/checkout \
  --name checkout \
  --add-dir /Users/you/src/acme/shared-agent-kit

compozy workspace add /Users/you/src/acme/billing \
  --name billing \
  --add-dir /Users/you/src/acme/shared-agent-kit

Now checkout and billing can both use incident-reviewer, but each keeps its own primary config and workspace memory.

Nested Workspace Pattern

Nested directories can be registered as separate workspaces because Compozy resolves registered rows, not a Git-style nearest-parent marker.

acme-platform/
  .compozy/
    config.toml
    agents/
      platform/AGENT.md
  services/
    checkout/
      .compozy/
        config.toml
        agents/
          checkout/AGENT.md

You can register both:

compozy workspace add /Users/you/src/acme-platform --name platform

compozy workspace add /Users/you/src/acme-platform/services/checkout --name checkout

Run from either registered tree and let cwd discovery select the nearest root:

cd /Users/you/src/acme-platform
compozy session new --agent platform

cd /Users/you/src/acme-platform/services/checkout
compozy session new --agent checkout

From any subdirectory under services/checkout, cwd discovery selects the registered checkout root because it is the nearest enclosing workspace. From elsewhere under acme-platform, it selects platform. Use --workspace <id|name|path> only when you need to override that inferred context. Additional roots never participate in this ownership decision.

Path Normalization And Duplicates

Compozy normalizes every root with filepath.Abs, os.Stat, and filepath.EvalSymlinks.

Config Boundary

Additional roots do not load config:

checkout/
  .compozy/config.toml       # loaded

shared-agent-kit/
  .compozy/config.toml       # ignored for checkout
  .compozy/agents/...        # discovered
  .compozy/skills/...        # discovered

Use global ~/.compozy/config.toml for settings shared across workspaces. Use the primary root <workspace>/.compozy/config.toml for project-specific settings. Avoid putting shared runtime policy in additional roots, because Compozy will not read it for the parent workspace.

Inspect A Multi-Root Workspace

compozy workspace info resolves the workspace and shows the sessions, visible agents, and visible skills:

compozy workspace info checkout

The JSON shape includes the stored registration plus resolved resources:

{
  "workspace": {
    "id": "ws_8f33a913d23c4fd1",
    "name": "checkout",
    "root_dir": "/Users/you/src/acme/checkout",
    "add_dirs": ["/Users/you/src/acme/shared-agent-kit"]
  },
  "agents": [{ "name": "incident-reviewer", "provider": "claude" }],
  "skills": [
    {
      "name": "runbook-reader",
      "source": "additional",
      "dir": "/Users/you/src/acme/shared-agent-kit/.compozy/skills/runbook-reader"
    }
  ]
}

Use this command after editing --add-dir values. It exercises the same resolver path session creation uses.

Related Pages

• Workspace Resolver explains the registration and lookup model.
• Config Overlays explains why config comes only from the primary root.
• Skills Overview explains how workspace skill paths overlay the global registry.
• Agent Definitions documents agent discovery and parser behavior.