lucid

Limits & FAQ

What lucid doesn’t do, measured where possible.

Honest limits#

  • More agents still means more tokens. lucid cuts repeated exploration and re-explaining, not the cost of running each instance.
  • Parallelism helps decoupled work. Keep tightly coupled changes with a single agent; /lucid:swarm says so too.
  • Single agent across sessions: Claude Code’s built-in auto-memory already carries a policy into the next session, and the benchmark shows parity there. lucid earns its keep when several agents work at once.
  • Bash write detection is a heuristic. It catches redirects, tee, cp/mv/rm, sed -i and Python writes, but not every way a program can write a file.
  • POSIX only (macOS and Linux), because the log uses flock for locking.
  • The benchmark is small. 3–8 runs per arm on one small codebase: a strong signal, not a paper.

FAQ#

Does lucid spawn agents?#

No. It keeps the agents Claude Code spawns in sync: the lead, its subagents and Agent-Teams teammates.

Does it cost tokens when nothing changed?#

No. Before each tool call an agent gets only what other agents wrote since it last looked; when that’s nothing, nothing is injected. With nothing to coordinate, the measured overhead was +$0.002 and +5 s per run on Haiku, and +$0.026 (+7%) and +6 s on Opus.

Does it slow down projects that don’t use it?#

No. Until a project runs lucid init, a tiny shell guard checks for .lucid/ and exits without starting Python.

Can I add notes myself?#

Yes. Run lucid note from your own terminal; your notes reach agents as coming from human. See the CLI reference.

Can I edit the plan in my editor?#

Yes. Plan edits made outside Claude’s tools are picked up and attributed to user, and running agents get the diff before their next tool call. /lucid:replan does the same from inside Claude Code and also logs the decision.

What happens after /compact?#

The dream is injected again. In a real run, after a compaction the lead quoted a log entry word for word, from the re-injected dream rather than the summary.

Is it worth it with a single agent?#

Across sessions, Claude Code’s built-in auto-memory already carries a policy forward, and the benchmark shows parity there. lucid earns its keep when several agents work at once.

Does it work with git worktrees?#

Yes. Worktrees share the main checkout’s dream. For a worktree outside the repo, set LUCID_ROOT.

What if two people append to the log on different branches?#

lucid init sets log.jsonl merge=union in .lucid/.gitattributes, so two people appending never conflict.

Does it run on Windows?#

No. lucid is POSIX only (macOS and Linux), because the log uses flock for locking.