Skip to content

CLAUDE.md

Latest commit

 

History

History
73 lines (56 loc) · 2.45 KB

CLAUDE.md

File metadata and controls

73 lines (56 loc) · 2.45 KB

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

make build        # Build binary to ./devir
make build-all    # Build for all platforms (dist/)
make test         # Run tests
make lint         # Run golangci-lint
make install      # Build and copy to /usr/local/bin
make clean        # Remove build artifacts

Architecture

Devir is a terminal UI for managing multiple dev services. Written in Go using Bubble Tea TUI framework.

Core Components

cmd/devir/main.go     # Entry point, CLI flags, mode selection (TUI vs MCP)
internal/
  config/             # YAML config loading, service validation
  types/              # Shared types (LogLine, LogEntry, ServiceInfo)
  runner/             # Service lifecycle management, log processing
  tui/                # Bubble Tea model, view rendering, keyboard handling
  mcp/                # MCP server for Claude Code integration

Key Patterns

Runner (internal/runner/runner.go):

  • Manages service processes with platform-specific handling (Unix/Windows)
  • Channels for log streaming: LogChan (simple mode), LogEntryChan (TUI mode)
  • Log filtering via compiled regex (filter, exclude patterns)
  • Port detection and process killing via process_unix.go/process_windows.go

TUI Model (internal/tui/):

  • Bubble Tea architecture: Model → Update → View cycle
  • Tab-based service filtering (activeTab: -1=all, 0+=specific)
  • Auto-scroll with manual override on user scroll
  • 50ms tick for log collection

MCP Server (internal/mcp/mcp.go):

  • Exposes 7 tools: devir_start, devir_stop, devir_status, devir_logs, devir_restart, devir_check_ports, devir_kill_ports
  • Uses go-sdk/mcp with stdio transport
  • Same runner infrastructure as TUI mode

Configuration

Config file: devir.yaml (searched in current dir and parents)

services:
  name:
    dir: relative/path    # Working directory
    cmd: command to run   # Command to execute
    port: 3000            # Port for status display
    color: blue           # Log prefix color

defaults:
  - name                  # Services to start by default

Dependencies

  • github.com/charmbracelet/bubbletea - TUI framework
  • github.com/charmbracelet/bubbles - TUI components (viewport, textinput)
  • github.com/charmbracelet/lipgloss - Styling
  • github.com/modelcontextprotocol/go-sdk - MCP server
  • gopkg.in/yaml.v3 - Config parsing