Imported from jacobjmc/OpenCodeMonitor (AGENTS.md). Install upstream with npx skills add jacobjmc/OpenCodeMonitor. Copyright stays with the author.

OpenCodeMonitor Agent Guide

All docs must be canonical, with no past commentary, only live state.

Scope

This file is the agent contract for how to work in this repo. Detailed navigation/runbooks live in:

• docs/codebase-map.md (task-oriented file map: "if you need X, edit Y")
• README.md (setup, build, release, and broader project docs)
• docs/shaping/rest-api-migration.md (REST backend architecture and parity status)

Project Purpose

OpenCodeMonitor is a fork of CodexMonitor — a Tauri desktop app that orchestrates coding agents across local workspaces. The fork replaces the Codex CLI backend with OpenCode and translates between OpenCode's protocol and the original CodexMonitor frontend event shapes.

We pull upstream CodexMonitor changes regularly (weekly/monthly). The fork's translation layer is isolated to three Rust files so frontend merges stay clean.

Architecture

• Frontend: React + Vite (src/)
• Backend app: Tauri Rust process (src-tauri/src/lib.rs)
• Backend daemon: JSON-RPC process (src-tauri/src/bin/codex_monitor_daemon.rs)
• Shared backend source of truth: src-tauri/src/shared/*
• Protocol event translation: src-tauri/src/backend/event_translator.rs

Core Design Invariant

The frontend thread reducer receives events in the same shape as original CodexMonitor. All OpenCode-to-CodexMonitor translation happens in Rust, never in the frontend.

Backend: REST API

The backend uses opencode serve (HTTP REST + SSE). The translation layer is isolated to three Rust files so frontend merges stay clean:

• src-tauri/src/backend/event_translator.rs — protocol events to CodexMonitor event shapes
• src-tauri/src/shared/codex_core.rs — all protocol methods
• src-tauri/src/backend/app_server.rs — process spawn, event routing

Internal Rust module paths (codex_core.rs, codex/mod.rs, etc.) are not renamed — only user-facing strings. This minimizes merge conflicts with upstream. (The original CodexMonitor used Codex CLI; this fork uses OpenCode REST instead.)

Non-Negotiable Architecture Rules

1. Put shared/domain backend logic in src-tauri/src/shared/* first.
2. Keep app and daemon as thin adapters around shared cores.
3. Do not duplicate logic between app and daemon.
4. Keep JSON-RPC method names and payload shapes stable unless intentionally changing contracts.
5. Keep frontend IPC contracts in sync with backend command surfaces.
6. All OpenCode protocol translation happens in Rust — never in the frontend.

Backend Routing Rules

For backend behavior changes, follow this order:

1. Shared core (src-tauri/src/shared/*) when behavior is cross-runtime.
2. App adapter and Tauri command surface (src-tauri/src/lib.rs + adapter module).
3. Frontend IPC wrapper (src/services/tauri.ts).
4. Daemon RPC surface (src-tauri/src/bin/codex_monitor_daemon/rpc.rs + rpc/*).

If you add a backend command, update all relevant layers and tests.

Frontend Routing Rules

• Keep src/App.tsx as composition/wiring root.
• Move stateful orchestration into:
  • src/features/app/hooks/*
  • src/features/app/bootstrap/*
  • src/features/app/orchestration/*
• Keep presentational UI in feature components.
• Keep Tauri calls in src/services/tauri.ts only.
• Keep event subscription fanout in src/services/events.ts.

Import Aliases

Use project aliases for frontend imports:

• @/* -> src/*
• @app/* -> src/features/app/*
• @settings/* -> src/features/settings/*
• @threads/* -> src/features/threads/*
• @services/* -> src/services/*
• @utils/* -> src/utils/*

Key File Anchors

• Frontend composition root: src/App.tsx
• Frontend IPC wrapper: src/services/tauri.ts
• Frontend event hub: src/services/events.ts
• App command registry: src-tauri/src/lib.rs
• Daemon entrypoint: src-tauri/src/bin/codex_monitor_daemon.rs
• Daemon RPC router: src-tauri/src/bin/codex_monitor_daemon/rpc.rs
• Shared workspaces core: src-tauri/src/shared/workspaces_core.rs + src-tauri/src/shared/workspaces_core/*
• Shared git UI core: src-tauri/src/shared/git_ui_core.rs + src-tauri/src/shared/git_ui_core/*
• Protocol event translator: src-tauri/src/backend/event_translator.rs
• Protocol methods: src-tauri/src/shared/codex_core.rs
• Process spawn + event routing: src-tauri/src/backend/app_server.rs
• Threads reducer entrypoint: src/features/threads/hooks/useThreadsReducer.ts
• Threads reducer slices: src/features/threads/hooks/threadReducer/*

For broader path maps, use docs/codebase-map.md.

App/Daemon Parity Checklist

When changing backend behavior that can run remotely:

1. Shared core logic updated (or explicitly app-only/daemon-only).
2. App surface updated (src-tauri/src/lib.rs + adapter).
3. Frontend IPC updated (src/services/tauri.ts) when needed.
4. Daemon RPC updated (rpc.rs + rpc/*) when needed.
5. Contract/test coverage updated.

Design System Rule (High-Level)

Use existing design-system primitives and tokens for shared shell chrome. Do not reintroduce duplicated modal/toast/panel/popover shell styling in feature CSS.

(See existing DS files and lint guardrails for implementation details.)

Safety and Git Behavior

• Prefer safe git operations (status, diff, log).
• Do not reset/revert unrelated user changes.
• If unrelated changes appear, continue focusing on owned files unless they block correctness.
• If conflicts impact correctness, call them out and choose the safest path.
• Fix root cause, not band-aids.

Validation Matrix

Run validations based on touched areas:

• Always: npm run typecheck
• Frontend behavior/state/hooks/components: npm run test
• Rust backend changes: cd src-tauri && cargo check
• Use targeted tests for touched modules before full-suite runs when iterating.

Quick Runbook

Core local commands (keep these inline for daily use):

npm install
npm run doctor:strict
npm run tauri:dev
npm run test
npm run typecheck
cd src-tauri && cargo check

Release build:

npm run tauri:build

Focused test runs:

npm run test -- <path-to-test-file>

Hotspots

Use extra care in high-churn/high-complexity files:

• src/App.tsx
• src/features/settings/components/SettingsView.tsx
• src/features/threads/hooks/useThreadsReducer.ts
• src-tauri/src/shared/git_ui_core.rs
• src-tauri/src/shared/workspaces_core.rs
• src-tauri/src/shared/codex_core.rs
• src-tauri/src/backend/event_translator.rs
• src-tauri/src/backend/app_server.rs
• src-tauri/src/bin/codex_monitor_daemon/rpc.rs

Canonical References

• Task-oriented code map: docs/codebase-map.md
• Setup/build/release/test commands: README.md
• REST backend architecture: docs/shaping/rest-api-migration.md
• Frontend event contract: docs/app-server-events.md
• For OpenCode API/feature changes, refer to opencode-server-api.mdx and ./tmp/opencode before implementing protocol or behavior updates.

Project Memory

Load project memory: read .memory/SUMMARY.md before starting work. If .memory/ doesn't exist, initialize it per the project-memory skill.