Troubleshooting

How to see what lucid is doing, and what its messages mean.

Agents don’t see the dream#

lucid stays silent unless all of these are true:

The project has opted in. A .lucid/ directory exists in the project, or in a parent folder up to the repo root. Run lucid init if not.
python3 is on the PATH Claude Code runs hooks with. The guard in front of every hook exits quietly when it can’t find python3.
The plugin is installed and enabled. Check with /plugin in Claude Code.
For a worktree outside the repo, LUCID_ROOT points at the folder that holds .lucid/.

See what agents see#

Print the digest a new agent gets, then the raw log:

In your terminal

lucid status        # the digest agents seelucid log --since 40

lucid log ends with last id: N, and marks entries ⚠stale or (superseded).

Log every hook input#

Start Claude Code with LUCID_DEBUG=1, and lucid appends every hook input, tagged with its event name, to .lucid/.debug.jsonl. The file is git-ignored.

In your terminal

LUCID_DEBUG=1 claudetail -n 5 .lucid/.debug.jsonl

Watch the hooks run#

Claude Code’s own debug mode shows each hook as it runs, with its output. Use it to confirm that lucid’s hooks fire and what they inject or block:

In your terminal

claude --debug

Messages#

Message	What it means
lucid: no .lucid/ found here; run `lucid init` first	The command ran outside an opted-in project. Run lucid init, run the command from inside the project, or set LUCID_ROOT.
lucid: `path` is claimed by `owner` (glob: task). Work on something else, or coordinate …	Another active agent has claimed that file, so the write was blocked. Pick other work, or coordinate with `lucid note blocker` or SendMessage.
lucid: glob overlaps `owner`’s claim … Pick other work or coordinate.	Your lucid claim overlaps an active claim by another agent.
lucid: log.jsonl is append-only; use `lucid note\|supersede`.	Something tried to edit the log directly. Add entries with lucid note, and retire wrong ones with lucid supersede.
`lucid: you edited files but logged nothing for the other agents …`	The stop gate. The agent is asked once to record decisions, dead ends and facts before finishing.
`lucid hook error: …`	A hook hit an unexpected error. It never blocks the agent. Turn on LUCID_DEBUG=1 to capture the input, and open an issue.

A claim is in the way#

Claims end when their owner releases them, when a claiming subagent stops or its session ends, or after LUCID_CLAIM_TTL seconds (default 1200) without activity from the owner. To see who holds what, run lucid status and look under “Active claims”.

Still stuck?#

Open an issue on GitHub with the output of lucid status and, if you can, the relevant lines of .lucid/.debug.jsonl.