Workspace Resolver

A workspace is a registered project root with a stable identity. Compozy 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, the durable workspace_id, effective configuration, visible agents, and visible skill directories.

The durable identity comes from <workspace>/.compozy/workspace.toml:

workspace_id = "01HXJ9YR4Q..."
created_at   = "2026-05-04T14:30:00Z"
realpath_at_creation = "/Users/you/dev/checkout-api"

Memory v2 catalog rows, memory_events, memory_decisions, recall signals, dreaming runs, and forensic session ledgers all key on workspace_id. Path-keyed memory is gone. Moving the workspace directory (mv) does not orphan its memory because the ULID travels with the directory.

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

On a fresh install, daemon boot registers the operator home directory ($HOME) as the default workspace through the same resolver path. That gives first-run onboarding and compozy workspace list a usable workspace before any manual project registration. Use compozy workspace add for additional project roots that should have their own stable names, agents, skills, or config overlays.

What Gets Stored

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

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

Typical .compozy/ Layout

my-repo/
  .env
  .compozy/
    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

Compozy resolves a workspace reference from three forms:

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

CLI context chain

Every workspace-scoped CLI command uses one precedence chain:

1. A positional workspace ref, when the command accepts one.
2. --workspace <id|name|path>.
3. COMPOZY_WORKSPACE.
4. A validated COMPOZY_SESSION_ID plus COMPOZY_AGENT identity.
5. Current-working-directory discovery.

--workspace is an override, not a prerequisite. Structured JSON, JSONL, and TOON output includes resolution_source so an agent can see which tier won. Partial, stale, global, or workspace-less session credentials fall through to cwd discovery. If no tier resolves, the command returns one deterministic error that names the attempted tiers and tells you to register the directory or pass an override.

Cwd and path discovery choose the nearest registered root that contains the path. A nested registered workspace therefore wins over its parent. Canonical path comparison prevents sibling prefix matches and preserves symlink resolution. Additional directories extend agent and skill discovery only; they do not establish workspace ownership for cwd discovery.

Register A Workspace

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

compozy 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:

compozy 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

Compozy can also register a workspace on demand:

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

When --cwd points to a path outside every registered workspace, ResolveOrRegister canonicalizes the path, creates a registration, and resolves the new workspace before starting the session. A path inside a registered workspace resolves the nearest enclosing root and never creates a nested registration.

If you run compozy session new without --workspace or --cwd, the CLI applies the shared context chain. Cwd is the final tier; an unregistered project directory is auto-registered, while any subdirectory of a registered project binds to its nearest enclosing workspace.

Use --workspace when you want to override the inferred workspace with an existing registration by ID, name, or path:

compozy 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:

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

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

Running this command:

compozy 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, Compozy updates the stored root_dir.
4. Config is loaded as built-in defaults, then ~/.compozy/config.toml, then ~/.compozy/mcp.json, then <workspace>/.compozy/config.toml, then <workspace>/.compozy/mcp.json.
5. Agents are discovered from <workspace>/.compozy/agents/, then additional roots, then global $COMPOZY_HOME/agents/.
6. Base skills are resolved from bundled plus global $COMPOZY_HOME/skills/, then additional roots, then <workspace>/.compozy/skills/.
7. If the winning agent has skills/, that agent-local directory overlays the base set last.
8. Same-name agents and skills use first-wins or higher-precedence overlay behavior, so the workspace reviewer and repo-map override the global ones.
9. 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.
• Memory Scopes explains how workspace_id keys workspace and agent-workspace memory.