pi-orca-debug

Debug log viewer overlay and logging control

Version: 0.0.3-dev
License: MIT

Overview

A diagnostic extension for Pi Orca that controls the shared structured JSONL logger from @pi-orca/core and provides an interactive full-screen overlay for browsing live log entries. Use the /debug slash command to open the log viewer, enable or disable logging, set the minimum log level, and toggle logging on and off. All other Pi Orca extensions use the shared logger instead of console.log, funneling all diagnostic data into a single append-only log file.

Features

Debug Log Viewer Overlay

Run /orca-debug (no arguments) or /orca-debug view to open a full-screen interactive overlay:

• Scrollable log entry list — SelectList with fuzzy search
• Live polling — Refreshes every 2 seconds to show new entries in real time
• Sort toggle — Press R to toggle between newest-first (default) and oldest-first
• Metadata expand/collapse — Press Enter on any entry to expand its metadata block
• Selection persistence — Cursor position is preserved across overlay rebuilds (sort toggles, live polls)
• Keybindings: | Key | Action | |-----|--------| | ↑ / ↓ | Navigate entries | | Enter | Expand/collapse metadata | | R | Toggle sort order | | Esc | Close overlay |

Logging Control

• Enable/disable logging — Toggle logging on and off via /debug on and /debug off
• Configurable log levels — Set minimum log level (debug, info, warn, error) via /debug set <level>
• Autocomplete — Full autocomplete for subcommands and log levels
• Structured JSONL log — All entries include timestamp, level, source, message, and optional metadata
• Log rotation — 10 MB default, keeps 3 rotated files (configurable via config.yaml)

Defaults

| Setting | Default | |---------|---------| | enabled | false (logging disabled) | | logLevel | info |

When logging is disabled, all log*() calls are no-ops — nothing is written to disk.

When logging is enabled, only entries at or above the configured log level are written:

| Level | Writes when logLevel is... | |-------|---------------------------| | debug | debug, info, warn, error | | info | info, warn, error | | warn | warn, error | | error | error only |

Log File

Location: ~/.pi/agent/orca/log.jsonl

Entry format:

{"ts":"2026-04-24T10:00:00.000Z","level":"info","source":"pi-orca-tasks","message":"Ready"}
{"ts":"2026-04-24T10:00:01.000Z","level":"debug","source":"pi-orca-models","message":"Resolved alias","meta":{"alias":"fast","resolved":"anthropic/claude-haiku-4-5"}}

Rotation: When the log exceeds 10 MB (configurable), it is rotated to log.jsonl.<ISO-timestamp>. Up to 3 rotated files are kept (configurable).

Configuration

Add to ~/.pi/agent/orca/config.yaml or <project>/.pi/orca/config.yaml:

logging:
  enabled: false                 # disable all logging (default)
  logLevel: info                 # minimum level: debug, info, warn, error
  maxFileSizeBytes: 10485760    # 10 MB (default)
  maxRotatedFiles: 3            # keep 3 rotated files (default)

Slash Commands

| Command | Description | |---------|-------------| | /orca-debug | Open the debug log viewer overlay | | /orca-debug view | Open the debug log viewer overlay (alias) | | /orca-debug on | Enable debug logging | | /orca-debug off | Disable debug logging | | /orca-debug set <level> | Set minimum log level (debug, info, warn, error) |

Autocomplete

All subcommands and log levels are autocompleted via tab completion:

• /orca-debug → suggests on, off, set, view
• /orca-debug set → suggests debug, info, warn, error

Architecture

src/
├── index.ts    # Extension entry: command registration, autocomplete, handlers
└── overlay.ts  # Full-screen debug log viewer overlay with live polling

Logger API

Extensions use the logger from @pi-orca/core instead of console.log:

import { logInfo, logWarn, logError, logDebug, getLogFile } from "@pi-orca/core";

logInfo("pi-orca-tasks", "Ready");
logWarn("pi-orca-models", "Alias not found", { alias: "fast" });
logError("pi-orca-cleanup", "Failed to sweep", { error: "permission denied" });
logDebug("pi-orca-debug", "Loaded 150 entries");

Dependencies

• @pi-orca/core — Logger utility, debug config, autocomplete helpers, path resolution, selection persistence
• @earendil-works/pi-coding-agent — DynamicBorder for overlay framing
• @earendil-works/pi-tui — SelectList, Container, Text, Spacer for overlay UI

License

MIT License — see LICENSE for details.