Debugging and Observability

When things go wrong, Recalletta 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:

~/.recalletta/log/unified.log

This log captures:

  • Hook execution events (SessionStart/End).
  • Background uploader status and errors.
  • Monitor polling events for non-hook clients.
  • API communication failures.

To follow the log in real-time:

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

The --debug Flag

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

$ recalletta --debug kb tree

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.

$ recalletta 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.

Pipeline Debugging (Attractor)

Status Artifacts

Each Attractor run creates a state directory under .attractor/runs/<run_id>/. The status.json file for each stage contains:

  • status: (pending, running, success, fail).
  • notes: A short summary of what the stage accomplished.
  • failure_reason: If the stage failed, this contains the specific error or goal-gate outcome that triggered the failure.

Validation

Before running a complex pipeline, always run the validator to find structural errors:

$ recalletta attractor validate my-pipeline.dot

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.