🌟 Why CodeFlow?

Stop letting AI jump straight into code! CodeFlow sits between your intent and AI agents, creating a structured planning layer that ensures quality, consistency, and maintainability.

❌ The Problem

• AI agents jump to code without proper planning
• Lost context in large codebases
• Hallucinated APIs and misunderstood requirements
• Regressions and unexpected bugs
• Hours of cleanup and refactoring

✅ The CodeFlow Solution

• 📋 Detailed Planning - Break down complex tasks into manageable phases
• 🎯 Context-Aware - Understands your project structure
• 🔍 Verifiable - Check if implementation matches the plan
• 🤖 Agent-Agnostic - Works with Cursor, Claude, Copilot, etc.
• ⚡ Fast - Generate plans in seconds with AI

🎨 Features

🚀 Quick Start

📦 Installation

# Install globally (recommended)
npm install -g codeflow-cli

# Or use with npx
npx codeflow-cli init

🔑 Setup API Key

CodeFlow supports OpenAI or Anthropic:

# Option 1: OpenAI (Recommended)
export OPENAI_API_KEY="sk-your-api-key-here"

# Option 2: Anthropic Claude
export ANTHROPIC_API_KEY="sk-ant-your-api-key-here"

# Option 3: Use .env file
echo "OPENAI_API_KEY=sk-..." > .env

⚡ 3-Step Workflow

# 1️⃣ Initialize in your project
codeflow init

# 2️⃣ Generate a plan
codeflow plan "Add user authentication with JWT and bcrypt"

# 3️⃣ Export for your AI agent
codeflow export plan-<id> --format cursor

That's it! Now give the exported plan to your AI coding agent.

📋 Complete Workflow

graph LR
    A[💡 Your Idea] --> B[🤖 CodeFlow Analyzes]
    B --> C[📝 Generates Plan]
    C --> D[📤 Export Plan]
    D --> E[🤖 AI Agent Codes]
    E --> F[✅ CodeFlow Verifies]
    F --> G{Pass?}
    G -->|Yes| H[🎉 Done!]
    G -->|No| I[🔄 Iterate]
    I --> C

💻 Usage Examples

Example 1: Add Authentication

# Generate detailed plan
$ codeflow plan "Add JWT authentication with refresh tokens"

✔ Codebase analyzed
✔ Plan generated
✔ Plan saved

╔═══════════════════════════════════════════════════════════╗
║        ✨  Plan Generated Successfully!  ✨            ║
╚═══════════════════════════════════════════════════════════╝

Plan Summary:
  Plan ID: plan-1708123456789
  Phases: 3
  Files Affected: 8
  Complexity: Medium
  Estimated Time: 2-3 hours

Phases:
  1. Setup authentication middleware (4 tasks)
  2. Create auth routes and controllers (5 tasks)
  3. Add token refresh mechanism (3 tasks)

💡 Next: codeflow export plan-1708123456789 --format cursor

Example 2: Interactive Mode

$ codeflow plan --interactive

? What would you like to build? » Add user profile page
? Any specific requirements? » Should include avatar upload and bio editing
? Which files should be modified? » Let CodeFlow decide
? Generate plan now? » Yes

Analyzing... ⠼

Example 3: Phase-by-Phase Implementation

# Export just Phase 1
$ codeflow export plan-123 --phase 1 -o phase1.md

# Implement Phase 1 with your AI agent...

# Verify Phase 1
$ codeflow verify plan-123 --phase 1

✔ Phase 1 verification complete

  ✅ auth.middleware.ts created
  ✅ jwt.utils.ts created
  ⚠️  Missing: Error handling in middleware
  
  2/3 tasks completed (66%)

# Continue with Phase 2...
$ codeflow export plan-123 --phase 2

Example 4: Verification with Report

$ codeflow verify plan-123 --report report.md

✅ Overall Status: PARTIAL

Summary:
  Total Tasks: 12
  Completed: 9 ✓
  Partial: 2 ⚠
  Missing: 1 ✗

📄 Report saved to: report.md

🎯 Commands Reference

