Devir

Devir - Dev Runner CLI

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

[](https://github.com/productdevbook/devir/actions/workflows/ci.yml) [](https://github.com/productdevbook/devir/releases) [](https://goreportcard.com/report/github.com/productdevbook/devir) [](https://opensource.org/licenses/MIT) [](https://go.dev/)

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

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

| Platform | Download | |----------|----------| | macOS (Apple Silicon) | devir-darwin-arm64.tar.gz | | macOS (Intel) | devir-darwin-amd64.tar.gz | | Linux (x64) | devir-linux-amd64.tar.gz | | Linux (ARM64) | devir-linux-arm64.tar.gz | | Windows (x64) | devir-windows-amd64.zip |

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

| Key | Action | |-----|--------| | Tab | Cycle through services | | 1-9 | Select specific service | | a | Show all services | | / | Search logs | | c | Copy logs to clipboard | | r | Restart current service | | j/k | Scroll up/down | | q | Quit |

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

| Field | Description | |-------|-------------| | dir | Working directory (relative to config file) | | cmd | Command to run | | port | Port number (for status display) | | color | Log prefix color: blue, green, yellow, magenta, cyan, red, white | | icon | Custom emoji/icon for the service | | type | Service type: service (default), oneshot, interval, http | | interval | Run interval for interval type (e.g., 5s, 1m) | | url | URL for http type | | method | HTTP method for http type (default: GET) | | body | Request body for http type | | headers | Custom headers for http type |

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

| Symbol | Status | Description | |:------:|--------|-------------| | ● | Running | Service is active | | ✓ | Completed | Oneshot/HTTP completed successfully | | ✗ | Failed | Service failed | | ◐ | Waiting | Interval service waiting for next run | | ○ | Stopped | Service is stopped |

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

| Field | Description | |-------|-------------| | icon | Override icon with emoji or short text | | color | Override service color | | status | Override status: running, completed, failed, waiting | | message | Status message (shown in MCP response) |

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

| Tool | Description | |------|-------------| | devir_start | Start services | | devir_stop | Stop all services | | devir_status | Get service status (includes type, icon, message) | | devir_logs | Get recent logs | | devir_restart | Restart a service | | devir_check_ports | Check if ports are in use | | devir_kill_ports | Kill processes on ports |

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

``bash devir ``

1. Open Chrome DevTools (F12) on any page
2. 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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: productdevbook
• Source: productdevbook/devir
• License: MIT

Install and usage instructions live in the source repository linked above.