> ## Documentation Index
> Fetch the complete documentation index at: https://docker-agent-tail.michaelscotello.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Using with AI Agents

> Learn how to integrate docker-agent-tail with AI coding agents like Claude Code and Cursor.

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

<Steps>
  <Step title="Set up agent config">
    Run `init` to create CLAUDE.md instructions, .mcp.json, and agent-specific skill/rule files:

    ```bash theme={null}
    docker-agent-tail init
    ```
  </Step>

  <Step title="Start collecting logs">
    In your terminal, start docker-agent-tail to write logs:

    ```bash theme={null}
    docker-agent-tail --all --follow
    ```
  </Step>

  <Step title="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
    ```
  </Step>

  <Step title="Debug with context">
    Claude Code can now see what's happening in your containers and help debug issues.
  </Step>
</Steps>

## Cursor Integration

Similar to Claude Code, you can use docker-agent-tail with Cursor:

```bash theme={null}
# 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

<CardGroup cols={2}>
  <Card title="Filter Noisy Logs" icon="filter">
    Use `--exclude` and `--mute` to reduce noise in logs shared with AI agents. This helps them focus on meaningful errors and warnings.

    ```bash theme={null}
    docker-agent-tail --all --exclude 'health' --mute 'worker'
    ```
  </Card>

  <Card title="Query Logs with lnav" icon="magnifying-glass">
    Agents can use `lnav -n -c` to run SQL queries against logs without an interactive terminal.

    ```bash theme={null}
    lnav -n -c ';SELECT container, level, count(*) FROM log GROUP BY container, level' logs/latest/combined.jsonl
    ```
  </Card>

  <Card title="Recent Logs Only" icon="clock">
    Use `--since` to only capture recent logs, reducing file size and improving agent performance.

    ```bash theme={null}
    docker-agent-tail --all --since 5m
    ```
  </Card>

  <Card title="Specific Services" icon="bullseye">
    Tail only the containers relevant to debugging to avoid overwhelming the agent with irrelevant logs.

    ```bash theme={null}
    docker-agent-tail --names api,web --follow
    ```
  </Card>
</CardGroup>

## Log Format for Agents

docker-agent-tail writes structured JSONL logs designed for easy parsing by AI agents:

<CodeGroup>
  ```json Plain text container output theme={null}
  {"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"}
  ```

  ```json Structured JSON (merged + level normalized) theme={null}
  {"ts":"2026-03-04T10:30:01.789Z","container":"api","stream":"stdout","level":"info","msg":"request completed","status":200}
  {"ts":"2026-03-04T10:30:02.145Z","container":"mongodb","stream":"stdout","level":"warning","msg":"Slow operation","durationMillis":1200}
  ```
</CodeGroup>

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:

<Steps>
  <Step title="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?"*
  </Step>

  <Step title="Start collecting logs">
    ```bash theme={null}
    docker-agent-tail --all --follow
    ```
  </Step>

  <Step title="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?"*
  </Step>

  <Step title="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.
  </Step>
</Steps>

***

For more details on CLI options, see the [CLI reference](/cli-reference). For interactive log analysis, see the [lnav integration](/lnav).