---

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

$3

``bash
npm install -g @fjcunha/devflow-cli
`

$3

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

Usage

$3

`bash
devflow init
`

$3

`bash
devflow init my-project
`

$3

`bash
devflow init --skip-deps
`

$3

`bash
devflow ide start
`

This command will:
- Clone the DevFlow repository (if not already set up)
- Install dependencies automatically
- Start the Next.js development server

$3

`bash
devflow ide update
`

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

$3

`bash
devflow --help
devflow init --help
devflow ide --help
`

$3

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

$3

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

$3

`bash


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
`

$3

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

$3

`
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
`

$3

`
┌─────────────────────────────────────────────────────────────┐
│ 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.

`bash


Run tests in watch mode

npm test

Run tests once

npm run test:run

Run tests with UI

npx vitest --ui
`

$3

| 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:

`bash
npm run check
`

CI/CD

$3

| 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

$3

Git Not Found

Ensure Git is installed and available in your system PATH:

`bash


Check if Git is installed

git --version

Install on Ubuntu/Debian

sudo apt install git

Install on macOS

brew install git
`

Claude Code Not Found

Install Claude Code CLI:

`bash


Install via npm


npm install -g @anthropic-ai/claude-code
`

Permission Denied

If you encounter permission issues during global installation:

`bash


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

`

Network Issues

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

$3

- 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.

---