tomevault-io Runtime Activity Logger
Log key activities to .claude/logs/activity.log using bash as you work. This creates a trace of agent reasoning and actions analogous to info-level logging in deterministic code.
Setup
Before starting any task, ensure the log directory exists:
mkdir -p .claude/logs
Log Format
Use this consistent format for all log entries:
echo "[$(date -Iseconds)] [LEVEL] phase: message" >> .claude/logs/activity.log
Log Levels
| Level | Use For |
|---|---|
INFO |
Normal operations, progress updates, decisions |
DEBUG |
Detailed technical information when troubleshooting |
WARN |
Unexpected situations that don't block progress |
ERROR |
Failures that affect task completion |
When to Log
Task Lifecycle
- Task start: Log the goal and planned approach
- Task completion: Log summary, outcome, and any artifacts created
Tool Usage
- Before significant tool use: Log what tool and why
- After tool use: Log outcome (success/failure, key findings)
Decision Points
- Architectural choices: Log reasoning for design decisions
- Branch points: Log why one approach was chosen over alternatives
- Assumptions: Log any assumptions being made
Subagent Activity
- Delegation: Log task being delegated and to which subagent
- Completion: Log subagent results when they return
Examples
Starting a Task
echo "[$(date -Iseconds)] [INFO] start: Beginning refactoring task for payment module" >> .claude/logs/activity.log
echo "[$(date -Iseconds)] [INFO] planning: Will analyze current structure, identify patterns, then apply Strategy pattern" >> .claude/logs/activity.log
Tool Usage
echo "[$(date -Iseconds)] [INFO] tool: Reading src/payments/processor.py to understand current implementation" >> .claude/logs/activity.log
echo "[$(date -Iseconds)] [INFO] tool-result: Found 3 payment types with duplicated validation logic" >> .claude/logs/activity.log
Decision Points
echo "[$(date -Iseconds)] [INFO] decision: Using Strategy pattern - cleaner than inheritance for 3 payment types" >> .claude/logs/activity.log
echo "[$(date -Iseconds)] [INFO] decision: Keeping backward compatibility by wrapping legacy interface" >> .claude/logs/activity.log
Subagent Delegation
echo "[$(date -Iseconds)] [INFO] delegate: Spawning test-writer subagent for unit test coverage" >> .claude/logs/activity.log
echo "[$(date -Iseconds)] [INFO] delegate-complete: test-writer created 12 unit tests, all passing" >> .claude/logs/activity.log
Warnings and Errors
echo "[$(date -Iseconds)] [WARN] Found deprecated API usage in line 142, will need migration" >> .claude/logs/activity.log
echo "[$(date -Iseconds)] [ERROR] Build failed: missing dependency 'stripe-sdk', attempting to resolve" >> .claude/logs/activity.log
Task Completion
echo "[$(date -Iseconds)] [INFO] complete: Refactoring finished - 3 files modified, 12 tests added" >> .claude/logs/activity.log
echo "[$(date -Iseconds)] [INFO] artifacts: Created src/payments/strategies/*.py, updated tests/test_payments.py" >> .claude/logs/activity.log
Log File Management
Viewing Logs in Real-Time
tail -f .claude/logs/activity.log
Rotating Logs
For long-running projects, consider date-based log files:
echo "[$(date -Iseconds)] [INFO] message" >> .claude/logs/activity-$(date +%Y-%m-%d).log
Integration with Subagents
Subagents inherit access to bash and should follow the same logging conventions. When delegating tasks, instruct subagents to:
- Log their start and completion
- Use the same log file path
- Prefix messages with their agent name for traceability
Example subagent log entry:
echo "[$(date -Iseconds)] [INFO] [test-writer] start: Generating unit tests for PaymentStrategy classes" >> .claude/logs/activity.log
Converted and distributed by TomeVault — claim your Tome and manage your conversions.