docker-tui: Instructions file for Claude Code

CLAUDE.md

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

Project Overview

Docker TUI is a Terminal User Interface application for managing Docker containers, built with Go and Bubbletea (The Elm Architecture framework). It provides real-time container monitoring, multi-select operations, CPU usage tracking, live log streaming with colored backgrounds, regex-based filtering, and a demo mode for presentations.

Build and Development Commands

# Build for current platform
make build              # Creates ./docker-tui binary

# Run without building
make run               # Executes: go run ./src

# Run tests
make test              # Executes: go test -v ./src/...

# Format code
make fmt               # Executes: go fmt ./src/...

# Clean artifacts
make clean             # Removes ./docker-tui and dist/

# Cross-platform builds
make dist-all          # Builds for Linux (amd64/arm64), macOS (amd64/arm64), Windows

Architecture: Elm Architecture (Bubbletea)

The application follows Bubbletea's Elm Architecture pattern with three core components:

Model (state)

Located in src/model.go, the model struct contains all application state:

• Docker client and container list
• Selection state (selected map, cursor position)
• View mode (listView, logsView, confirmView, exitConfirmView, mcpLogsView)
• Processing state for async operations
• CPU statistics tracking (current + 10-value history)
• CPUStatsCache instance (cpuCache) for instant MCP responses (shared with MCPServer)
• LogBroker instance (logBroker) for centralized log streaming management
• RateTracker instance (rateTracker) for L/S (lines/second) monitoring
• BufferConsumer instance (bufferConsumer) for logs view circular buffering
• MCPServer instance (mcpServer) for Claude Desktop integration
• Filter state (filterMode, filterInput, filterActive, filterRegex, filterIsRegex)
• Demo mode flag (demoMode) for hiding container name prefixes
• Closing flag (closing atomic.Bool) for graceful shutdown coordination