Version 3.0 - Central Reasoning Engine Edition
A structured development environment for Claude Code that transforms AI coding from conversation into deterministic, traceable software engineering.
🚀 New in v3.0: Central Reasoning Engine (CRE), Excalidraw AI Diagrams, Memory Plugin, and automated sprint orchestration with Code Model tracking.
Claude Code is extraordinary out of the box. It can take you to production for projects in the 10k-100k LoC range. But as projects grow, maintaining context, traceability, and structured collaboration becomes critical.
Puffin transforms AI coding from ad-hoc prompting into structured software engineering.
Prompts alone create confusion. Claude responds much better to a backlog-driven workflow with implementation plans:
- Prompts → User Stories - Specifications become structured, reviewable stories
- Stories → Sprint Planning - CRE generates implementation plans with dependencies and sequencing
- Plans → Ready-to-Implement Specs (RIS) - Deterministic specifications that any AI could implement
- RIS → Implementation - Claude executes with full architectural context from the Code Model
- Code Review → Verification - Assertions validate correctness, findings tracked for bug fixes
This structured approach, with automated Code Model maintenance, ensures traceability from requirements through implementation. You can charge ahead on complex projects without losing track of what was built, why, and how.
| Traditional AI Coding | Puffin v3.0 |
|---|---|
| Ad-hoc prompts | Structured user stories → Plans → RIS |
| Context lost over time | Code Model tracks codebase structure |
| Repeat architecture context | Memory Plugin auto-injects knowledge |
| Manual story-by-story | Automated sprint orchestration |
| Text-only planning | AI-generated diagrams from docs |
| Hope code matches requirements | Inspection assertions verify correctness |
| Implementation details in prompts | CRE generates deterministic RIS specs |
Key Benefits:
- Deterministic Implementation - Same RIS produces equivalent results across runs
- Traceability - Track from requirements → plan → RIS → implementation → verification
- Knowledge Retention - Architectural decisions preserved and auto-applied
- Sprint Automation - Let Claude orchestrate entire implementation cycles
- Visual Documentation - Generate diagrams directly from markdown docs
Puffin is an Electron-based application that provides a visual interface for Claude Code, Anthropic's official CLI for Claude. Rather than replacing the terminal, Puffin wraps it—giving you full agentic capabilities (file read/write, bash execution, tool use) with a structured workflow for managing cloding projects.
Puffin's philosophy is to provide a hierarchical view of the tasks being performed by Claude with traceability to architecture and user stories so that it becomes easier to work collaboratively with Claude and other cloders, rather than just being a passive tester.
You can't "prompt along" a coding agent, just like you can't "prompt along" a developer—there are good reasons why we came up with processes and methodologies to build complex solutions. Processes and methodologies for cloding are yet to be built, but they are coming. Puffin serves as a foundation for structured collaboration between humans and AI coding agents.
- Implementation Plans with dependency analysis and story sequencing
- Ready-to-Implement Specifications (RIS) - deterministic, AI-executable specs
- Code Model (h-DSL) tracking codebase structure with incremental updates
- Inspection Assertions for automated verification of implementation correctness
- MCP Integration for enhanced code exploration via Model Context Protocol
- Generate diagrams from docs - Architecture, sequence, flowcharts, component diagrams
- Professional hand-drawn aesthetic with 10+ element types
- Industry-standard format -
.excalidrawfiles compatible with Excalidraw web app - Multi-format export - PNG, SVG, and JSON
- Branch Memory Plugin auto-extracts domain knowledge from conversations
- Architectural Decisions captured and injected into future sessions
- Branch-specific context with facts, conventions, and bug patterns
- CLAUDE.md Generation with Code Model snippets and memory context
- Automated Sprint Implementation - Claude orchestrates entire sprints end-to-end
- Sequential Story Implementation with clean sessions per story
- Automated Code Review identifies issues, queues bug fixes
- Acceptance Criteria Validation after each implementation
- Cost & Duration Tracking with completion summaries
- RLM Plugin for Recursive Language Model document analysis
- Document Editor with syntax highlighting, inline prompt markers, auto-save
- Document Viewer for markdown and images
- Branched Conversations (Specifications, Architecture, UI, Backend, Deployment, Plugins)
- Git Integration with branch management, staging, commits, and merge operations
- Real-time Activity Tracking showing Claude's tool execution
- CLI Output View with live streaming and raw JSON debugging
- SAM Debugger for state management visualization
Watch the introduction
Ask in our Q&A Discussions and get AI-powered answers! Our bot uses Claude to respond to questions about Puffin, its features, and how to use it.
Puffin opens a project directory (like VS Code) and stores its state in a .puffin/ folder within that directory. When you submit a prompt, Puffin spawns the Claude Code CLI as a subprocess, streams the response in real-time, and persists the conversation history.
Your Project/
├── .puffin/
│ ├── config.json # Project configuration & Claude options
│ ├── history.json # Branched conversation history
│ ├── puffin.db # SQLite database (user stories, sprints, etc.)
│ ├── architecture.md # Architecture document
│ └── plugins/ # Claude Code plugins/skills
├── src/
└── ...your project files
- Platform: Electron 33+
- Frontend: Vanilla JavaScript (ES6+ modules)
- State Management: SAM Pattern (sam-pattern + sam-fsm)
- Database: SQLite via better-sqlite3 for persistent storage
- AI Integration: Claude Code CLI (spawned as subprocess with JSON streaming)
- Markdown: marked for rendering responses
| Component | Requirement | Notes |
|---|---|---|
| Node.js | v20 LTS | Required for SQLite native module support |
| RAM | 4GB minimum, 8GB+ recommended | CRE and Code Model operations are memory-intensive |
| Disk Space | 500MB for Puffin + project storage | Code Models and design files stored in .puffin/ |
| OS | Windows 10+, macOS 10.13+, Linux | Cross-platform Electron support |
| Claude CLI | Latest version | Install: npm install -g @anthropic-ai/claude-code |
| Claude Subscription | Pro or API access | Required for all AI operations |
📖 First time using Puffin? Check out the User Manual for a complete walkthrough of features, workflows, and best practices.
Before using Puffin, authenticate Claude Code CLI in your terminal:
# Install Claude Code CLI (if not already installed)
npm install -g @anthropic-ai/claude-code
# Authenticate with your Claude account
claude auth
# Verify authentication
claude --versionThe browser will open for login. Once authenticated, Puffin inherits this authentication automatically.
Windows PowerShell users: Optionally start Claude first to ensure full initialization:
claude
npm start# Clone the repository
git clone https://github.com/jdubray/puffin.git
cd puffin
# Install dependencies
npm install
# Start the application
npm startOn first launch, Puffin prompts you to select a project directory. Alternatively, pass a path:
npm start /path/to/your/project- Project Setup - Define description, assumptions, technical architecture
- Coding Preferences - Set style (OOP/FP), testing approach, documentation level
- Branch Focus - Configure focus areas for different branches (UI, Backend, etc.)
- Write Specifications - Describe what you want to build in the Specifications branch
- Derive User Stories - Click "Derive User Stories" to extract structured stories
- Create Sprint - Select stories from backlog and create a sprint
- Generate Plan - CRE analyzes stories and produces an implementation plan
- Approve & Implement - Review the plan, approve, and choose automated or manual implementation
📖 Need Help? Read the User Manual for detailed workflows, plugin guides, and best practices.
# Run with DevTools enabled
npm run dev
# Run tests
npm test
# Run specific test suite
npm test -- tests/rlm-chunk-strategy.test.js
# Build Excalidraw bundle (after modifying excalidraw-bundle-entry.js)
npm run build:excalidraw# Package for current platform
npm run package
# Package for all platforms
npm run package:all
# Package for specific platforms
npm run package:win # Windows
npm run package:mac # macOS
npm run package:linux # LinuxPackaged apps are output to dist/ directory. Electron Builder handles code signing (requires certificates for macOS/Windows distribution).
puffin/
├── src/
│ ├── main/ # Electron main process
│ │ ├── main.js # Entry point, window creation
│ │ ├── preload.js # Secure IPC bridge
│ │ ├── ipc-handlers.js
│ │ ├── puffin-state.js # .puffin/ directory management
│ │ ├── claude-service.js # Claude CLI subprocess
│ │ ├── database/ # SQLite database layer
│ │ │ ├── database-manager.js
│ │ │ ├── repositories/ # Data access layer
│ │ │ └── migrations/ # Schema migrations
│ │ └── plugins/ # Plugin system core
│ │
│ ├── renderer/ # Electron renderer process
│ │ ├── index.html
│ │ ├── app.js # Application bootstrap
│ │ ├── img/ # Logo and splash screen
│ │ ├── styles/ # CSS (main, components, themes, debugger)
│ │ ├── sam/ # SAM pattern (model, state, actions, instance)
│ │ ├── lib/ # SAM libraries (sam-pattern, sam-fsm)
│ │ ├── plugins/ # Plugin renderer components
│ │ └── components/ # UI components
│ │ ├── project-form/
│ │ ├── prompt-editor/
│ │ ├── response-viewer/
│ │ ├── history-tree/
│ │ ├── gui-designer/
│ │ ├── architecture/
│ │ ├── cli-output/
│ │ └── debugger/
│ │
│ └── shared/ # Shared utilities (validators, formatters, constants)
│
├── plugins/ # Built-in Puffin plugins
│ ├── stats-plugin/ # Usage statistics dashboard
│ ├── designer-plugin/ # GUI designer
│ ├── claude-config-plugin/ # CLAUDE.md context management
│ ├── document-viewer-plugin/ # Documentation browser
│ └── document-editor-plugin/ # Text file editor with syntax highlighting
│
├── projects/ # Example projects (optional)
└── tests/
Puffin uses the SAM (State-Action-Model) pattern for predictable state management:
User Intent → Action → Model → State → View → User Intent...
Two FSMs control application flow:
- App FSM: Application lifecycle (uninitialized → initializing → ready → error)
- Prompt FSM: Prompt lifecycle (idle → composing → submitted → streaming → completed/error)
The SAM Debugger (toggle with the magnifying glass icon or Ctrl+Shift+D) provides real-time visibility into state transitions.
Configure your project with guidance options for Claude:
- Programming style: OOP, FP, Temporal Logic, Hybrid
- Testing approach: TDD, BDD, Integration First
- Documentation level: Minimal, Standard, Comprehensive
- Error handling: Exceptions, Result Types, Either Monad
- Naming convention: camelCase, snake_case, PascalCase
- Comment style: JSDoc, Inline, Minimal
The main interaction area with:
- Branch tabs for organizing conversations by topic
- Response area with markdown rendering
- Prompt input with "Include GUI" option to attach your GUI design
Visual GUI designer with:
- Element palette: Container, Text, Input, Button, Image, List
- Drag-and-drop canvas with grid snapping
- Property inspector for selected elements
- Export to Claude-readable description
Comprehensive user story management interface with Kanban-style workflow:
- Full CRUD operations for user stories (create, edit, delete)
- Status tracking: Pending → In Progress → Completed → Archived
- Story derivation from specifications using Claude
- Interactive review workflow for derived stories
- Batch selection: Select multiple pending stories with checkboxes
- Start Implementation: Generate implementation prompts for selected stories with automatic planning
- Acceptance Criteria Verification: Claude must explicitly verify each numbered criterion (✅ done,
⚠️ partial, ❌ blocked) - Mark Complete: One-click completion for in-progress stories
- Auto-Archive: Completed stories older than 2 weeks are automatically archived
Markdown editor for documenting your system architecture, with "Review with Claude" for AI feedback.
Real-time streaming of Claude Code's output:
- Live Stream tab: Raw text output as it streams
- Messages tab: Parsed message blocks
- Raw JSON tab: Full JSON output for debugging
Puffin includes 12 built-in plugins that extend functionality:
Core Plugins:
- Excalidraw Sketcher 📐: AI-powered diagram generation from markdown docs (Architecture, Sequence, Flowchart, Component diagrams)
- Document Editor 📝: Collaborative Code/text editor with syntax highlighting (190+ languages), auto-save, inline prompt markers (
/@puffin: ... @/) - RLM Document Analysis 🔍: Recursive Language Model for analyzing large documents with chunking and aggregation
- Context 📄: CLAUDE.md configuration viewer/editor with branch focus management
- Docs 📁: Documentation browser for markdown and image files in your docs/ directory
Designer: Create simple GUI layouts to communicate UX requirements to Claude, this plugin is deprecated as we can now attach screen shots to a prompt to facilite the UX design
Analysis & Visualization:
- Memory Plugin 🧠: Auto-extracts domain knowledge from conversations (runs in background)
- Outcome Lifecycle 🎯: Track development outcomes across sprint phases
- Code Model 🗺️: Interactive Code Model visualization with dependency tracing and annotations
- Prompt Templates 📋: Create and reuse prompt templates for common tasks
Utility Plugins:
- Stats 📊: Usage statistics dashboard with weekly metrics, cost tracking, and markdown export
- Calendar 📅: Development activity timeline with sprints, git branches, and post-it notes
- Toast History 🔔: Notification history viewer with 24-hour tracking
The CRE transforms Puffin from a conversation tracker into a deterministic implementation system:
- Two-Stage Planning: Plans specify sequence and dependencies, RIS provides execution details
- Code Model (h-DSL): Living representation of your codebase structure
- Inspection Assertions: Testable criteria validate each implementation
- Plan Iteration: Review, question, and refine plans before approval
- CRE Introspector: Automatically updates Code Model after each sprint
Workflow: Sprint → CRE generates Plan → User approves → CRE generates RIS → Claude implements → Introspector updates Code Model
Generate professional diagrams from your documentation:
- Doc-to-Diagram Pipeline: Select markdown file, choose diagram type, Claude generates elements
- Diagram Types: Architecture, sequence, flowchart, component diagrams
- Hand-Drawn Aesthetic: Professional yet approachable via Rough.js rendering
- Export Formats: PNG, SVG, JSON
- Editable Results: Generated diagrams are fully editable in Excalidraw
Stop repeating context - let Puffin remember architectural decisions:
- Auto-Extraction: Background analysis extracts domain knowledge from conversations
- Categorized Storage: Facts, Architectural Decisions, Conventions, Bug Patterns
- Auto-Injection: Branch memory automatically included in CLAUDE.md context
- Memory Evolution: New knowledge merges with existing, deduplicates, resolves conflicts
Visualize and explore your Code Model:
- Interactive Graph: Navigate modules, dependencies, and relationships
- Annotations: See which primitives (TERM, PROSE, RELATION, etc.) map to each element
- Dependency Tracing: Follow import chains and call relationships
Embed Claude instructions directly in your documents with the new marker syntax:
/@puffin: your instructions here @/
- Insert via toolbar, context menu, or Ctrl+M
- Visual highlighting with yellow background and 🐧 icon
- Multiline support for complex instructions
- Holistic processing - Claude sees all markers and applies changes cohesively
- Clean markers button removes all markers when you're done
This workflow lets you annotate your code exactly where changes are needed, making it easier to communicate precise modifications to Claude.
Let Claude orchestrate entire sprints autonomously:
- Implementation Mode Selection: After plan approval, choose between automated (Claude orchestrates everything) or human-controlled (manual story-by-story)
- Intelligent Story Ordering: Claude analyzes dependencies and determines optimal implementation sequence
- Branch Assignment: Each story is assigned to the appropriate branch (UI, Backend, Fullstack, Plugin)
- Orchestration Plan Review: See the complete implementation plan before Claude starts
- Sequential Sessions: Each story is implemented in a separate, clean session
- Acceptance Criteria Validation: Automatic verification after each story implementation
- Code Review Phase: Automated code review identifies issues after all stories complete
- Bug Fix Sessions: Sequential sessions to address each finding from code review
- Completion Statistics: Summary showing costs, durations, and outcomes
- Graceful Interruption: Pause or stop automated implementation at any point
The core of Puffin's approach to structured cloding:
Prompt → Derive Stories → Review → Backlog → Pull → Thread → Implement → Complete
- Story Derivation: Claude extracts user stories from your specifications
- Review Interface: Refine, edit, or discard proposed stories before committing
- Backlog Management: Stories queue up with status tracking (Pending → In Progress → Completed)
- Implementation Threads: Each story gets its own focused thread with full context
- Completion Tracking: Mark stories and threads complete for clear progress visibility
Navigate complex project histories with ease:
- Collapsible Threads: All threads start collapsed for a clean overview
- Expand on Click: Click to expand and see child prompts
- Visual Indicators: Arrows show expandable threads, checkmarks show completed ones
- Context Menu: Right-click to mark complete, expand/collapse, or reply
- Strikethrough Styling: Completed threads are visually distinct
Enhanced transparency during prompt execution:
- Tool Monitoring: Real-time display of active Claude tools (Read, Write, Bash, etc.)
- File Operations: Track which files are being read, written, or edited
- Status Indicators: Visual feedback showing thinking, tool-use, and completion states
- Concurrent Support: Monitor multiple simultaneous tool executions
Keep Claude focused on what matters:
- Visual Context Indicator: See which prompts are in Claude's context window
- Session Resumption: Automatically resumes Claude sessions to maintain context
- Smart History: Only sends relevant context when resuming, not redundant history
Puffin includes a comprehensive Git panel for repository management directly within the application:
- Branch Management: Create, switch, and delete branches with configurable prefixes (feature/, bugfix/, etc.)
- Change Staging: View modified files, stage/unstage individual files or all changes
- Commit Workflow: Write commit messages manually or generate them with Claude based on staged changes
- Merge Operations: Merge branches with conflict detection and resolution guidance
- Operation History: Track all Git operations performed through Puffin
Cross-Platform Line Endings: Puffin includes a .gitattributes file that automatically normalizes line endings (CRLF/LF) across different operating systems. This prevents phantom "modified" files when working in mixed environments like Windows with WSL. No additional configuration is required—Git will automatically handle line ending conversions on commit.
- User Manual - Complete guide to features, workflows, and best practices
- Central Reasoning Engine Specification - CRE architecture and capabilities
- CRE Detailed Design - Technical implementation guide
- h-DSL & h-M3 Research - Hybrid DSL theoretical foundations
- Excalidraw Plugin Guide - AI diagram generation workflow
- Memory Plugin Lifecycle - How branch memory extraction works
- RLM Document Plugin - Recursive Language Model document processing
- Outcome Lifecycle - Sprint outcome tracking
- Calendar Plugin - Event scheduling and reminders
- GitHub Integration - Repository operations
- Architecture Report - System architecture analysis
- 3CLI Features Catalog - Claude Code CLI capabilities
- Plugin Architecture - Building Puffin plugins
- Q&A Discussions - Ask questions, get AI-powered answers
- Video Introduction - Watch the intro video
- Changelog - Full version history
MIT
- RLM Skill by John Adeojo - Recursive Language Model implementation
- SAM Pattern by Jean-Jacques Dubray - State-Action-Model architecture
- Claude Code by Anthropic - AI coding assistant
- Excalidraw - Hand-drawn diagram library
- Electron - Cross-platform desktop framework
- better-sqlite3 - Fast SQLite bindings
- marked - Markdown rendering
Puffin is under active development. Contributions welcome! See GitHub Issues for planned features and known issues.
MIT - See LICENSE file for details.
Built with ❤️ for the cloding community
Transforming AI coding from conversation into software engineering