forge_logs
Query structured event logs from Forge runs to debug failures, audit tool execution history, and investigate errors without re-running processes.
Instructions
Query the structured JSONL event stream that forge writes on every tool call throughout a run. Filter by runId, moduleId, phase (planning, execution, validation, review, retry, memory, session, tool_call, plan_validation), severity (info, warn, error), and limit. Lets agents reconstruct what happened without re-running anything, and lets humans audit a run after the fact without paging through console output.
Behaviour:
READ-ONLY, idempotent.
Reads
.forge/logs/<runId>.jsonl. WhenrunIdis omitted, the most recently modified log file in.forge/logs/is used.runIdis guarded against path traversal via_RUN_ID_PATTERN.JSON parse errors on individual lines are silently skipped — a single corrupt line does not crash the query.
No authentication, no network, no rate limits.
Use when:
A debugger agent needs the sequence of events leading up to a module failure — especially useful for diagnosing why validation failed even though review passed.
A user wants to audit what a forge run actually did, after the fact, without re-running anything.
The orchestrator wants to confirm that a prior phase completed successfully before transitioning.
Investigating an escalation: pull all
severity: "error"entries for the run and read them in order.
Do NOT use for:
Live progress display — read
/tmp/forge-status.jsonwhich the server refreshes on every tool call, or callsession_statewithaction: "list".Appending new entries — the server writes logs automatically; there is no external append API.
Long-term knowledge — that's
memory_save/memory_recall.
Returns: { runId, entries: [...], total }. Each entry is
{ timestamp, runId, phase, moduleId, event, severity, data }.
data is a free-form object whose shape depends on the event
type.
Example: forge_logs({ runId: "2026-04-15-1", phase: "validation", severity: "error", limit: 10 }) → { "runId": "2026-04-15-1", "total": 2, "entries": [ { "timestamp": "...", "phase": "validation", "moduleId": "m3", "event": "validate", "severity": "error", "data": { "passed": false, "score": 0.5, ... } }, ... ] }
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| runId | No | Run ID to query. If omitted, uses most recent log file. | |
| moduleId | No | Filter by module ID | |
| phase | No | Filter by phase name | |
| severity | No | Filter by severity level | |
| limit | No | Max entries to return (default: 50) |