@compilr-dev/cli

      \|/
    ╭══════════╮     ___  ___  _ __ ___  _ __ (_) |_ __
    ║'  ▐▌  ▐▌ │    / __|/ _ \| '_ ` _ \| '_ \| | | '__|
    ║          │   | (__| (_) | | | | | | |_) | | | |
    ╰─═──────═─╯    \___|\___/|_| |_| |_| .__/|_|_|_|
      \________\                        | | .dev
                                        |_| CLI

AI-powered coding assistant for your terminal

[!WARNING] This package is in beta. APIs may change between minor versions.

Overview

A structured AI coding assistant that brings discipline to AI-assisted development. Supports 9 LLM providers, multi-agent teams, project workflows, and 25 interactive tutorials -- all in your terminal.

Stop vibe coding. Start building.

Quick Start

# Install globally
npm install -g @compilr-dev/cli

# Start the CLI
compilr

# Set your API key (interactive prompt on first run)
# Or use /keys inside the CLI

Features

Multi-LLM Support (9 Providers)

Use your preferred AI provider with three tiers per provider (Fast / Balanced / Powerful):

| Provider | Models | API Key | |----------|--------|---------| | Claude | Haiku, Sonnet, Opus | ANTHROPIC_API_KEY | | OpenAI | GPT-4o-mini, GPT-4o, o1 | OPENAI_API_KEY | | Gemini | Flash, Pro, Ultra | GOOGLE_API_KEY | | Ollama | Any local model | None (local) | | Together AI | Open-source models | TOGETHER_API_KEY | | Groq | Fast inference | GROQ_API_KEY | | Fireworks | Open-source models | FIREWORKS_API_KEY | | Perplexity | Search-augmented | PERPLEXITY_API_KEY | | OpenRouter | Multi-provider | OPENROUTER_API_KEY |

Switch models anytime with /model -- a visual overlay with provider tabs, model cycling, and connection testing.

Project Workflows

The CLI guides you through structured development:

| Command | Description | |---------|-------------| | /new | Create a project with guided 8-step wizard | | /design | AI-driven requirements gathering (creates PRD + backlog) | | /sketch | Quick 6-question project outline | | /prd | Update the Product Requirements Document | | /arch | Create architecture documentation (ADR, diagrams, data model, API) | | /scaffold | Generate base project structure (folders, config, dependencies) | | /build | Implement a backlog item end-to-end | | /backlog | Visual backlog management with filtering and search | | /docs | Browse and edit all project documents | | /workflow | Project status, metrics, and actions |

Multi-Agent Teams

Specialized AI agents with different expertise, tools, and model tiers:

$arch    Architect - System design, patterns, tech decisions
$dev     Developer - Implementation, coding, debugging
$qa      QA Engineer - Testing, quality, code review
$pm      PM - Planning, task tracking, estimation
$ops     DevOps - Deployment, CI/CD, infrastructure
$docs    Technical Writer - Documentation, guides
$ba      Business Analyst - Requirements, metrics

• $agent message -- switch to an agent and send a message
• $agent message & -- run in background (non-blocking)
• /team -- visual team management overlay
• /bg / /fg / /kill -- manage background agents
• /filter -- filter conversation by agent
• Custom agents -- 4-step creation wizard with tool profiles

Context Management

• Auto-compaction -- automatically compresses old messages when context fills up
• Anchors (/anchors) -- persistent notes that survive compaction and sessions
• Token tracking (/context, /tokens) -- real-time context window visualization
• Session restore -- pick up where you left off
• COMPILR.md -- project-specific instructions loaded automatically

418 Terminal Themes

Choose from 418 themes with live preview via /config > Theme. Curated favorites plus browsing by Dark/Light.

Permission System

Fine-grained control over what the AI can do:

• Permission levels -- always, session, once, deny
• Wildcard rules -- git_* matches all git tools
• Permission modes -- Normal, Plan, Auto-accept
• Safety settings -- delete protection, CWD mismatch warnings
• /permissions -- visual overlay for managing rules and grants

Interactive Tutorials

25 tutorials across 5 tabs, accessible via /tutorial:

| Tab | Topics | |-----|--------| | Basics | Welcome, First Project, First Conversation, Navigation | | Projects | New Project, Import, Managing, Sessions, Anchors | | Plan & Build | Design, Sketch, Backlog, PRD, Arch, Docs, Scaffold, Build | | Teams | Overview, Working with Agents, Background Execution, Tasks | | Config | Model Selection, Settings, Context Management, Permissions |

Commands Reference

Project Management

| Command | Description | |---------|-------------| | /new | Create or import a project | | /projects | Switch between projects | | /workflow | Project status and actions | | /backlog | Manage work items |

Development

| Command | Description | |---------|-------------| | /design | Requirements gathering | | /sketch | Quick project outline | | /prd | Update PRD | | /arch | Architecture documentation | | /scaffold | Generate project structure | | /build | Implement backlog items | | /docs | Browse project documents |

Teams

| Command | Description | |---------|-------------| | /team | Team management overlay | | /bg | View background agents | | /fg | Bring agent to foreground | | /kill | Terminate background agent | | /pending | View pending requests | | /filter | Filter conversation by agent |

Configuration

| Command | Description | |---------|-------------| | /config | Settings (4 tabs: Status, Config, Environment, Usage) | | /model | Select AI model and provider | | /permissions | Manage tool permissions | | /keys | Manage API keys | | /anchors | Persistent notes |

Context & Session

| Command | Description | |---------|-------------| | /context | Context window usage | | /tokens | Token breakdown | | /compact | Compress conversation | | /status | Session overview | | /export | Save conversation to markdown | | /tutorial | Interactive guides | | /help | All commands | | /clear | Clear screen | | /exit | Exit the CLI |

Input Features

| Feature | Syntax | |---------|--------| | Slash commands | /help, /build REQ-003 | | File references | @src/index.ts (with Tab autocomplete) | | Agent switching | $arch, $dev fix the bug | | Background exec | $qa review this & | | Tab completion | Commands, files, and agents | | Esc | Cancel running operation |

Configuration

API Keys

Option 1: Use /keys command (recommended)

Run /keys inside the CLI to securely store your API keys. Keys are encrypted and stored locally in ~/.compilr-dev/credentials.enc.

Option 2: Environment variables

export ANTHROPIC_API_KEY="sk-ant-..."   # Claude
export OPENAI_API_KEY="sk-..."          # OpenAI
export GOOGLE_API_KEY="..."             # Google Gemini
# Ollama: no key needed, just run `ollama serve`

Environment variables take priority over stored keys.

Project Configuration

Create a COMPILR.md file in your project root to provide context:

# COMPILR.md

## Project Overview
This is a React application using TypeScript...

## Coding Standards
- Use functional components
- Prefer hooks over class components

The CLI automatically loads this file at startup.

Settings

All settings available via /config:

| Setting | Options | |---------|---------| | Auto-compact | true / false | | Permission mode | Normal / Plan / Accept edits / Don't ask | | Theme | 418 terminal themes | | Model | Per-provider tier selection | | Startup behavior | Show menu / Direct to REPL | | Session restore | Auto / Ask / Fresh | | Mascot | 13 expressions + Random / None |

Requirements

• Node.js 20 or higher
• API Key for your chosen provider (except Ollama)
• Platform: macOS, Linux, or Windows via WSL2

Windows Users

The CLI requires a Unix-like shell environment. On Windows, use WSL2 (Windows Subsystem for Linux):

# 1. Install WSL2 (run in PowerShell as Administrator)
wsl --install

# 2. Open your WSL terminal, then install Node.js 20+
#    (see https://nodejs.org for instructions)

# 3. Install the CLI inside WSL
npm install -g @compilr-dev/cli

# 4. Start coding
compilr

VS Code works seamlessly with WSL via the WSL extension -- open your project in VS Code, connect to WSL, and use the integrated terminal.

Built With

• @compilr-dev/agents - Multi-LLM agent framework
• @compilr-dev/agents-coding - Coding-specific tools

Links

• Website
• npm Package
• Report Issues

License

FSL-1.1-MIT - See LICENSE for details. Converts to MIT after 2 years per version.

[^_^] Built with @compilr-dev/agents