Prepare a project workspace

This flow is for a maintainer who already has a repository and wants CompozyOS 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, 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: CompozyOS registered the current directory and will resolve workspace-scoped agents, skills, and config overlays 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 CompozyOS resolves the file you just created:

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

Run a smoke-test session

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

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 and the agent definition 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, and additional roots.
Agent visibility	`compozy agent info reviewer --workspace checkout-api -o json`	The workspace-local `AGENT.md` parses and wins discovery.
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
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 or MCP settings that should not apply globally.
Use Review a Change once the workspace smoke test passes.

SetupCopy Anchor Link

FlowCopy Anchor Link

Evidence to keepCopy Anchor Link

Failure pathCopy Anchor Link

NextCopy Anchor Link

On this page

Setup

Flow

Evidence to keep

Failure path

Next