iFlow CLI Development

A comprehensive development skill for the iFlow CLI - a powerful AI assistant that runs in the terminal. This monorepo project uses TypeScript, Node.js, and React (via Ink) with a plugin-based architecture.

What This Skill Does

Guides you through developing, extending, and contributing to the iFlow CLI codebase. This includes:

Project Structure

The iFlow CLI monorepo consists of three main packages:

1. **packages/cli** - Command-line interface with terminal UI (React/Ink)

2. **packages/core** - Core AI agent orchestration, tools, and MCP integration

3. **packages/vscode-ide-companion** - VS Code extension for editor integration

Development Instructions

Initial Setup

1. **Clone and install dependencies**

- Ensure Node.js ≥20 is installed

- Run `npm install` to install all workspace dependencies

- Verify installation with `npm run build`

2. **Understand the architecture**

- Review `docs/architecture/overview.md` for component interactions

- The project uses layered architecture: Core → CLI → Integration

- Tools extend `BaseTool`, agents orchestrate via the task system

- MCP servers provide dynamic tool discovery

Building the Project

**Standard build (all packages):**

```bash

npm install && npm run build

```

**Bundled release build:**

```bash

npm run release:version [version]

npm pack

```

The bundle script generates the final CLI artifact in `bundle/` directory.

Testing

**Unit tests for CLI package:**

```bash

npm run build --workspaces && npm run typecheck --workspace=@iflow-ai/iflow-cli && npm run test:ci --workspace=@iflow-ai/iflow-cli

```

**Unit tests for core package:**

```bash

npm run build --workspaces && npm run typecheck --workspace=@iflow-ai/iflow-cli-core && npm run test:ci --workspace=@iflow-ai/iflow-cli-core

```

**Integration tests with different sandbox modes:**

```bash

npm run test:integration:sandbox:none # No sandbox

npm run test:integration:sandbox:docker # Docker sandbox

npm run test:integration:sandbox:podman # Podman sandbox

```

**End-to-end tests:**

```bash

npm run test:e2e

```

**Code quality checks:**

```bash

npm run lint # ESLint check

npm run lint:fix # Auto-fix linting issues

npm run format # Prettier formatting

npm run typecheck # TypeScript type checking

```

Adding a New Tool

1. Create tool file in `packages/core/src/tools/my-tool.ts`

2. Extend `BaseTool` class:

```typescript

export class MyTool extends BaseTool<MyParams, ToolResult> {

constructor() {

super('my_tool', 'My Tool', 'Description for the AI', Icon.Hammer);

}

// Implement parameter schema, validation, execution

}

```

3. Register in `packages/core/src/tools/tools.ts` by adding to `coreTools` array

4. Write unit tests in `my-tool.test.ts` following existing patterns

5. Update documentation if the tool affects user-facing behavior

Reference: `docs/architecture/tool-system-design.md` and `docs/core/tools-api.md`

Adding a New Agent Type

1. Define agent metadata in `packages/core/src/tools/task/agentRegistry.ts` under `AGENT_DEFINITIONS`

2. Specify allowed tools, MCP servers, and execution constraints

3. The `task` tool automatically handles lifecycle, parallel execution, and results

4. Test the agent with integration tests

Adding a New CLI Command

1. Create command definition in `packages/cli/src/commands/my-command.ts`

2. Register in `packages/cli/src/commands/commands.ts`

3. Implement using existing CLI services and UI components

4. Add command documentation to `docs/cli/commands.md`

Integrating an MCP Server

1. Configure in `~/.iflow/settings.json`:

```json

"mcpServers": {

"my_server": {

"command": "npx",

"args": ["-y", "my-mcp-server"]

}

}

```

2. Tools are auto-discovered with prefix: `my_server__tool_name`

3. Reference: `docs/architecture/mcp-integration-guide.md`

Development Workflow

**Feature development process:**

1. Explore codebase using `$explore-agent "How is X organized?"`

2. Create feature branch from `main`

3. Implement changes following TypeScript strict mode and existing patterns

4. Run tests locally (unit + integration + typecheck)

5. Update documentation for user-facing changes

6. Submit PR with clear description

**Code review checklist:**

**Performance profiling:**

Code Style Requirements

Important Constraints

Example Usage

**Exploring the codebase:**

```bash

$explore-agent "How does the tool registration system work?"

```

**Building and testing a new feature:**

```bash

After implementing new tool in packages/core/src/tools/

npm run build

npm run typecheck

npm run test:ci --workspace=@iflow-ai/iflow-cli-core

npm run test:integration:sandbox:none

```

**Debugging with telemetry:**

```bash

DEBUG=true npx iflow-cli

```

Key Documentation References