Quick Start

This tutorial takes you from a bootstrapped Compozy install to one durable session you can inspect, attach to while it is active, and stop without deleting its history. It is intentionally repository-aware: you will create the session from the project you actually want Compozy to manage.

Before you begin: Complete Installation, make sure your selected provider is authenticated, and cd into a repository you want the session to use. For native ACP providers, use the provider's own login command before starting Compozy. For API-key providers, make sure the configured env: or vault: credential is available to the daemon.

1. Start the daemon

compozy daemon start

If you want to watch the daemon logs in the current terminal instead of detaching, use:

compozy daemon start --foreground

Verify that the daemon is available:

compozy status

2. Register the current repository as a workspace

Compozy can use the current directory directly, but registering the workspace gives you a stable name you can reuse in later commands.

compozy workspace add "$PWD" --name current

Confirm the registration:

compozy workspace info current

3. Create your first session

Create a session for the workspace you just registered:

compozy session new --workspace current --agent general --name first-run

If you prefer not to register a workspace first, use:

compozy session new --cwd "$PWD" --agent general

The key point is explicit workspace context. That keeps the first session tied to the repository you expect, instead of relying on an implicit working directory.

4. Find the session ID

List sessions and note the ID:

compozy session list

For scripts or copy-paste into later commands, JSON is often easier:

compozy session list -o json

The examples below use sess_1234 as a placeholder for your real session ID.

5. Send a repository-aware prompt

Use a prompt that makes the workspace matter:

compozy session prompt sess_1234 "Summarize the top-level structure of this repository and tell me what I should read first."

Compozy records the prompt, the agent response, tool calls, permission decisions, and usage events in the per-session event store.

6. Follow the live event stream

compozy session events sess_1234 --follow

This is the fastest way to see what Compozy means by a durable session: every important step appears as an event instead of disappearing into one terminal transcript.

When you are done following, press Ctrl+C.

7. Attach to the active session

compozy session list --resumable -o json
compozy session resume sess_1234

Despite its historical name, session resume acquires a short-lived attach lease for an eligible live session. It does not restart a stopped provider process. The resumable list is the authoritative way to find sessions that currently accept this operation.

8. Inspect the durable history

compozy session history sess_1234
compozy session recap sess_1234

History and recap read the persisted record. They do not depend on the attach lease and remain available after the live runtime stops.

9. Clean up the live session

If you want to continue with the Web UI, leave this session active and return to cleanup afterward. Otherwise, stop it now:

compozy session stop sess_1234
compozy session status sess_1234 -o json
compozy session history sess_1234

Stopping ends the live provider process and moves the public session lifecycle to terminal stopped. It preserves the session directory, catalog record, and history. A later compozy session resume sess_1234 is expected to fail because stopped sessions are not attachable; start a new session when you need new work.

What you just proved

You verified that Compozy can:

1. run a local daemon
2. attach work to one explicit repository
3. persist session events durably
4. attach another client while the session is live
5. stop live work without losing its inspectable history

Next steps

• Your First Custom Agent shows how to add a workspace-scoped AGENT.md.
• Web UI shows how to inspect the same daemon state in the browser.
• Session Lifecycle explains what Compozy is storing and why.