ZERG Logs

ZERG Logs

Stream, filter, and aggregate worker logs for debugging and monitoring.

Usage

# Show recent logs from all workers
zerg logs

# Show logs from specific worker
zerg logs 1

# Follow logs in real-time
zerg logs --follow

# Filter by log level
zerg logs --level error

# Show more lines
zerg logs --tail 200

# Output as JSON for scripting
zerg logs --json

# Aggregate structured JSONL logs across all workers
zerg logs --aggregate

# Filter to a specific task
zerg logs --task T1.1

# Show task artifacts (Claude output, verification, git diff)
zerg logs --artifacts T1.1

# Filter by execution phase and event
zerg logs --aggregate --phase verify --event verification_failed

# Time range filtering
zerg logs --aggregate --since 2026-01-28T10:00:00Z --until 2026-01-28T12:00:00Z

# Text search in messages
zerg logs --aggregate --search "failed"

CLI Flags

zerg logs [WORKER_ID] [OPTIONS]

Arguments:
  WORKER_ID              Optional worker ID to filter logs

Options:
  -f, --feature TEXT     Feature name (auto-detected)
  -n, --tail INTEGER     Number of lines to show (default: 100)
  --follow               Stream new logs continuously
  -l, --level LEVEL      Filter by log level: debug|info|warn|error
  --json                 Output raw JSON format
  --aggregate            Merge all worker JSONL logs by timestamp
  --task TEXT            Filter to specific task ID
  --artifacts TEXT       Show artifact file contents for a task
  --phase TEXT           Filter by execution phase (claim/execute/verify/commit/cleanup)
  --event TEXT           Filter by event type (task_started, task_completed, etc.)
  --since TEXT           Only entries after this ISO8601 timestamp
  --until TEXT           Only entries before this ISO8601 timestamp
  --search TEXT          Text search in messages

Log Format

Structured JSONL Format (workers/*.jsonl)

Each worker writes structured JSON lines to .zerg/logs/workers/worker-{id}.jsonl:

{"ts":"2026-01-28T10:30:45.123Z","level":"info","worker_id":0,"task_id":"T1.1","feature":"user-auth","phase":"execute","event":"task_started","message":"Task T1.1 started"}

Required fields: ts, level, message, worker_id, feature. Optional fields: task_id, phase, event, data, duration_ms.

Human-Readable Format (console output)

[10:30:45] [INFO ] W0 Task T1.1 started task_id=T1.1 phase=execute event=task_started
[10:31:12] [INFO ] W0 Verification passed task_id=T1.1 phase=verify event=verification_passed
[10:31:13] [INFO ] W0 Task T1.1 completed task_id=T1.1 event=task_completed
[10:31:45] [ERROR] W1 Task T1.3 failed task_id=T1.3 event=task_failed

JSON Output (--json)

{"ts":"2026-01-28T10:30:45.123Z","level":"info","worker_id":0,"message":"Task T1.1 started","task_id":"T1.1","phase":"execute","event":"task_started","feature":"user-auth"}

Log Levels

Execution Phases

Event Types

Log Locations

Structured JSONL Logs (new)

• Worker logs: .zerg/logs/workers/worker-{id}.jsonl
• Orchestrator log: .zerg/logs/orchestrator.jsonl

Task Artifacts

• Execution log: .zerg/logs/tasks/{TASK-ID}/execution.jsonl
• Claude output: .zerg/logs/tasks/{TASK-ID}/claude_output.txt
• Verification output: .zerg/logs/tasks/{TASK-ID}/verification_output.txt
• Git diff: .zerg/logs/tasks/{TASK-ID}/git_diff.patch

Legacy Logs

• Worker logs: .zerg/logs/worker-{id}.log

Aggregation Mode

Use --aggregate to merge all worker JSONL files by timestamp. This performs read-side aggregation (no aggregated file on disk). Combine with filters:

# All structured logs, sorted by time
zerg logs --aggregate

# Only errors across all workers
zerg logs --aggregate --level error

# Task timeline
zerg logs --task T1.1

# Failed verifications
zerg logs --aggregate --event verification_failed

# Logs from worker 2 in verify phase
zerg logs 2 --aggregate --phase verify

Task Artifacts

View captured artifacts for a specific task:

zerg logs --artifacts T1.1

This shows the contents of all artifact files:

• claude_output.txt — stdout/stderr from Claude Code
• verification_output.txt — verification command output
• git_diff.patch — changes committed
• execution.jsonl — structured event log

Streaming Mode

Use --follow for real-time log streaming (legacy .log files):

zerg logs --follow

Press Ctrl+C to stop streaming.

Task Tracking

On invocation, create a Claude Code Task to track this command:

Call TaskCreate:

• subject: "[Logs] View worker logs"
• description: "Viewing logs for {feature}. Filters: worker={worker_id}, level={level}."
• activeForm: "Viewing worker logs"

Immediately call TaskUpdate:

• taskId: (the Claude Task ID)
• status: "in_progress"

On completion, call TaskUpdate:

• taskId: (the Claude Task ID)
• status: "completed"

Integration with Other Commands

# Aggregate all errors
zerg logs --aggregate --level error

# Check why a task failed
zerg logs --task TASK-015

# View artifacts from failed task
zerg logs --artifacts TASK-015

# Monitor all workers in real-time
zerg logs --follow --level info

# Export structured logs for analysis
zerg logs --aggregate --json > logs.jsonl

# Clean up old logs
zerg cleanup --logs

Help

When --help is passed in $ARGUMENTS, display usage and exit:

/zerg:logs — Stream, filter, and aggregate worker logs for debugging and monitoring.

Flags:
  WORKER_ID              Optional worker ID to filter logs
  -f, --feature TEXT     Feature name (auto-detected)
  -n, --tail INTEGER     Number of lines to show (default: 100)
  --follow               Stream new logs continuously
  -l, --level LEVEL      Filter by log level: debug|info|warn|error
  --json                 Output raw JSON format
  --aggregate            Merge all worker JSONL logs by timestamp
  --task TEXT            Filter to specific task ID
  --artifacts TEXT       Show artifact file contents for a task
  --phase TEXT           Filter by execution phase (claim/execute/verify/commit/cleanup)
  --event TEXT           Filter by event type (task_started, task_completed, etc.)
  --since TEXT           Only entries after this ISO8601 timestamp
  --until TEXT           Only entries before this ISO8601 timestamp
  --search TEXT          Text search in messages
  --help                Show this help message