⚡ CodeFlow CLI ⚡

🎯 Plan Your Flow, Code With Confidence 🎯

The Intelligent Planning Layer for AI Coding Agents

Transform your ideas into detailed, verifiable implementation plans before writing a single line of code.

🚀 Quick Start • 📖 Documentation • 💻 Examples • 🤝 Contributing

🌟 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

🧠 AI-Powered Planning Leverage GPT-4 or Claude to generate detailed, phase-based implementation plans	📊 Smart Analysis Automatically analyzes your codebase structure, dependencies, and patterns	✅ Auto Verification Compares your implementation against the plan to catch gaps and issues
📤 Multi-Format Export Export plans as Markdown, JSON, or agent-specific formats	🔄 Phase Management Break complex tasks into sequential, manageable phases	🎭 Framework Aware Understands React, Express, Next.js, and more

🚀 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 - Initialize CodeFlow

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 - Generate implementation plan

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 - Verify implementation

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 - Export plan for agents

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 - List all plans

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 - Display plan details

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

❓ CodeFlow not initialized

Error: CodeFlow is not initialized in this directory

Solution:

cd your-project-directory
codeflow init

❓ API Key not found

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

❓ Plan generation fails

Solution:

Check your API key is valid
Ensure you have internet connection
Try with a simpler description first
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! 🎉

🍴 Fork the repository
🌿 Create your feature branch (git checkout -b feature/amazing)
💻 Make your changes
✅ Test thoroughly
📝 Commit (git commit -m 'Add amazing feature')
🚀 Push (git push origin feature/amazing)
🎯 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

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
assets		assets
src		src
.gitignore		.gitignore
.npmignore		.npmignore
CHANGELOG.md		CHANGELOG.md
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
Readme.md		Readme.md
codeflow-cli-1.0.0.tgz		codeflow-cli-1.0.0.tgz
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json

License

CodewithEvilxd/codeflow-cli

Folders and files

Latest commit

History

Repository files navigation

⚡ CodeFlow CLI ⚡

🎯 Plan Your Flow, Code With Confidence 🎯

🌟 Why CodeFlow?

❌ The Problem

✅ The CodeFlow Solution

🎨 Features

🧠 AI-Powered Planning

📊 Smart Analysis

✅ Auto Verification

📤 Multi-Format Export

🔄 Phase Management

🎭 Framework Aware

🚀 Quick Start

📦 Installation

🔑 Setup API Key

⚡ 3-Step Workflow

📋 Complete Workflow

💻 Usage Examples

Example 1: Add Authentication

Example 2: Interactive Mode

Example 3: Phase-by-Phase Implementation

Example 4: Verification with Report

🎯 Commands Reference

⚙️ Configuration

Supported AI Models

🏗️ Project Structure

🎭 Supported Frameworks

🔥 Advanced Features

🎨 Custom Templates

🔗 Integration with CI/CD

📊 Analytics & Insights

🤝 Integrations

Cursor IDE

VS Code + GitHub Copilot

Claude Code (Anthropic)

📊 Comparison

🎓 Best Practices

✅ Do's

❌ Don'ts

🐛 Troubleshooting

🚧 Roadmap

🤝 Contributing

📄 License

💬 Support & Community

Get Help & Connect

🙏 Acknowledgments

👨‍💻 Author

Nishant Gaurav

🌟 Star History

⚡ Plan Your Flow, Code With Confidence ⚡

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages