Debugging and Observability

When things go wrong, Metateam provides several layers of visibility into the internal state of agents, hooks, and the API.

Local Logs

The primary source of truth for CLI and hook behavior is the unified log file:

~/.metateam/log/unified.log

This log captures:

  • Hook execution events (SessionStart plus stale SessionEnd compatibility shims).
  • Communicator uploader status and errors.
  • Manual session upload/catch-up errors.
  • API communication failures.

To follow the log in real-time:

$ tail -f ~/.metateam/log/unified.log

The --debug Flag

Every Metateam command supports the --debug flag. This increases verbosity and prints detailed information about API requests, configuration loading, and local database operations.

$ metateam --debug kb list

Agent Observability (Crew)

The "killer feature" for debugging autonomous agents is not logs—it is direct observation.

tmux Attachment

Every crew agent runs in a dedicated tmux session. If an agent hangs or produces unexpected output, you can attach to its session to see exactly what it sees.

$ metateam crew attach <name>

While attached, you can:

  • See the raw tool calls and outputs.
  • Observe the agent "thinking" or looping.
  • Manually intervene if the agent is stuck.

Audit Trails

  • .crew/history.md: A chronological record of every summon, release, and message event in the current project context.
  • Mail-board reports: Durable markdown artifacts written by agents to .crew/mail-board/. Use these to verify if an agent reached a specific milestone or delivered a planned report.

Dashboard Telemetry

The Web dashboard provides a higher-level view of session history and knowledge totals.

  • Sessions Page: Check if your session metadata (duration, tokens, tags) was captured correctly.
  • Knowledge Page: Verify that your "important" entries are correctly flagged and scoped to the right project.