Lucid Train

Product Introduction

1. Definition: Lucid Train is a local-first, AI-powered software development harness and architecture diagram generator. It is a desktop application and command-line interface (CLI) tool that analyzes a local codebase to automatically generate deterministic system architecture diagrams, which are then used as a formal specification for an integrated AI coding agent.
2. Core Value Proposition: Lucid Train exists to bridge the gap between system design and implementation by enforcing a "systems-design-first" workflow. It solves the problem of outdated or non-existent documentation by automatically creating visual and textual specifications from live code, then using those specifications to guide AI-assisted coding, refactoring, and auditing tasks—all while keeping code and data fully offline on the user's machine.

Main Features

1. AI-Powered Architecture Diagram Generation: The core feature surveys a Git repository and uses a local or cloud AI model to generate a semantic graph of the system's components and relationships. It employs a deterministic ELK layout engine to auto-align nodes and route edges, guaranteeing non-overlapping, professional diagrams. The process is structured into five narrative "acts": Context, Containers, Data Flow, Data, and Failure Modes.
2. Specification-Driven AI Coding Agent: The generated diagram is automatically converted into a structured DESIGN.md markdown specification. This spec is handed to the integrated coding agent as the authoritative source of truth for implementing features, fixing bugs, or refactoring. The agent operates with a "plan → approve → apply" workflow, showing diffs for review before committing changes.
3. Multi-Model Orchestration & Local-First Operation: Lucid Train features a smart orchestrator that can route different tasks to different AI models (e.g., a fast model for planning, a strong coder for editing, a vision model for diagram analysis). It supports local models via Ollama (zero-setup, fully offline), OpenRouter, or direct API keys for services like Anthropic and OpenAI. All prompts and code are processed locally; no data is sent to Lucid Train's servers.
4. Unified Desktop Workspace with Specialized Tabs: The native desktop app consolidates multiple development workflows into a single interface with dedicated tabs: Code (chat with the agent), Diagram (architecture canvas), Audit (dependency and security scanning), Dashboards (integrated Grafana viewer), and Connectors (Model Context Protocol / MCP server management).
5. Terminal CLI (TUI) Alternative: For users who prefer the command line, the entire agent core is available as a 6 MB Rust binary with a keyboard-first Terminal User Interface (TUI). It offers live plans, thinking streams, diffs, and token accounting, providing a powerful, IDE-free coding agent experience.

Problems Solved

1. Pain Point: The disconnect between system architecture diagrams (often stale PowerPoint/Visio files) and the actual, evolving codebase. This leads to misalignment, technical debt, and onboarding difficulties.
2. Pain Point: The inefficiency of manually writing and maintaining DESIGN.md or similar specification documents, which are often verbose, quickly outdated, and not machine-actionable.
3. Target Audience: Software Engineers & Architects who need to understand, document, and modify complex systems. Engineering Managers who require clear, up-to-date architecture visuals for planning and review. DevOps/SRE Practitioners who audit system dependencies and monitor live dashboards. Developers who use AI coding assistants but want them to work from a precise, visual specification rather than vague prompts.
4. Use Cases: Onboarding & Codebase Discovery: New team members can generate an interactive architecture diagram from a repo in minutes. Refactoring & System Redesign: Visualize the current state, design the target architecture on the canvas, and use the AI agent to implement the changes guided by the new diagram. Documentation Automation: Automatically export updated SVG diagrams and update the ## Architecture section of a project's README. Dependency Auditing: Run integrated security scans (osv-scanner, npm audit, etc.) across the project within the Audit tab.

Unique Advantages

1. Differentiation: Unlike cloud-based diagramming tools (e.g., Lucidchart, Miro) or AI diagram generators, Lucid Train is fully offline, privacy-focused, and deeply integrated with the code development lifecycle. Unlike general AI coding assistants (e.g., Cursor, GitHub Copilot), it uses a generated visual architecture as a strict specification, reducing hallucination and improving context.
2. Key Innovation: The "diagram-as-spec" handoff is the central innovation. The tool doesn't just create a picture; it creates a structured, machine-readable design document (DESIGN.md) from the visual canvas. This document then constrains and guides the AI coding agent, creating a closed-loop system where design and implementation are continuously synchronized. The self-auditing feature, where the AI screenshots its own diagram and performs a vision check for errors, further ensures output quality.

Frequently Asked Questions (FAQ)

1. How does Lucid Train generate architecture diagrams from code? Lucid Train uses an AI model to semantically analyze your local source code, identifying components, services, data stores, and their relationships. It constructs a graph and passes it to the deterministic ELK layout engine, which calculates optimal node positions and orthogonal edge routes, ensuring clean, non-overlapping diagrams without manual placement.
2. Can Lucid Train run completely offline without an API key? Yes. Lucid Train has a built-in, zero-setup integration with Ollama. The installer can download Ollama and pull optimized local LLMs (like DeepSeek Coder, Qwen Coder). All diagram generation, code analysis, and agent tasks run 100% offline on your machine with no data transmitted externally.
3. What is the difference between the Lucid Train desktop app and the CLI? Both share the same core AI agent engine. The desktop app provides a graphical interface with multi-tab workspaces (Diagram, Audit, Dashboards), a visual diagram canvas, and integrated tools. The CLI is a lightweight 6 MB Terminal UI (TUI) focused on keyboard-driven, fast-paced coding agent interactions without a GUI. You can use either based on your workflow preference.
4. How does the pricing work for Lucid Train? The CLI (terminal version) is free and open-source. The desktop application costs $3/month or $30/year ($2.50/month billed annually), with a 7-day free trial. Crucially, Lucid Train does not meter or charge for AI usage. You pay for model inference separately, either by using free local models or by providing your own API keys for cloud providers (OpenAI, Anthropic, OpenRouter, etc.).
5. What AI models are supported and which one is best for coding? Lucid Train supports any OpenAI-compatible API endpoint. For optimal coding performance, it recommends and can route to high-performing open-weight models like DeepSeek V4 Pro (top of LiveCodeBench), GLM 5.2 (leader on SWE-bench Verified), and Kimi K2.7 Code (strong agentic performance). The orchestrator allows you to assign different models to planning, editing, and vision roles for cost-efficiency.