Skip to main content

​
Why AI Agents Need Logs

When debugging or developing multi-container applications, AI agents need access to real-time logs from all running services. docker-agent-tail provides structured JSONL log output with normalized levels that AI agents can easily parse and analyze.

​
Claude Code Integration

Use docker-agent-tail to provide real-time logs to Claude Code:
1

Set up agent config

Run init to create CLAUDE.md instructions, .mcp.json, and agent-specific skill/rule files:
docker-agent-tail init
2

Start collecting logs

In your terminal, start docker-agent-tail to write logs:
docker-agent-tail --all --follow
3

Share logs with Claude Code

Ask Claude Code to read the latest logs:
Read the logs in logs/latest/combined.jsonl and help me debug the errors
4

Debug with context

Claude Code can now see what’s happening in your containers and help debug issues.

​
Cursor Integration

Similar to Claude Code, you can use docker-agent-tail with Cursor: 
# In your workspace, start collecting logs
docker-agent-tail --all --follow

# Cursor will pick up the logs/ directory in your workspace
# It can then analyze logs/latest/combined.jsonl for insights

​
Best Practices

Filter Noisy Logs

Use --exclude and --mute to reduce noise in logs shared with AI agents. This helps them focus on meaningful errors and warnings.
docker-agent-tail --all --exclude 'health' --mute 'worker'

Query Logs with lnav

Agents can use lnav -n -c to run SQL queries against logs without an interactive terminal.
lnav -n -c ';SELECT container, level, count(*) FROM log GROUP BY container, level' logs/latest/combined.jsonl

Recent Logs Only

Use --since to only capture recent logs, reducing file size and improving agent performance.
docker-agent-tail --all --since 5m

Specific Services

Tail only the containers relevant to debugging to avoid overwhelming the agent with irrelevant logs.
docker-agent-tail --names api,web --follow

​
Log Format for Agents

docker-agent-tail writes structured JSONL logs designed for easy parsing by AI agents: 
{"ts":"2026-03-04T10:30:01.789Z","container":"api","stream":"stdout","message":"GET /api/users 200 12ms"}
{"ts":"2026-03-04T10:30:02.145Z","container":"web","stream":"stderr","message":"Warning: slow query detected"}
Each log entry includes:
  • ts: ISO 8601 timestamp for correlating events across containers
  • container: Container name for filtering
  • stream: stdout or stderr
  • level: Normalized log level (when detected from structured JSON)
  • message: Log content (plain text) or original fields (structured JSON)

​
Example: Debugging a Failing Deploy

Here’s a typical workflow for using docker-agent-tail with an AI agent:
1

You notice errors

Your web service is crashing on startup. You ask the AI agent for help:“My web service is crashing on startup. Can you help me debug?”
2

Start collecting logs

docker-agent-tail --all --follow
3

Share with the AI agent

“I’ve got logs streaming to logs/latest/. Can you read logs/latest/combined.jsonl and tell me what’s going wrong?”
4

AI agent analyzes

The agent reads combined.jsonl and per-container .jsonl files, correlates errors by timestamp and level, identifies the root cause, and suggests fixes.
For more details on CLI options, see the CLI reference. For interactive log analysis, see the lnav integration.