Coven Documentation

Coven records project-scoped harness work as sessions. Use coven sessions to browse recent work and choose session actions without copying ids.

coven sessions

The daemon owns session state; see Daemon lifecycle for recovery and restart behavior.

Rituals Cheat Sheet

Coven names its session-management verbs rituals. The whimsy is deliberate; the semantics are conventional and conservative. This table is the full mapping in one place:

Ritual	Plain meaning	Command	Allowed for	Reversible	Events
Archive	Hide from the active list	`coven archive <session-id>`	Any non-running session	Yes — summon it back	Preserved
Summon	Restore an archived record	`coven summon <session-id>`	Archived sessions	Yes — archive again	Preserved
Sacrifice	Delete permanently	`coven sacrifice <session-id> --yes`	Any non-running session	No	Deleted

Three rules cover almost every question:

Running sessions are untouchable. Kill the process or wait for exit before any ritual applies.
Only sacrifice destroys data. Archive and summon flip visibility; the session record and event log survive both.
Summon does not re-run anything. It restores the record to its prior terminal status (completed, failed, killed, or orphaned) and opens the existing log.

Rituals are CLI-owned in coven.daemon.v1: the public socket API has no archive, summon, or sacrifice endpoints yet, and GET /api/v1/sessions simply excludes archived records. Clients that need record management should use the CLI verbs above.

The rituals in detail:

Listing modes

Command	Output
`coven sessions`	Interactive browser in a terminal; table output when piped.
`coven sessions --all`	Includes archived sessions.
`coven sessions --manage`	Forces the interactive session browser.
`coven sessions --plain`	Forces a plain table for scripts and copying.
`coven sessions --json`	Prints a JSON `sessions` array for local clients and scripts.

Use --json for integrations and --plain for shell scripts or support snippets.

Search and inspect

Search recorded event payloads with FTS5 query syntax:

coven sessions search "auth OR jwt"

Inspect one session without attaching:

coven sessions show <session-id>
coven sessions events <session-id> --limit 100
coven sessions log <session-id>

show prints the session record and ritual state. events prints redacted event payloads and accepts --after-seq plus --limit. log renders the recorded log lines. Each command also supports --json.

Session references may be full ids or unique prefixes. Ambiguous prefixes fail instead of selecting an arbitrary session.

Attach

Replay and follow a session:

coven attach <session-id>

For live daemon sessions, attach can also forward input to the running harness.

Summon

Restore an archived session, then attach:

coven summon <session-id>

Use coven sessions --all when you need to find archived session ids.

Sacrifice

Permanently delete a non-running session and its event log:

coven sacrifice <session-id> --yes

Sacrifice is destructive. It requires --yes and refuses running sessions.

Run for creating sessions.
Daemon lifecycle for live-session daemon behavior.
Recovery and upgrades for stale local IPC and orphaned sessions.

Sessions