orbit: Instructions file for Codex

AGENTS.md

This file provides guidance to WARP (warp.dev) when working with code in this repository.

What is Orbit

Orbit is a Tauri v2 desktop app that aggregates and displays coding agent session transcripts from multiple AI tools (Claude Code, Codex, Cursor, OpenCode). It indexes session files from each tool's local storage into a unified SQLite database, then presents them in a searchable, filterable UI with transcript viewing and session resume capabilities.

Build & Dev Commands

• npm run tauri dev — Run the full app in dev mode (starts Vite frontend + Rust backend)
• npm run dev — Start only the Vite frontend dev server (port 1420)
• npm run build — TypeScript check + Vite production build (frontend only)
• npm run tauri build — Full production build (frontend + Rust, produces native binary)
• cargo build — Build only the Rust backend (run from src-tauri/)
• cargo test — Run Rust tests (run from src-tauri/)
• tsc --noEmit — TypeScript type check without emitting

There is no linter, formatter, or test runner configured for the frontend. There are no frontend tests.

Architecture

Two-process Tauri model

The app follows Tauri v2's split architecture:

• Frontend (src/): React 19 + TypeScript + Tailwind CSS v4 + Vite. Communicates with the backend exclusively via invoke() from @tauri-apps/api/core.
• Backend (src-tauri/): Rust. Exposes Tauri commands that the frontend calls. Manages all data access, file system scanning, and session parsing.

Backend (Rust) — key modules

• adapters/ — One adapter per agent tool (Claude, Codex, Cursor, OpenCode). Each implements the AgentAdapter trait which defines: detect() (is the tool installed?), scan() (find session files on disk), parse_session() (parse a session file into normalized NormalizedSession), resume_command(), and is_active(). The AdapterRegistry holds all adapters in a HashMap keyed by string ID.
• adapters/claude.rs — Filters out Claude-Mem plugin observer sessions by checking if the first user message contains "claude-mem" or "Hello memory agent". These return Err("Subagent/plugin session, skipping") from parse_session().
• indexer/ — Orchestrates scanning all adapters, parsing sessions, upserting into SQLite, managing stale session cleanup, and rebuilding the FTS5 index. Uses a size+mtime hash to skip unchanged files. Important: mark_stale_sessions() is called ONCE after ALL adapters finish (not per-adapter), using combined paths from every adapter — otherwise each adapter would delete the previous adapter's sessions.
• db/ — schema.rs creates tables (sessions, messages, attachments) and a messages_fts FTS5 virtual table. queries.rs provides DbQueries for all SQL operations. The database lives at ~/<platform data dir>/orbit/orbit.db with WAL mode enabled.
• commands.rs — Tauri command handlers (#[tauri::command]). These are the IPC boundary: get_sessions, get_session_messages, search_sessions, get_resume_command, launch_resume, get_active_sessions, reindex_all.
• watcher.rs — File system watcher using the notify crate (kqueue on macOS). Currently defined but not wired into the main app loop.
• models.rs — Shared data types: Session, Message, Attachment, AgentType, MessageRole, SessionFilters. These are serialized to/from JSON for the frontend via serde.