LucidForge

Structured AI code generation with step-by-step review. LucidForge breaks feature development into phases — discovery, planning, execution, code review, and documentation — then gives you a rich review experience with diffs, change maps, per-file reasoning, and design pattern identification.

Two components work together:

1. Claude Code skills orchestrate the development workflow and write structured artifact files
2. A viewer reads those artifacts and presents diffs, change maps, and insights for human review. LucidForge ships two viewers today:
   • Desktop app (Wails, Go + React) — the reference implementation, with the full change-map and agent-management UI.
   • JetBrains plugin (Kotlin) — a lightweight tool window that lives alongside your code in IntelliJ IDEA, PyCharm, WebStorm, Rider, and other IntelliJ-based IDEs. Opens diffs in the IDE's native diff viewer.

Quick Start

1. Install the desktop app

Download the latest release for your platform from the Releases page:

• Windows — lucidforge-windows-amd64.zip → extract and run lucidforge.exe
• macOS — lucidforge-macos-universal.zip → extract and run lucidforge.app
• Linux — lucidforge-linux-amd64.AppImage → see Linux install below

The app will prompt you to install the Claude Code skills on first launch. Click Install to copy them to ~/.claude/commands/. If you already have skills installed under ~/.claude/skills/, the app will detect them automatically and skip the prompt.

1a. Install the skills manually (optional)

If you prefer to install from source or skip the app:

./install.sh          # global install → ~/.claude/commands/

2. Generate agents for your project

Open Claude Code in your project directory and run:

/lucidforge-agents

This scans your project and creates specialized agents (e.g., "Backend API", "Frontend", "Data Layer") in .claude/agents/. Each agent owns specific directories and accumulates learnings over time.

3. Run a feature

/lucidforge "add-user-auth" -p "Add JWT-based authentication with login and register endpoints"

LucidForge walks through six phases:

Phase	What happens
Discovery	Explores codebase, asks clarifying questions, writes feature spec
UX Design	Designs user flows and creates HTML mockups (optional, UI features only)
Planning	Breaks feature into steps, assigns agents, predicts file changes
Execution	Spawns agents step by step, validates (build + test) after each
Code Review	Reviews generated code, auto-fixes issues
Documentation	Updates project docs to reflect changes (if applicable)

Each phase writes artifact files to .lucidforge/features/{feature-id}/.

Flags:

• -p "..." — feature description (skips the "what do you want to build?" question)
• --auto-approve — skip interactive approval gates
• --skip-ux — skip UX design phase

4. Review changes

Option A: Desktop app

Download and run the app from the Releases page (see Install below). Open the project directory in the app.

The app shows:

• Discovery — what was asked for, requirements, technical approach
• Plan — step-by-step breakdown with agent assignments and file predictions
• UX Design — user flows, component specs, HTML mockups you can open in a browser
• AI Review Notes — issues found during code review and what was auto-fixed
• Review — per-step diffs with syntax highlighting, change navigation, per-file reasoning, and an interactive change map showing how files connect

You can edit files directly in the diff viewer — changes auto-save to disk. Mark files as reviewed to track your progress. Use side-by-side or unified diff mode, toggle whitespace visibility, and search within files.

The app auto-refreshes when artifact files change, so you can have it open while a feature is still executing.

Option B: JetBrains IDE plugin

If you work in IntelliJ IDEA, PyCharm, WebStorm, Rider, GoLand, or any other JetBrains IDE, install the LucidForge plugin to review features without leaving your editor. Download lucidforge-jetbrains-<version>.zip from the Releases page (tags starting with jetbrains-v), then in your IDE: Settings → Plugins → ⚙ → Install Plugin from Disk….

The plugin adds a LucidForge Review tool window on the left sidebar where you pick a feature, pick a step, and click a file to open its diff in the IDE's native diff viewer. Files have a viewed checkbox (persisted to the step JSON), and Discovery / Plan / Issues / Insights buttons open the corresponding artifacts as editor tabs. See jetbrains/README.md for full details.

Option C: Read the files directly

Everything is in .lucidforge/features/{feature-id}/ as human-readable JSON and markdown. You can inspect them with any text editor.

5. Make targeted changes (optional)

If you spot something during review that needs adjusting — a bug, a missed requirement, a style issue — run:

/lucidforge-change "description of what to change"

This makes the targeted edit using the same agent that owned the step, re-validates (build + tests), and updates the step artifact so the diff in the app reflects the change. You can run it as many times as needed.

6. Commit the feature

In Claude Code, run:

/lucidforge-commit

This:

