lucid
lucid icon: an eye with a crescent moon for a pupil, under three stars

One shared dream for every Claude

lucid is a Claude Code plugin that gives the lead agent, its subagents and Agent-Teams teammates one live plan, one memory and one set of file claims. Change the plan partway through, and every running worker sees the change before its next action.

Install in Claude Code

/plugin marketplace add Redskull-127/lucid
/plugin install lucid@lucid

Then turn it on per project: ask Claude to run lucid init, or just start with /lucid:swarm.

Read the docsView on GitHub
Injected before the worker’s next tool call
[lucid] 1 update(s) from other agents since you last looked:#3 PLAN CHANGED by user:@@ -3 +3,2 @@ - add a one-line docstring to every function in calc.py+- ALSO add multiply() to calc.py
From a real claude -p run on Haiku. The worker’s brief never mentioned multiply(). A human added one line to the plan, and the worker added it.

Change your mind mid-build, and parallel agents drift apart

You build a feature with several Claude agents working at once, then change your mind partway through. Here is what goes wrong.

Plan drift
Workers that are already running still follow the plan they were spawned with. Nothing tells them it changed.
Lossy handoffs
A subagent’s summary leaves out the why, and leaves out the “we tried X, it broke”.
Repeated work
Every worker re-reads and re-searches the same code.
Compaction amnesia
Decisions disappear when the conversation is compacted and in new sessions.
Overwritten work
Two agents edit the same file and one loses its changes.

One dream, kept in plain files, wired in through hooks

lucid gives every agent in the project one shared memory, the dream, kept in .lucid/. Hooks read it into every agent, so nobody can forget to check it. Agents only add to the log and never rewrite it.

  • 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.

You edit .lucid/plan.md; hooks inject the full dream into every agent on start and only what changed before each tool call; agents write back with lucid note and lucid claim.You edit .lucid/plan.md; hooks inject the full dream into every agent on start and only what changed before each tool call; agents write back with lucid note and lucid claim.

Scroll sideways to see the whole diagram.

  1. SessionStart, SubagentStart

    Every agent starts with the whole dream

    The plan, the live memory and active claims are injected within a fixed budget, also after /compact. Subagents and teammates get the full shared context instead of a one-paragraph brief.

  2. UserPromptSubmit, PreToolUse

    Before each action, only what changed

    An agent sees what other agents wrote since it last looked. When nothing changed, nothing is injected and it costs no tokens.

  3. PreToolUse on writes

    Claimed files stay locked

    A write to a file another active agent has claimed is blocked, whether it goes through Edit or Write or through Bash.

  4. SubagentStop, TaskCompleted

    Nothing finishes silently

    An agent that edited files but logged nothing is asked once for notes. A stopping subagent’s claims are released.

A fact whose cited code has changed is flagged ⚠stale, so shared memory doesn’t spread outdated claims. Read how it works

When the plan changes mid-build

26/26passed with lucid

7/26passed without

Across Claude Haiku 5.5 and Claude Opus 5.5, through headless claude -p. A hidden acceptance test the agents never see scores the final code.

  • Without lucid, Haiku missed every late change (0/8). Opus did better by re-checking the plan at the end (2/5), but still missed most.
  • Cheaper per working result. On Opus, a passing run cost $1.01 vs $4.57 for early changes and $1.06 vs $2.35 for late ones.
  • Small overhead when there’s nothing to coordinate. +$0.002 and +5 s per run on Haiku, +$0.026 (+7%) and +6 s on Opus.

74 runs, $23.01 in total. Methodology, every chart and caveats

Task success with vs without lucid. Haiku: plan changes early 8/8 vs 4/8, late 8/8 vs 0/8, policy 4/4 vs 4/4, simple 4/4 vs 4/4. Opus: early 5/5 vs 1/5, late 5/5 vs 2/5, simple 3/3 vs 3/3Task success with vs without lucid. Haiku: plan changes early 8/8 vs 4/8, late 8/8 vs 0/8, policy 4/4 vs 4/4, simple 4/4 vs 4/4. Opus: early 5/5 vs 1/5, late 5/5 vs 2/5, simple 3/3 vs 3/3

Scroll sideways to see the whole chart.

Opus 5.5 cost per passing run: plan changes early $1.01 vs $4.57, late $1.06 vs $2.35, simple task $0.37 vs $0.35Opus 5.5 cost per passing run: plan changes early $1.01 vs $4.57, late $1.06 vs $2.35, simple task $0.37 vs $0.35

Scroll sideways to see the whole chart.

Honest limits

Limits and FAQ

  • More agents, more tokens

    lucid cuts repeated exploration and re-explaining, not the cost of running each instance.

  • Decoupled work only

    Parallelism helps when parts don’t touch. Keep tightly coupled changes with one agent.

  • Parity for one agent

    Across sessions, Claude Code’s built-in memory already carries a policy forward. lucid matches it.

  • Bash writes are a heuristic

    Redirects, tee, cp/mv/rm, sed -i and Python writes are caught, not every way a program can write.

  • macOS and Linux

    POSIX only, because the log uses flock for locking.