Troubleshooting and Logging
Relevant source files
The following files were used as context for generating this wiki page:
Troubleshooting and logging within the OhMyOpenCode ecosystem are governed by a multi-layered architecture of automated verification, proactive progress reporting, and specialized review agents. The system utilizes a "Trust but Verify" philosophy where every action taken by an agent is subjected to rigorous automated checks, including Language Server Protocol (LSP) diagnostics, test suite execution, and cross-agent audits.
The primary goal is to ensure "Decision Complete" outcomes where implementation errors are caught and resolved before final delivery. This is achieved through structured logging in the form of progress updates, task tracking, and evidence collection stored within the .sisyphus/ directory.
System Observability and Progress Tracking
The system mandates proactive communication to keep the user informed of the agent's internal state and current phase. Agents must report progress at meaningful transitions to ensure transparency and prevent the system from appearing as a "black box."
Progress Update Protocols
Agents are required to send brief, concrete updates during specific triggers:
- Before Exploration: Identifying the intent and scope of search.
- After Discovery: Reporting found patterns or configuration locations.
- Before Large Edits: Notifying the user before modifying multiple files.
- On Phase Transitions: Moving from exploration to implementation or verification.
- On Blockers: Explaining snags and alternative approaches being attempted.
Sources: src/agents/hephaestus/gpt.ts:241-255, src/agents/sisyphus/default.ts:468-477
Task and Todo Management
Multi-step work is tracked through a non-negotiable task/todo system. This serves as the "execution backbone" and recovery mechanism.
| Component | Description | Mandatory Action |
|---|---|---|
| Task Creation | Initial breakdown of a multi-step request. | task_create or todowrite FIRST. |
| Status Updates | Real-time state of an atomic step. | Mark in_progress (one at a time). |
| Completion | Immediate marking after verification. | Mark completed (never batch). |
| Scope Changes | Updates to the plan during execution. | Update tasks BEFORE proceeding. |
Sources: src/agents/hephaestus/gpt.ts:42-63, src/agents/sisyphus/default.ts:50-70
Automated Verification and Evidence Collection
OhMyOpenCode implements a 4-Phase Critical QA protocol to troubleshoot and validate implementation tasks. Agents are instructed to assume that subagent self-reports are "suspicious" and require independent verification using direct tools.
The 4-Phase QA Workflow
The following diagram illustrates the standard verification flow required after any code modification:
This workflow ensures that "No Evidence = Not Complete." Agents must capture output from tests, builds, and diagnostics as proof of work.
Sources: src/agents/atlas/gemini-prompt-sections.ts:79-135, src/agents/hephaestus/gpt.ts:291-305, src/agents/sisyphus/default.ts:439-450
Diagnostic Tools and evidence
| Tool | Purpose | Success Criteria |
|---|---|---|
lsp_diagnostics | Static analysis and type checking. | Zero errors on modified files. |
Bash (test) | Running unit and integration tests. | Exit code 0 / All tests pass. |
Bash (build) | Verifying build-time integrity. | Exit code 0. |
Evidence Files | Persistent logs of QA results. | Stored in .sisyphus/evidence/. |
Sources: src/agents/hephaestus/gpt.ts:293-298, src/agents/prometheus/gpt.ts:223-225, src/agents/sisyphus/default.ts:440-447
Failure Recovery and Escalation
When standard implementation fails, the system follows a deterministic failure recovery protocol to prevent "shotgun debugging" or leaving the codebase in a broken state.
Recovery Protocol
- Fix Root Causes: Agents must avoid patching symptoms.
- Re-verify: Re-run diagnostics after every attempt.
- Alternative Approaches: If the first approach fails, try a different algorithm or pattern.
- Threshold (3 Failures): After three failed attempts, the agent must:
- Stop all edits.
- Revert to the last working state (via git checkout or undo).
- Document the failure context.
- Consult the Oracle agent or the user.
Sources: src/agents/hephaestus/gpt.ts:307-316, src/agents/sisyphus/default.ts:455-463
Specialized Troubleshooting Agents
The project utilizes specialized agents to audit and review work plans and implementation results.
- Metis: Performed during the planning phase to identify missed questions, guardrails, and scope creep.
- Momus (The Blocker-Finder): A ruthless reviewer that identifies blocking issues in work plans. It verifies if referenced files exist and if the plan is practically executable.
- Oracle: A high-reasoning agent used as a last resort for complex architectural or debugging problems.
Sources: src/agents/prometheus/plan-generation.ts:37-60, src/agents/momus.ts:25-50, src/agents/hephaestus/gpt.ts:312
Review and Audit Phases (The Final Wave)
Before a task is considered truly resolved, it must pass the "Final Verification Wave," consisting of four parallel approval gates.
The Orchestrator agent (Atlas or Sisyphus) is responsible for coordinating these reviews. If any reviewer rejects the work, the agent must fix the issue and re-run the audit until all verdicts are APPROVE.
Sources: src/agents/atlas/gemini-prompt-sections.ts:153-165, src/agents/prometheus/gpt.ts:340-345
Logging and troubleshooting in OhMyOpenCode are not merely passive activities but active requirements built into every agent's core loop. By combining strict task discipline, multi-phase verification, and specialized audit agents like Momus and Metis, the system maintains a high bar for implementation accuracy and system stability.