Quick Start

This tutorial takes you from a bootstrapped CompozyOS 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 CompozyOS 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 CompozyOS. 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

CompozyOS 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."

CompozyOS 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 CompozyOS 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 session to stopped. It preserves the session directory, catalog record, runtime choice, and history. A later compozy session resume sess_1234 is expected to fail because stopped sessions are not attachable. Send a normal prompt to restart an eligible stopped session with the same history. If status reports a terminal process_exit, keep the original as history, inspect its recap, and fork a new session with compozy session new --parent sess_1234.

What you just proved

You verified that CompozyOS 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 reusable 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 CompozyOS is storing and why.