codeflow init [options]

Options:
  -n, --name <name>    Project name
  --skip-analysis      Skip initial codebase analysis

Examples:
  codeflow init
  codeflow init --name "My Awesome Project"
  codeflow init --skip-analysis

Creates .codeflow/ directory with configuration and analyzes your project.

codeflow plan [description] [options]

Arguments:
  description          What you want to build

Options:
  -i, --interactive    Interactive mode with prompts
  -o, --output <path>  Save plan to specific path
  -f, --format <fmt>   Output format (markdown, json)

Examples:
  codeflow plan "Add REST API for blog posts"
  codeflow plan --interactive
  codeflow plan "Refactor auth" -o plans/auth-refactor.md
  codeflow plan "Add dark mode" --format json

Generates a detailed, phase-based implementation plan using AI.

codeflow verify <plan-id> [options]

Arguments:
  plan-id              ID of the plan to verify

Options:
  -p, --phase <num>    Verify specific phase only
  -t, --task <id>      Verify specific task only
  -r, --report <path>  Save verification report
  --fix                Attempt auto-fix (experimental)

Examples:
  codeflow verify plan-123
  codeflow verify plan-123 --phase 1
  codeflow verify plan-123 --report verification.md
  codeflow verify plan-123 --fix

Compares your code against the plan and identifies gaps.

codeflow export <plan-id> [options]

Arguments:
  plan-id              ID of the plan to export

Options:
  -f, --format <fmt>   Export format (markdown, json, cursor)
  -o, --output <path>  Output file path
  -p, --phase <num>    Export specific phase only

Examples:
  codeflow export plan-123
  codeflow export plan-123 --format cursor
  codeflow export plan-123 --phase 1 -o phase1.md
  codeflow export plan-123 --format json -o plan.json

Exports plan in formats optimized for AI coding agents.

codeflow list [options]

Options:
  -s, --status <status>  Filter by status (ready, in-progress, completed)

Examples:
  codeflow list
  codeflow list --status ready
  codeflow list --status in-progress

Shows all generated plans with their status.

codeflow show <plan-id> [options]

Arguments:
  plan-id              ID of the plan to display

Options:
  -p, --phase <num>    Show specific phase only

Examples:
  codeflow show plan-123
  codeflow show plan-123 --phase 2

Displays detailed information about a specific plan.

⚙️ Configuration

CodeFlow stores configuration in .codeflow/config.json:

{
  "version": "1.0.0",
  "projectRoot": "/path/to/your/project",
  "plansDirectory": "plans",
  "cacheDirectory": ".codeflow/cache",
  "excludePatterns": [
    "node_modules/**",
    "dist/**",
    "build/**",
    ".git/**"
  ],
  "ai": {
    "provider": "openai",
    "model": "gpt-4o",
    "maxTokens": 4096,
    "temperature": 0.7
  },
  "verification": {
    "strictMode": false,
    "ignoreWarnings": false,
    "autoFix": false
  }
}

Supported AI Models

| Provider | Models | API Key | |----------|--------|---------| | OpenAI | gpt-4o, gpt-4-turbo, gpt-3.5-turbo | OPENAI_API_KEY | | Anthropic | claude-sonnet-4-20250514, claude-opus-4-20250514 | ANTHROPIC_API_KEY |

🏗️ Project Structure

After initialization, your project will have:

your-project/
├── .codeflow/
│   ├── config.json          # Configuration
│   ├── metadata.json        # Project metadata
│   └── cache/               # Cached analysis
├── plans/
│   ├── plan-123.json        # Plan data (JSON)
│   ├── plan-123.md          # Plan markdown
│   └── plan-123-export.md   # Exported plan
├── src/                     # Your source code
└── ...

🎭 Supported Frameworks

| Frontend | Backend | Mobile | Full-Stack | |----------|---------|--------|------------| | React | Express | React Native | Next.js | | Vue | Fastify | Expo | Nuxt | | Angular | NestJS | Flutter | Remix | | Svelte | Koa | Ionic | SvelteKit |

🔥 Advanced Features