1. Finds features ready for review (or takes a feature ID)
2. Extracts learnings from the feature's execution and appends them to the relevant agent files
3. Shows a proposed commit message for your approval
4. Stages all changed files plus updated agent files
5. Creates a single commit (does not push)

Agents accumulate project-specific knowledge through learnings — patterns, gotchas, conventions, and relationships discovered during each feature. These learnings make future features more accurate.

You can also cancel a feature from the app (✖ button on the feature card), with the option to revert changes or keep them.

Install

Windows & macOS

Download the latest release from the Releases page, extract the archive, and run the app. On first launch, click Install when prompted to install the Claude Code skills.

Linux

Download lucidforge-linux-amd64.AppImage from the Releases page.

Prerequisites (Ubuntu 22.04+):

sudo apt install libfuse2

Run directly (no install):

chmod +x lucidforge-linux-amd64.AppImage
./lucidforge-linux-amd64.AppImage

Integrate with your app launcher (move to permanent location first):

mkdir -p ~/.local/bin
mv lucidforge-linux-amd64.AppImage ~/.local/bin/lucidforge.AppImage
chmod +x ~/.local/bin/lucidforge.AppImage
APPIMAGE_EXTRACT_AND_RUN=1 ~/.local/bin/lucidforge.AppImage --install

This copies the .desktop file and icon into ~/.local/share/ so LucidForge appears in GNOME, KDE, and other desktop launchers. The launcher entry is automatically configured to run without FUSE.

Blank window on launch? WebKit2GTK 2.40+ ships a DMA-BUF renderer that produces a blank window on some Linux setups. The AppImage works around this by setting WEBKIT_DISABLE_DMABUF_RENDERER=1 automatically. If you're running a wails dev build or seeing the same issue elsewhere, set it manually:

WEBKIT_DISABLE_DMABUF_RENDERER=1 wails dev

Skills (manual install from source)

# Global install (all projects)
./install.sh

# Per-project install
./install.sh --project /path/to/your/project

Build from Source

Desktop app — requires Go and Wails v2:

go install github.com/wailsapp/wails/v2/cmd/wails@latest
cd app
wails build

The built binary is in app/build/bin/.

JetBrains plugin — requires JDK 17+; Gradle wrapper is included:

cd jetbrains
./gradlew clean buildPlugin

The plugin zip is written to jetbrains/build/distributions/lucidforge-jetbrains-<version>.zip. See jetbrains/README.md for details.

Skills Reference

Skill	Command	Purpose
lucidforge	/lucidforge "name" -p "description"	Orchestrate a full feature through all phases
lucidforge-agents	/lucidforge-agents	Generate or refresh project agents
lucidforge-change	/lucidforge-change "description"	Make a targeted change to a feature under review
lucidforge-commit	/lucidforge-commit [feature-id]	Commit a completed feature, extract agent learnings
lucidforge-cancel	/lucidforge-cancel [feature-id]	Cancel a feature, optionally revert changes

Managing Agents

Agents are standard Claude Code agent files in .claude/agents/ with lucidforge: true in their frontmatter. You can manage them:

• From Claude Code: Run /lucidforge-agents --refresh to update after restructuring
• From the app: Click "Agents" to add, edit, delete, or merge agents with a visual editor
• Manually: Edit the .md files directly

Each agent has:

• Identity — who the agent is and what it owns
• Directories — which parts of the codebase it's responsible for
• Instructions — your project-specific guidelines (you write these)
• Learnings — patterns discovered during feature execution (accumulated automatically)

Artifact Files

.lucidforge/
└── features/
    └── add-user-auth/
        ├── feature.json       # metadata, status
        ├── discovery.md       # feature description
        ├── plan.md            # step plan with task lists
        ├── ux.md              # UX design (optional)
        ├── mockups/           # HTML mockups (optional)
        ├── review.json        # code review issues (optional)
        └── steps/
            ├── 00-backend-api.json
            ├── 01-frontend.json
            └── ...

The artifact schema is documented in docs/artifact-schema.md. Any tool that reads this format can be a LucidForge viewer.

Project Structure

app/                                # Wails desktop app (Go + React)
    skills/                         # Claude Code skill files (bundled in the app)
        lucidforge/SKILL.md
        lucidforge-agents/SKILL.md
        lucidforge-cancel/SKILL.md
        lucidforge-change/SKILL.md
        lucidforge-commit/SKILL.md
jetbrains/                          # JetBrains IDE plugin (Kotlin, IntelliJ Platform)
docs/                               # design documentation
install.sh                          # skill installer (for source installs)

Each viewer (desktop app, JetBrains plugin) is released independently with its own tag prefix (app-v*, jetbrains-v*) and shares only the artifact schema — there's no shared runtime code between them.

License

MIT