Step 1 — Open the project
Pick a project root and confirm the Coven daemon is running there before any agent work begins.
2 min read
A Coven session is always scoped to a project root — an absolute path on this machine that the daemon canonicalizes and uses as the trust boundary for harness cwd checks. Step 1 is making that root explicit, both to the daemon and to CastCodes.
What "project root" means
Coven's daemon will refuse any session whose harness cwd does not canonicalize inside the requested projectRoot. The project root you open in CastCodes is the same string you would pass to coven run --project <root> or to a POST /api/v1/sessions request.
Anything inside example-project/ is a valid cwd. Anything outside is rejected before the harness starts.
The flow
Start (or confirm) the daemon
The daemon owns session state, the SQLite ledger, and the socket. CastCodes will refuse to launch agent panes if the daemon is unreachable, and so will the CLI.
coven daemon start
coven daemon status # expect pid + socket pathIf coven daemon status reports nothing, see Daemon lifecycle.
Open the project in CastCodes
TODO: CastCodes UI specifics — exact label for the project picker (currently "Open Project"?), keyboard shortcut, whether dragging a folder onto the dock works, and where the project root is stored in user preferences.
Once opened, the project root appears in the CastCodes sidebar and is the implicit --project for every agent pane launched from this window.
Confirm CastCodes sees the daemon
The agent panel renders a status pill (green) when CastCodes can reach coven.daemon.v1. If the pill is amber, the daemon isn't running on this machine; if it's red, CastCodes hit an error talking to the socket.
TODO: screenshot of the agent-panel status pill in each state.
CLI equivalent
There is no separate "open project" command in Coven. The project root is just an argument:
# `coven run` accepts an absolute path; if omitted, the cwd is used.
coven run codex --project ~/code/example-project "fix the failing tests"Handshake (under the hood)
Next
Continue to Step 2 — Launch a session. The project is open; nothing is running yet.
Last updated on