docker-agent-tail

docker-agent-tail

CLI tool that auto-discovers Docker containers, tails their logs, and writes structured files optimized for AI coding agents.

Features

• Auto-discover containers — Tail all containers, specific by name, or from docker-compose projects
• Smart log formatting — Structured output with timestamps and container names, optimized for AI agents
• Flexible filtering — Exclude containers and mute streams from terminal output while keeping log files
• Follow restarts — Automatically reattach to containers when they restart
• Cross-platform — Runs on macOS (Intel/ARM) and Linux (x86_64/ARM64)

Quick Install

Homebrew

brew install Mscotello/docker-agent-tail/docker-agent-tail

From GitHub Releases

# Direct download and install
curl -sSL https://github.com/Mscotello/docker-agent-tail/releases/latest/download/install.sh | bash

Go Install

go install github.com/Mscotello/docker-agent-tail@latest

Quick Start

Tail all running containers:

docker-agent-tail --all

Tail specific containers:

docker-agent-tail --names api,web,db

Tail containers from a docker-compose project:

docker-agent-tail --compose

Tail with filtering:

docker-agent-tail --all \
  --exclude "healthcheck|debug" \
  --mute "verbose-service" \
  --output ./logs

Usage

docker-agent-tail [flags]

Flags:
  -a, --all                   Tail all running containers
  -n, --names strings         Explicit container names (comma-separated)
  -c, --compose               Auto-discover from compose project
  -f, --follow                Reattach on restart (default: true)
  -e, --exclude strings       Regex patterns to exclude containers
  -m, --mute strings          Hide from terminal, still write to file
  -o, --output string         Output directory (default: "./logs")
  -s, --since string          Start from N ago (e.g., "5m", "1h")
  -j, --json                  JSON lines output
      --no-color              Disable terminal colors
  -h, --help                  Show this help message

Log Output Format

Per-container logs (<container_name>.log):

[2026-03-04T10:30:01.789Z] [stdout] GET /api/users 200 12ms
[2026-03-04T10:30:02.456Z] [stderr] Connection error: timeout

Combined logs (combined.log):

[2026-03-04T10:30:01.789Z] [api    ] [stdout] GET /api/users 200 12ms
[2026-03-04T10:30:02.456Z] [web    ] [stderr] Connection error: timeout

• ISO 8601 timestamps with millisecond precision
• Fixed-width container name column for easy alignment
• Stream type ([stdout]/[stderr]) always included

Documentation

Full documentation available at docker-agent-tail.michaelscotello.com

Development

# Build
make build

# Test
make test

# Lint
make lint

# Test release (no publish)
make release-snapshot

Requirements

• Docker daemon running and accessible
• Docker log driver must be json-file or journald
• Go 1.25+ (for building from source)

License

MIT License — see LICENSE for details.