CLI reference

The lucid command is how agents, and you, write to the dream. It is on the agents’ PATH and usable from your own terminal.

Synopsis#

lucid [--as ME] initlucid [--as ME] note {decision,fact,failed,blocker} TEXT [-e EVIDENCE [EVIDENCE ...]]lucid [--as ME] claim GLOB [GLOB ...] [--for TASK]lucid [--as ME] release [GLOB ...]lucid [--as ME] supersede ID [ID ...] [--why WHY]lucid [--as ME] log [--since SINCE]lucid [--as ME] status

Every command accepts -h / --help. Commands other than init need a .lucid/ directory and exit with lucid: no .lucid/ found here; run `lucid init` first otherwise.

Who wrote what: --as#

Option	Meaning
`--as ME`	The agent id recorded on the entry. Hooks fill it in for agents.

Agents never manage ids. Before an agent’s Bash command runs, a lucid hook adds the agent’s real id to every lucid command in it, replacing a wrong --as if there is one. Every entry records who wrote it, and leads can’t invent worker ids.

Humans appear as human. When you run lucid from your own terminal without --as, your notes reach agents as coming from human.

init#

lucid init

Creates .lucid/ in this project with a plan template, an empty log and git settings. Safe to run again: an existing plan and log are kept. See what lucid init creates.

note#

lucid note {decision,fact,failed,blocker} TEXT [-e EVIDENCE [EVIDENCE ...]]

Logs a decision, fact, dead end (failed) or blocker, and prints its id.

Argument	Meaning
`decision`	A choice others must stay consistent with. Write it as “what, because why”.
`fact`	A non-obvious truth about the code. Always give evidence.
`failed`	A dead end: what was tried and why it broke, so nobody retries it.
`blocker`	What you need, and from whom. The lead sees it on its next turn.
`TEXT`	The entry. Quote it.
`-e, --evidence`	One or more `path[:line[-line]]` references, or free text.

When evidence points at a file that exists, lucid records a hash of that file. If the file changes later, the entry is shown as ⚠stale until someone re-checks it.

Examples

lucid note decision "use JWT, not sessions, because the API is stateless" -e src/auth.ts:42lucid note failed   "bcrypt native build breaks on Node 24; use bcryptjs"lucid note blocker  "need the DB schema from the migrations worker"

claim#

lucid claim GLOB [GLOB ...] [--for TASK]

Claims files before editing them. While your claim is active, other agents’ writes to matching files are blocked, whether through Edit/Write or through Bash.

Argument	Meaning
`GLOB`	One or more globs or paths. Quote globs so your shell doesn’t expand them.
`--for TASK`	What the claim is for. Shown to other agents next to the claim.

A claim that overlaps another active agent’s claim is refused with a message naming the owner, so you can pick other work or coordinate. Claims lapse after LUCID_CLAIM_TTL seconds without activity from their owner, and are released automatically when a subagent stops or a session ends.

Example

lucid claim 'src/db/**' --for "migrations"     # release when done

release#

lucid release [GLOB ...]

Drops your claims: all of them with no arguments, or only the given globs.

Examples

lucid release                 # all of your claimslucid release 'src/db/**'     # just this one

supersede#

lucid supersede ID [ID ...] [--why WHY]

Retires wrong or outdated entries. The log stays append-only: superseding adds an entry that marks the old ones as retired. Retired entries drop out of what agents are shown, and lucid log marks them (superseded).

Example

lucid supersede 12 --why "switched to sessions"

log#

lucid log [--since SINCE]

Prints log entries in order, with ⚠stale and (superseded) markers, and ends with last id: N. With --since SINCE, prints only entries after that id.

Example

lucid log --since 40

status#

lucid status

Prints the digest agents get when they start: the plan, the consolidated digest if /lucid:dream has written one, active claims, and the newest log entries that fit the budget. Use it to see exactly what a new agent would see.