DevFlow CLI

The official npm package wrapper for DevFlow - A Multi-Agent System for Claude Code

What is DevFlow? | Features | Installation | Usage | Development

What is DevFlow?

DevFlow is a powerful multi-agent system designed to supercharge your development workflow with Claude AI. It provides:

• Specialized AI Agents - Pre-configured agents for different development tasks
• Persistent Memory - Agents that remember context across sessions
• Session Management - Organized workflows with session tracking
• Seamless Integration - Works directly with Claude Code CLI

This CLI package is the official npm wrapper that makes it easy to install and configure DevFlow in any project with a single command.

Overview

DevFlow CLI simplifies the setup of DevFlow-powered projects by installing the multi-agent system, project structure templates, and configuration files into your existing projects. It handles dependency validation, provides OS-specific installation guidance, and ensures a smooth onboarding experience.

Features

| Feature | Description | |---------|-------------| | Project Initialization | Install DevFlow components into existing projects with a single command | | Web IDE | Start and manage the DevFlow Web IDE with automatic updates | | Dependency Validation | Automatically checks for Git, Claude Code, Node.js, Python, GCC, and Make | | Cross-Platform Support | Works on macOS, Windows, Ubuntu, Debian, Fedora, RHEL, CentOS, and Arch Linux | | Claude AI Agents | Installs pre-configured Claude agents for enhanced development workflows | | Conflict Resolution | Gracefully handles existing files with user prompts | | Smart .gitignore Merge | Intelligently merges DevFlow entries with your existing .gitignore |

Requirements

| Dependency | Required | Description | |------------|----------|-------------| | Git | Yes | Version control | | Claude Code | Yes | AI-powered coding assistant | | Node.js | Optional | v18+ for Web IDE features | | Python 3 | Optional | For Web IDE features | | GCC | Optional | For native module compilation | | Make | Optional | For build automation |

Installation

Quick Install

npm install -g @fjcunha/devflow-cli

From Source

git clone https://github.com/fjcunha/devflow-cli.git
cd devflow-cli
npm install
npm run build
npm link

Usage

Initialize DevFlow in Current Directory

devflow init

Initialize in a Specific Folder

devflow init my-project

Skip Dependency Checks

devflow init --skip-deps

Start the DevFlow Web IDE

devflow ide start

This command will:

• Clone the DevFlow repository (if not already set up)
• Install dependencies automatically
• Start the Next.js development server

Update the DevFlow Web IDE

devflow ide update

Updates the Web IDE to the latest version from the repository.

Get Help

devflow --help
devflow init --help
devflow ide --help

What Gets Installed

When you run devflow init, the following components are added to your project:

your-project/
├── .claude/
│   └── commands/
│       └── agents/          # Claude AI agent configurations
├── .devflow/
│   ├── agents/              # Agent definitions
│   ├── memory/              # Persistent memory storage
│   └── sessions/            # Session management
├── docs/                    # Documentation templates
└── .gitignore               # Updated with DevFlow entries

Development

Prerequisites

• Node.js >= 18
• npm >= 9

Setup

# Clone the repository
git clone https://github.com/fjcunha/devflow-cli.git
cd devflow-cli

# Install dependencies
npm install

# Run in development mode
npm run dev

Available Scripts

| Script | Description | |--------|-------------| | npm run build | Build for production | | npm run dev | Run in development mode | | npm test | Run tests in watch mode | | npm run test:run | Run tests once | | npm run check | Run all quality checks (types, lint, tests, audit) | | npm run fix | Auto-fix linting issues |

Project Structure

devflow-cli/
├── src/
│   ├── cli.ts              # Main CLI entry point (Commander.js)
│   ├── init.ts             # Project initialization logic
│   ├── ide.ts              # Web IDE management (start, update)
│   ├── deps.ts             # Dependency checking & OS detection
│   ├── output.ts           # Terminal output utilities
│   ├── utils.ts            # Helper functions
│   ├── postinstall.ts      # Post-install script
│   └── *.test.ts           # Test files
├── dist/                   # Compiled output
├── .github/
│   └── workflows/          # CI/CD pipelines
├── package.json
├── tsconfig.json
├── vitest.config.ts
└── biome.jsonc

Architecture

┌─────────────────────────────────────────────────────────────┐
│                        CLI Entry                            │
│                        (cli.ts)                             │
└─────────────────────────┬───────────────────────────────────┘
                          │
          ┌───────────────┼───────────────┐
          ▼               ▼               ▼
┌─────────────────┐ ┌───────────┐ ┌───────────────┐
│   Dependency    │ │   Init    │ │    Output     │
│    Checker      │ │  Logic    │ │   Utilities   │
│   (deps.ts)     │ │ (init.ts) │ │ (output.ts)   │
└─────────────────┘ └───────────┘ └───────────────┘
         │                │
         ▼                ▼
┌─────────────────┐ ┌───────────────────────────────┐
│  OS Detection   │ │     File Operations           │
│  & Install      │ │  - Clone template repo        │
│  Instructions   │ │  - Copy DevFlow components    │
└─────────────────┘ │  - Merge .gitignore           │
                    └───────────────────────────────┘

Testing

The project uses Vitest for testing with comprehensive coverage.

# Run tests in watch mode
npm test

# Run tests once
npm run test:run

# Run tests with UI
npx vitest --ui

Test Coverage

| Module | Coverage Focus | |--------|----------------| | deps.ts | OS detection, dependency checking, installation instructions | | init.ts | Project initialization, file operations, conflict handling | | ide.ts | Web IDE start/update, version checking, command execution | | output.ts | Terminal output, spinner functionality |

Code Quality

| Tool | Purpose | |------|---------| | TypeScript | Static type checking (strict mode) | | Biome | Linting and formatting | | Vitest | Unit testing | | npm audit | Security vulnerability scanning |

Run all checks:

npm run check

CI/CD

Workflows

| Workflow | Trigger | Purpose | |----------|---------|---------| | check.yaml | Pull Requests | Run type checks, linting, tests, and audit | | release.yaml | Version tags (v*..) | Build and publish to npm registries | | tag.yaml | Manual | Create version tags |

Troubleshooting

Common Issues

Ensure Git is installed and available in your system PATH:

# Check if Git is installed
git --version

# Install on Ubuntu/Debian
sudo apt install git

# Install on macOS
brew install git

Install Claude Code CLI:

# Install via npm
npm install -g @anthropic-ai/claude-code

If you encounter permission issues during global installation:

# Use sudo (Linux/macOS)
sudo npm install -g devflow-cli

# Or fix npm permissions
# https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally

If cloning the template repository fails:

1. Check your internet connection
2. Verify access to https://github.com/evolve-labs-cloud/devflow.git
3. Check if you're behind a proxy and configure Git accordingly

Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run quality checks (npm run check)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Guidelines

• Follow the existing code style (enforced by Biome)
• Write tests for new features
• Update documentation as needed
• Ensure all checks pass before submitting PR

License

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

Built with TypeScript and Commander.js

Report Bug | Request Feature