Devir - Dev Runner CLI

A terminal UI for managing multiple dev services with colored logs, filtering, and MCP integration.

Features

• Bubble Tea TUI - Interactive terminal UI with tabs, viewport, and status bar

• Colored Logs - Each service has its own color for easy identification

• Service Types - Long-running, oneshot, interval, and HTTP request services

• Custom Icons - Emoji icons for services with dynamic status updates

• Service Filtering - View logs from all services or filter by specific service

• Search - Filter logs by text pattern

• Port Management - Detects ports in use and offers to kill them

• MCP Server - Integrate with Claude Code via Model Context Protocol

• Daemon Mode - Multiple TUI/MCP clients can connect to the same services

• Chrome DevTools Extension - View logs in browser DevTools panel

Related MCP server: devctl-mcp

Installation

Quick Install (Recommended)

curl -fsSL https://raw.githubusercontent.com/productdevbook/devir/master/install.sh | bash

Homebrew (macOS/Linux)

brew install productdevbook/tap/devir

Manual Download

Download from Releases

From Source

go install github.com/productdevbook/devir@latest

Or build manually:

git clone https://github.com/productdevbook/devir.git
cd devir
make build

Quick Start

# Create devir.yaml (auto-detects project structure)
devir init

# Start services
devir

Usage

Initialize Project

devir init

This creates a devir.yaml file by detecting your project structure:

• Node.js - Detects package.json with dev script

• Go - Detects go.mod

• Rust - Detects Cargo.toml

• Python - Detects requirements.txt or pyproject.toml

• Monorepos - Scans apps/*, packages/*, services/*

TUI Mode (default)

# Start all default services
devir

# Start specific services
devir admin server

# With filters
devir --filter "error"
devir --exclude "hmr"

MCP Server Mode

devir --mcp

Daemon Mode

Devir uses a Unix socket daemon, allowing multiple clients (TUI or MCP) to connect to the same running services:

# Terminal 1: Start TUI (daemon starts automatically)
devir

# Terminal 2: Connect another TUI (same services, same logs)
devir

# Terminal 3: Connect via MCP (Claude Code controls same services)
devir --mcp

All clients share the same daemon and see the same logs in real-time. When Claude Code restarts a service, you'll see it immediately in your TUI.

Keyboard Shortcuts

Configuration

Create devir.yaml in your project root:

services:
  admin:
    dir: apps/admin
    cmd: bun run dev
    port: 3000
    color: blue

  server:
    dir: server
    cmd: bun run dev
    port: 3123
    color: magenta

defaults:
  - admin
  - server

Service Options

Service Types

Devir supports 4 different service types:

service (default)

Long-running process. For web servers, APIs, etc.

web:
  dir: apps/web
  cmd: npm run dev
  port: 3000
  icon: "🌐"
  color: blue

oneshot

Run once and exit. For migrations, setup scripts, etc.

migrate:
  type: oneshot
  dir: .
  cmd: npm run migrate
  icon: "⚙️"
  color: yellow

interval

Run periodically. For health checks, cleanup jobs, etc.

health:
  type: interval
  interval: 5s
  dir: .
  cmd: bash health.sh
  icon: "💓"
  color: green

http

Make HTTP requests. For API calls, webhooks, etc.

api-check:
  type: http
  url: https://api.example.com/health
  method: GET
  icon: "📡"
  color: magenta

With POST body:

notify:
  type: http
  url: https://api.example.com/webhook
  method: POST
  body: '{"event": "started"}'
  headers:
    - "Authorization: Bearer token123"
  icon: "📤"
  color: cyan

Status Symbols

Dynamic Status

Services can dynamically update their icon and status by writing to .devir-status file in their directory:

# Simple - just icon
echo "🟢" > .devir-status

# JSON - icon + message
echo '{"icon": "🟢", "message": "All OK"}' > .devir-status

# JSON - full control
echo '{"icon": "🔴", "color": "red", "status": "failed", "message": "DB down!"}' > .devir-status

Dynamic Status Fields

Example: Health Check with Dynamic Status

#!/bin/bash
# health.sh
if curl -sf http://localhost:3000/health >/dev/null 2>&1; then
    echo '{"icon": "🟢", "message": "All systems operational"}' > .devir-status
    echo "Health OK"
else
    echo '{"icon": "🔴", "color": "red", "message": "Service down!"}' > .devir-status
    echo "Health FAIL"
fi

MCP Integration

Add to your project's .mcp.json:

{
  "mcpServers": {
    "devir": {
      "command": "devir",
      "args": ["--mcp"],
      "cwd": "/path/to/project"
    }
  }
}

Note: Set cwd to the directory containing your devir.yaml. The daemon socket is unique per project directory, so multiple projects can run independently.

Available MCP Tools

MCP Status Response Example

{
  "services": [
    {
      "name": "web",
      "running": true,
      "port": 3000,
      "type": "service",
      "status": "running",
      "icon": "🌐"
    },
    {
      "name": "health",
      "running": true,
      "type": "interval",
      "status": "waiting",
      "icon": "🟢",
      "message": "All systems operational",
      "runCount": 5
    }
  ]
}

Chrome DevTools Extension

View devir logs directly in Chrome DevTools. The extension connects via WebSocket to the devir daemon.

Installation

Download from Releases and extract devir-extension.zip.

1. Open chrome://extensions

2. Enable "Developer mode"

3. Click "Load unpacked"

4. Select the extracted extension folder

Usage

1. Start devir with WebSocket enabled (default port 9222):

   devir

2. Open Chrome DevTools (F12) on any page

3. Click the "Devir" tab

Features

• Real-time logs - Logs stream as they happen

• Service tabs - Filter logs by service

• Level filtering - Filter by error, warn, info, debug

• Search - Filter logs by text

• Service controls - Start, Stop, Restart services directly from DevTools

• Status indicators - Green/yellow/red dots show service status

WebSocket Port

By default, devir starts WebSocket server on port 9222. To use a different port:

devir --ws-port 9333

Note: If you change the port, you'll need to modify the extension's useWebSocket.ts to match.

Development

# Build
make build

# Build for all platforms
make build-all

# Run tests
make test

# Lint
make lint

Dependencies

• Bubble Tea - TUI framework

• Lip Gloss - Styling

• MCP Go SDK - MCP server

License

MIT