| ... | ... | @@ -0,0 +1,35 @@ |
| 1 | # AGENTS.md |
| 2 | |
| 3 | ## Project Snapshot |
| 4 | CodeThing is a minimal GUI for using code agents like Codex and Claude Code (coming soon). |
| 5 | |
| 6 | This repository is a VERY EARLY WIP. Proposing sweeping changes that improve long-term maintainability is encouraged. |
| 7 | |
| 8 | ## Core Priorities |
| 9 | 1. Performance first. |
| 10 | 2. Reliability first. |
| 11 | 3. Keep behavior predictable under load and during failures (session restarts, reconnects, partial streams). |
| 12 | |
| 13 | If a tradeoff is required, choose correctness and robustness over short-term convenience. |
| 14 | |
| 15 | ## Package Roles |
| 16 | - `apps/desktop`: Electron main/preload runtime. Owns provider orchestration, process/session lifecycle, and native IPC boundaries. |
| 17 | - `apps/renderer`: React/Vite UI. Owns session UX, conversation/event rendering, and client-side state. |
| 18 | - `packages/contracts`: Shared Zod schemas and TypeScript contracts for provider events, IPC payloads, and model/session types. |
| 19 | |
| 20 | ## Codex App Server (Important) |
| 21 | CodeThing is currently Codex-first. The desktop app starts `codex app-server` (JSON-RPC over stdio) per provider session, then streams structured events into the renderer through the provider APIs. |
| 22 | |
| 23 | How we use it in this codebase: |
| 24 | - Session startup/resume and turn lifecycle are brokered in `apps/desktop/src/codexAppServerManager.ts`. |
| 25 | - Provider dispatch and thread event logging are coordinated in `apps/desktop/src/providerManager.ts`. |
| 26 | - Renderer consumes provider event streams via `nativeApi.providers.onEvent`. |
| 27 | |
| 28 | Docs: |
| 29 | - Codex App Server docs: https://developers.openai.com/codex/sdk/#app-server |
| 30 | |
| 31 | ## Reference Repos |
| 32 | - Open-source Codex repo: https://github.com/openai/codex |
| 33 | - Codex-Monitor (Tauri, feature-complete, strong reference implementation): https://github.com/Dimillian/CodexMonitor |
| 34 | |
| 35 | Use these as implementation references when designing protocol handling, UX flows, and operational safeguards. |
Theo Browne <me@t3.gg> 2026-02-09 02:07:17-08:00