🎨 Custom Templates

Create custom plan templates:

# Create template
nano .codeflow/templates/my-template.md

# Use template
codeflow plan "Task" --template my-template

🔗 Integration with CI/CD

# .github/workflows/verify-plan.yml
name: Verify Implementation
on: [pull_request]
jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - run: npm install -g codeflow-cli
      - run: codeflow verify ${{ github.event.pull_request.title }}

📊 Analytics & Insights

# View project insights
codeflow insights

# Export metrics
codeflow metrics --export metrics.json

🤝 Integrations

Cursor IDE

# Generate plan
codeflow plan "Add feature"

# Export for Cursor with checklist
codeflow export plan-123 --format cursor

# In Cursor: Load the exported file and start coding!

VS Code + GitHub Copilot

# Export as markdown
codeflow export plan-123 --format markdown

# Use as context in Copilot Chat

Claude Code (Anthropic)

# Export with Claude-optimized format
codeflow export plan-123 --format cursor

# Paste into Claude Code interface

📊 Comparison

| Feature | Without CodeFlow | With CodeFlow | |---------|-----------------|---------------| | Planning | Ad-hoc, in your head | Structured, AI-powered | | Context Loss | Frequent | Minimal | | Quality | Inconsistent | Consistent & Verified | | Rework | 30-40% of time | < 10% of time | | Documentation | Often missing | Auto-generated | | Team Collaboration | Unclear intent | Clear plan to follow |

🎓 Best Practices

✅ Do's

• 🎯 Be specific in your task descriptions
• 📋 Review generated plans before implementing
• ✅ Verify after each phase
• 💾 Keep plans under version control
• 📝 Add context about your project structure

❌ Don'ts

• 🚫 Don't skip the initialization step
• 🚫 Don't ignore verification warnings
• 🚫 Don't make large changes without a plan
• 🚫 Don't forget to set your API key
• 🚫 Don't ignore complex tasks - break them down!

🐛 Troubleshooting

Error: CodeFlow is not initialized in this directory

Solution:

cd your-project-directory
codeflow init

Error: No AI API key found

Solution:

# For OpenAI
export OPENAI_API_KEY="sk-..."

# For Anthropic
export ANTHROPIC_API_KEY="sk-ant-..."

# Or create .env file
echo "OPENAI_API_KEY=sk-..." > .env

Solution:

1. Check your API key is valid
2. Ensure you have internet connection
3. Try with a simpler description first
4. Check API rate limits

🚧 Roadmap

• [ ] 🌐 Web dashboard for plan management
• [ ] 🔌 VS Code extension
• [ ] 🤖 More AI provider support (Google Gemini, etc.)
• [ ] 📱 Mobile app for plan review
• [ ] 🔄 Git integration for auto-verification
• [ ] 📊 Advanced analytics and insights
• [ ] 🎨 Custom themes and styling
• [ ] 🌍 Multi-language support

🤝 Contributing

We love contributions! 🎉

1. 🍴 Fork the repository
2. 🌿 Create your feature branch (git checkout -b feature/amazing)
3. 💻 Make your changes
4. ✅ Test thoroughly
5. 📝 Commit (git commit -m 'Add amazing feature')
6. 🚀 Push (git push origin feature/amazing)
7. 🎯 Open a Pull Request

See CONTRIBUTING.md for detailed guidelines.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

MIT License - Copyright (c) 2026 Nishant Gaurav

💬 Support & Community

Get Help & Connect

🙏 Acknowledgments

• 💡 Inspired by Traycer
• 🤖 Powered by OpenAI and Anthropic
• 🌟 Built with TypeScript, Commander.js, and Chalk
• ❤️ Thanks to all contributors

👨‍💻 Author

Nishant Gaurav

🌟 Star History

⚡ Plan Your Flow, Code With Confidence ⚡

Made with ❤️ by Nishant Gaurav

If CodeFlow makes your life easier, consider giving it a ⭐ on GitHub!

⬆ Back to Top

© 2026 CodeFlow CLI • MIT License • Report Issue