lucid docs
lucid gives every Claude agent working on a project one shared memory, the dream: a live plan, an evidence-backed log and file claims. The lead agent, its subagents and Agent-Teams teammates all see it, and a change to the plan reaches every running worker before its next action.
What’s in the dream#
The dream is plain files in .lucid/ at the root of your project:
| File | What it holds |
|---|---|
plan.md | The live plan. When anyone edits it, every running agent gets the diff before its next tool call. |
log.jsonl | An append-only memory: decisions (with why), facts (with path:line evidence), dead ends, blockers and file claims. |
digest.md | A consolidated summary, written when you run /lucid:dream. |
The memory is wired in through hooks, so agents can’t forget to check it. Agents only add to the log and never rewrite it. A fact whose cited code has changed is flagged ⚠stale, so shared memory doesn’t spread outdated claims.
Scroll sideways to see the whole diagram.
The problem it solves#
You build a feature with several Claude agents working at once, then change your mind partway through. Workers that are already running keep following the plan they were spawned with. Subagent summaries leave out the why and the dead ends. Every worker re-reads the same code. Decisions disappear when the conversation is compacted, and two agents can edit the same file. lucid addresses each of these with one shared, hook-fed memory.
Off until a project opts in#
lucid stays inactive until you run lucid init in a project. In every other project a tiny shell guard checks for .lucid/ and exits without starting Python. It works from repo subfolders and git worktrees, which share the main checkout’s dream.
Where to go next#
Get started
- Installation: Install lucid from the marketplace or a local checkout, then turn it on per project.
- Quick start: Five steps from lucid init to a consolidated dream.
Use lucid
- Commands: The /lucid:swarm, /lucid:replan and /lucid:dream slash commands, and the protocol skill.
- CLI reference: Every lucid subcommand and flag, with examples.
Under the hood
- How it works: Hooks, digest and delta, claims, stale facts, the stop gate and Bash write detection.
- Agent Teams: Using lucid with Claude Code’s experimental Agent Teams.
- Configuration: Environment variables and what to commit.
Results and help
- Benchmark: Methodology, results, every chart, how to reproduce, and caveats.
- Limits & FAQ: What lucid does not do, and answers to common questions.
- Troubleshooting: Debug logging, lucid status, claude --debug and common messages.