Prepare a Project Workspace

This flow is for a maintainer who already has a repository and wants Compozy to run repeatable agent work against it. The goal is not just "start an agent"; it is to make the project discoverable, give the agent a local operating brief, and leave evidence that the runtime is using the intended workspace.

Setup

Start from the repository root and confirm the daemon is reachable:

compozy status

If you do not already have a provider configured, use the provider key that matches your local runtime setup when you create the agent definition below. The example uses claude because it is a built-in provider key, not because the workspace model depends on that provider.

Flow

Rendering diagram…

A project workspace becomes useful when registration, local agent instructions, memory, and session evidence all point at the same root.

Give the workspace a stable name. Use the same name in docs, scripts, and task descriptions so agents do not have to infer which checkout you mean.

compozy workspace add "$PWD" --name checkout-api --default-agent reviewer
compozy workspace info checkout-api -o json

What happened: Compozy registered the current directory and will resolve workspace-scoped agents, skills, memory, config overlays, and sandbox settings from this root.

Add a workspace-local agent

Put the agent definition in the workspace so it travels with the project and wins over global definitions of the same name.

mkdir -p .compozy/agents/reviewer

Create .compozy/agents/reviewer/AGENT.md with this content:

---
name: reviewer
provider: claude
toolsets:
  - "compozy__catalog"
  - "compozy__coordination"
permissions: approve-reads
---

You are the reviewer for this repository.

Start by identifying the changed files, relevant tests, and runtime surfaces involved.
Return blocking findings first with file paths and concrete reproduction evidence.

Then confirm Compozy resolves the file you just created:

compozy agent info reviewer --workspace checkout-api -o json

Write the first workspace memory

Add durable project context that should be visible beyond this session. Keep it short and factual; do not paste a full architecture document into memory.

compozy memory write project-map.md \
  --scope workspace \
  --type project \
  --description "Where agents should start in this repository" \
  --content "Start with README.md, then inspect packages/site for docs and internal/ for runtime code."

compozy memory list --scope workspace -o json

What happened: Compozy wrote a workspace-scoped Markdown memory and refreshed the index so future sessions can discover it.

Run a smoke-test session

Start the default agent for this workspace and ask it to prove that it can see the intended root, local instructions, and memory.

compozy session new --workspace checkout-api --agent reviewer --name workspace-smoke -o json
compozy session prompt sess_1234 "Inspect this workspace setup. Confirm the repository root, agent definition, and workspace memory you can see."
compozy session events sess_1234 --follow

What happened: the session produced durable events under the workspace context. Use the emitted session id in later status and history commands.

Evidence to keep

Evidence	Command	What it proves
Workspace resolution	`compozy workspace info checkout-api -o json`	The registered root, default agent, additional roots, and sandbox.
Agent visibility	`compozy agent info reviewer --workspace checkout-api -o json`	The workspace-local `AGENT.md` parses and wins discovery.
Memory indexing	`compozy memory list --scope workspace -o json`	The project note is visible to workspace-scoped sessions.
Session runtime state	`compozy session status sess_1234 -o json`	The live session is attached to the intended workspace and agent.
Session transcript	`compozy session history sess_1234`	The smoke-test answer is durable after the terminal closes.

Failure path

Symptom	First check	Next page
Workspace resolves a different root	`compozy workspace info checkout-api -o json`	Workspace Resolver
Agent is not found	`compozy agent info reviewer --workspace checkout-api -o json`	AGENT.md
Agent uses the wrong provider	`compozy agent info reviewer --workspace checkout-api -o json`	Agent Providers
Memory does not appear in the index	`compozy memory health -o json`	Memory System
Session starts but never produces output	`compozy session status sess_1234 -o json`	Debug a Failed Session

Use Your First Custom Agent for a tutorial version of agent authoring.
Use Workspace Config Overlays when this project needs provider, MCP, memory, or sandbox settings that should not apply globally.
Use Review a Change once the workspace smoke test passes.

Setup

Flow

Evidence to keep

Failure path

Next

On this page