claude-fsd

Automated project development - let AI build your project while you sleep.

What is this?

claude-fsd is an automated development system that runs continuous development cycles without constant supervision. Write a brief description of what you want, answer some clarifying questions, then let it build your project autonomously.

Think of it like Tesla FSD for code - it handles the driving, but you should keep an eye on it and occasionally take the wheel when needed.

How the Agent System Works

The system operates with multiple specialized AI agents working together:

• 🧑‍💻 Developer Agent: Writes code, implements features, fixes bugs
• 📋 Planner Agent: Breaks down tasks, manages the development roadmap
• 👀 Reviewer Agent: Reviews code quality, catches issues, ensures best practices
• 🧪 Tester Agent: Runs tests, validates changes, commits clean code

The agents work in continuous cycles:

Plan → Develop → Review → Test → Commit → Repeat

You can leave it running while you grab lunch or sleep - it just keeps going until it thinks the project is complete.

Installation

npm install -g claude-fsd

Quick Start

claude-fsd

The system will walk you through the setup process:

1. Create a BRIEF.md - Write a short description of what you want to build
2. Answer questions - The AI will generate clarifying questions for you to answer
3. Let it rip - Start the automated development process

Working with Multiple Projects

You can run multiple projects in the same repository using the --working-dir parameter:

# Default behavior (uses 'docs' directory)
claude-fsd

# Custom project directories
claude-fsd --working-dir=frontend
claude-fsd --working-dir=backend
claude-fsd --working-dir=client-app/docs

Commands

Main wrapper command

claude-fsd                    # Interactive mode (recommended for beginners)
claude-fsd dev                # Jump straight into development mode
claude-fsd interview          # Interactive requirements gathering
claude-fsd create-plan        # Generate development plan from requirements

# With custom working directory
claude-fsd --working-dir=project1 dev
claude-fsd --working-dir=backend interview

# claudefsd also works the same way
claudefsd                     # Same as claude-fsd

Individual commands (if you know what you're doing)

claudefsd-dev

Runs the development agent fleet. This command:

• Reads your project plan from PLAN.md in your working directory
• Intelligently selects and executes tasks (single agent for complex work, parallel agents for independent tasks)
• Has the code reviewed and tested
• Updates the plan to track progress
• Repeats until all tasks are done

Options:

• --max-time=MINUTES - Maximum total runtime (default: 120 minutes)
• --working-dir=DIR - Directory containing BRIEF.md and PLAN.md (default: docs)

Every 4th cycle, it activates "megathinking mode" using ultrathink for deep architectural planning.

@STOP Checkpoint: Add @STOP on its own line in PLAN.md to pause when all preceding tasks complete. Useful for human review or deployment gates.

claudefsd-interview

Interactive expert Q&A session that:

• Analyzes your BRIEF.md with multiple AI personas (DBA, Architect, UX Expert, etc.)
• Asks targeted questions to understand requirements
• Saves answers in QUESTIONS.md and consolidated requirements in REQUIREMENTS.md
• Supports resuming interrupted sessions

claudefsd-create-plan

Generates a comprehensive development plan based on:

• Your project brief (BRIEF.md)
• Interview answers (QUESTIONS.md) or requirements (REQUIREMENTS.md)
• Creates PLAN.md with prioritized tasks and CLAUDE-NOTES.md with architectural analysis
• Uses Claude Sonnet with ultrathink for deep strategic planning

How it Works

1. Write a BRIEF.md - Describe what you want to build in your working directory
2. Run the interview - Answer AI-generated questions from domain experts
3. Generate the plan - AI creates a comprehensive development roadmap
4. Start the development loop - The system automatically:
   • Analyzes all open tasks in PLAN.md
   • Intelligently executes tasks (sequentially or in parallel)
   • Updates the plan to track progress
   • Repeats until all tasks are complete or is detected

Monitoring Progress (Like Tesla FSD)

This isn't sci-fi level "sleep through the entire project" automation - it's more like Tesla FSD. The system handles most of the work, but you should monitor it and be ready to intervene when needed.

Recommended monitoring approach:

• Run a parallel Claude session - Open another Claude window/tab to chat about the project
• Check status periodically - Ask the parallel Claude: "What's the current status of my project?"
• Review the plan - Look at PLAN.md in your working directory to see what's been completed
• Watch for drift - If the system goes off track, intervene before it gets too far

When you need to course-correct:

• Update the plan - Add urgent fixes or redirections to the top of PLAN.md
• Direct intervention - Use your parallel Claude session to directly fix issues
• The system adapts - claude-fsd will pick up plan changes on the next loop iteration

Interruptible design:

• Hit Ctrl+C anytime to pause
• Restart later with claude-fsd dev
• Perfect for running overnight, during meetings, or while getting lunch

Requirements

Required

• Node.js >= 14.0.0
• Unix-like environment (macOS, Linux)
• Claude CLI (claude command)

Project Structure

Flexible Structure: Files can be placed in either docs/ (default) or root directory .

• System automatically detects file locations
• Use docs/ for larger projects to keep files organized
• Use root . for smaller projects for simplicity

Default structure (using 'docs' as working directory):

your-project/
├── docs/
│   ├── BRIEF.md         # Project overview and requirements
│   ├── PLAN.md          # The development plan (tasks with [ ] checkboxes)
│   ├── CLAUDE-NOTES.md  # AI architect's analysis and notes
│   ├── QUESTIONS.md     # Interview questions and answers
│   ├── REQUIREMENTS.md  # Consolidated requirements from interview
│   ├── IDEAS.md         # Future ideas and improvements
│   └── INTERVIEW-SESSION.json  # Interview session metadata
├── logs/                # Logs from each AI session
└── [your code files]

Simple structure (files in root):

your-project/
├── BRIEF.md
├── PLAN.md
├── CLAUDE-NOTES.md
├── logs/
└── [your code files]

With custom working directory:

your-project/
├── frontend/
│   ├── BRIEF.md
│   ├── PLAN.md
│   └── ...
├── backend/
│   ├── BRIEF.md
│   ├── PLAN.md
│   └── ...
└── logs/

Tips for Success

1. Keep your BRIEF.md concise - A few clear paragraphs work better than lengthy specifications
2. Answer questions thoroughly - The AI's questions help it understand your exact needs
3. Monitor periodically - Check progress while it runs, especially during initial cycles
4. Use the plan as your steering wheel - Update PLAN.md to guide development direction
5. Trust the process - Let it run autonomously, but verify the results
6. Use --working-dir for multiple projects - Run different projects in parallel by specifying different directories

Model Selection Strategy

The system uses Claude Sonnet throughout with strategic ultrathinking for complex work:

• Sonnet + Ultrathink: Used for complex architectural work requiring deep thinking

  • Requirements consolidation (interview)
  • Deep strategic planning (create-plan)
  • Megathinking mode (every 4th dev iteration)

• Sonnet (Standard): Used for regular development

  • Standard development tasks
  • Code implementation and reviews
  • Most development iterations
  • Question generation in interview

License

MIT