Installation

Install the plugin once, then turn it on in each project where you want agents to share a dream.

Requirements#

Claude Code, with plugin support.
python3 (3.9 or newer). lucid uses only the standard library, so there is nothing else to install.
macOS or Linux. lucid is POSIX only, because the log uses flock for locking.

Install from the marketplace#

Run these two commands inside Claude Code:

In Claude Code

/plugin marketplace add Redskull-127/lucid

In Claude Code

/plugin install lucid@lucid

Try a local checkout#

To develop lucid or try it without installing, load a clone for one session:

In your terminal

git clone https://github.com/Redskull-127/lucidclaude --plugin-dir ./lucid       # load for one session; /reload-plugins after editspython3 lucid/test_lucid.py       # self-checkclaude plugin validate ./lucid --strict

Turn it on in a project#

lucid does nothing until a project opts in. In Claude Code, ask Claude to run lucid init in the project, then write your plan in .lucid/plan.md:

lucid init        # Claude runs this: the plugin puts lucid on its PATH

You can also skip this step: /lucid:swarm and /lucid:replan run lucid init themselves when .lucid/ doesn’t exist yet. Running lucid init again is safe: it keeps an existing plan and log.

What lucid init creates#

Path in .lucid/	What it is	In git
`plan.md`	The live plan, started from a short template (goal, tasks with one owner per file set, constraints).	Commit
`log.jsonl`	The append-only log. Starts empty.	Commit
`digest.md`	Not created by init. /lucid:dream writes it later.	Commit
`.gitattributes`	Sets `log.jsonl merge=union`, so two people appending to the log never conflict.	Commit
`.gitignore`	Ignores the per-agent files below.	Commit
`.state/`	Per-agent state, such as how far each agent has read the log.	Ignored
`.plan.prev`	The last plan lucid saw, used to compute plan diffs.	Ignored
`.debug.jsonl`	Only with `LUCID_DEBUG=1`: every hook input.	Ignored

The plan template looks like this:

.lucid/plan.md

# Plan ## Goal ## Tasks (one owner per file set)- [ ] ## Constraints / non-goals

What to commit#

Commit plan.md, log.jsonl and digest.md so teammates and future sessions share the dream. Per-agent state is git-ignored automatically.

Subfolders and worktrees#

lucid finds .lucid/ by walking up from the project directory, so it works from repo subfolders. Git worktrees share the main checkout’s dream. For a worktree outside the repo, set LUCID_ROOT to where .lucid/ lives.

Next: walk through a first build.