Logging & Transcripts
Relevant source files
The following files were used as context for generating this wiki page:
Logging and Transcripts within Clawdbot represent a multi-layered system designed to capture system operations, agent interactions, and session histories. The system spans from unified macOS system logs to detailed persistent execution traces in the OpenProse VM, ensuring both developers and agents have access to a reliable record of past actions and decisions.
The architecture prioritizes observability and continuity, allowing agents to "remember" prior work through memory files and enabling developers to debug the gateway using specialized CLI tools. This documentation covers the infrastructure for general system logging, specialized session transcripts, and persistent agent memory management.
System-Level Logging
Clawdbot utilizes a combination of standard output streams and platform-specific logging facilities to track the health and operations of the gateway and its various subsystems.
macOS Unified Logs
On macOS, Clawdbot integrates with the unified logging system. A dedicated helper script, ./scripts/clawlog.sh, provides the primary interface for querying these logs.
- Functionality: Supports follow/tail operations and category-based filtering.
- Requirements: Expects passwordless
sudoaccess to/usr/bin/log. - Subsystem: Logs are recorded under the Clawdbot subsystem for precise filtering.
Sources: CLAUDE.md:144-145, AGENTS.md:144-145
Gateway Output
The gateway process directs its output to specific log files depending on the environment. In typical VM or background deployments, logs are directed to /tmp/clawdbot-gateway.log.
- Verification: The command
tail -n 120 /tmp/clawdbot-gateway.logis used to verify gateway startup and health. - Debug Tools:
clawdbot logs --followallows for live debugging of gateway events.
Sources: CLAUDE.md:46-50, src/commands/status.command.ts:515
Session Transcripts & Execution Traces
In the OpenProse environment, logging evolves into "Execution Traces" and "Segments," which provide a granular record of VM operations and agent logic.
OpenProse Execution Trace (state.md)
The OpenProse VM maintains a state.md file within the .prose/runs/{run-id}/ directory. This file acts as a live transcript of the program's execution flow.
The diagram above shows the relationship between the VM, subagents, and the state tracking files.
- Annotated Code Snippets: The trace shows full history with inline status annotations like
# <-- EXECUTING,# (complete), and# [...next...]. - Visibility: It provides a view of executed code, the current position, and upcoming statements.
- Exclusivity: Only the VM writes to
state.md; subagents never modify this file.
Sources: extensions/open-prose/skills/prose/state/filesystem.md:65-125
Binding Logs
Every session output, including anonymous ones, is persisted as a binding file.
- Path:
.prose/runs/{id}/bindings/{name}.md - Anonymous Sessions: Automatically named with a zero-padded prefix (e.g.,
anon_001.md). - Structure: Includes the binding name, kind (let/const/input/output), the source code that triggered the session, and the actual result.
Sources: extensions/open-prose/skills/prose/state/filesystem.md:141-168
Persistent Agent Memory
Clawdbot agents use a specialized transcript format called "Memory" to maintain continuity across different invocations. This system differentiates between the immediate output of a task and the long-term knowledge accumulated by an agent.
Compaction vs. Summarization
A key architectural requirement for agent transcripts is compaction. Agents are instructed not to simply summarize their actions but to preserve specific, usable details for their future selves.
| Feature | Compaction Requirement |
|---|---|
| Locations | Must include specific file paths and line numbers (e.g., src/auth/login.ts:67). |
| Findings | Must record exact issues (e.g., "SQL injection risk") rather than generalizations. |
| Rationale | Decisions must include the "why" to maintain consistency across sessions. |
| Metrics | Exact numbers and thresholds (e.g., "73% coverage") must be preserved. |
Sources: extensions/open-prose/skills/prose/primitives/session.md:125-155
Transcript Segmentation
Persistent agents record their history in "Segments," which are zero-padded Markdown files (e.g., captain-001.md).
Execution flow for a persistent agent updating its historical transcripts.
memory.md: Contains the current "Understanding," "Decisions Made," and "Open Concerns."{name}-{NNN}.md: A chronological record of a specific session, including the timestamp, prompt, findings, and next steps.
Sources: extensions/open-prose/skills/prose/primitives/session.md:215-245, extensions/open-prose/skills/prose/state/filesystem.md:195-215
Memory Scoping & Storage
Transcript and memory locations are determined by the persist scope defined in the agent configuration.
| Scope | Path | Lifetime |
|---|---|---|
| Execution | .prose/runs/{run-id}/agents/{name}/ | Deleted after the specific run completes. |
| Project | .prose/agents/{name}/ | Persists across different runs within the same project. |
| User | ~/.prose/agents/{name}/ | Persists globally across all projects for that user. |
Sources: extensions/open-prose/skills/prose/state/filesystem.md:255-265, CLAUDE.md:113-114
Tooling and Observability
The Clawdbot CLI provides commands to inspect the status of sessions and logs.
Status Command
The clawdbot status command aggregates logging and transcript information into a human-readable table.
- Sessions: Displays recent sessions with their Key, Kind, Age, Model, and Token usage.
- System Events: Lists queued events that are tracked by the system.
- Memory Plugin: Shows the status of the memory/vector store (e.g., "dirty," "ok," "vector off").
Sources: src/commands/status.command.ts:400-450
Pi Session Logs
For specialized agent debugging, session logs are stored as JSONL files.
- Location:
~/.clawdbot/agents/<agentId>/sessions/*.jsonl. - Usage: These files are the primary reference for "session" data when investigating agent behavior over SSH or local terminal.
Sources: CLAUDE.md:225-228, AGENTS.md:225-228
Conclusion
The Logging & Transcripts system in Clawdbot is designed for high-fidelity reconstruction of system and agent states. By enforcing strict compaction rules for agent memory and utilizing a hierarchical file-based state for the OpenProse VM, the project ensures that execution is both traceable by developers and continuous for AI agents. This structure supports complex, long-running workflows while maintaining a clear audit trail through macOS unified logs and CLI status reports.