lucid

Quick start

From an empty project to parallel workers that follow your change of plan, in five steps. This assumes you have installed the plugin.

  1. Turn lucid on

    In your project, create the dream:

    lucid init        # creates .lucid/ ; write your plan in .lucid/plan.md

  2. Write the plan

    Open .lucid/plan.md and write the goal, then tasks that each own a separate set of files. For example:

    .lucid/plan.md
    # Plan ## GoalAdd discounts and item removal to the shop. ## Tasks (one owner per file set)- [ ] shop/pricing.py: add discount(price, pct)- [ ] shop/cart.py: add Cart.remove(item) ## Constraints / non-goals

    Keep tightly coupled work with one agent: parts that share files, or that depend on design decisions still open. Parallel agents only help on parts that don’t touch each other.

  3. Split the work with /lucid:swarm

    In Claude Code
    /lucid:swarm add discounts and cart removal

    The lead writes or updates the plan, settles cross-cutting decisions (interfaces, names, data shapes) and logs each one, then spawns one worker per task. It uses Agent Teams when enabled, otherwise background subagents. Each worker first claims its files with lucid claim. Workers don’t need the plan pasted into their brief: hooks inject it.

    While they work, their decisions, dead ends and blockers reach the lead as [lucid] notes.

  4. Change your mind with /lucid:replan

    In Claude Code
    /lucid:replan Cart.total() must apply discount() over 100

    The plan is edited in place and the change is logged as a decision. Every running worker gets the diff before its next tool call, with a reminder that the plan overrides its original brief. This is what a worker saw in a real run:

    Injected into the running worker
    [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

    You can also edit .lucid/plan.md directly in your editor. lucid picks up plan edits made outside Claude’s tools too.

    At the end, the lead verifies the result itself (tests, build) instead of trusting summaries, and checks lucid status for unresolved blockers.

  5. Consolidate with /lucid:dream

    In Claude Code
    /lucid:dream

    When the log gets long, or before you hand the project to a new session, /lucid:dream merges duplicates, retires stale or wrong entries and writes .lucid/digest.md. It suggests up to three lessons for CLAUDE.md and asks before adding them. It runs only when you invoke it.