jockey: Instructions file for Codex

Repository Guidelines

JockeyUI is a Tauri 2 desktop app — a multi-agent orchestrator ("Conductor") that coordinates AI CLI agents (Claude Code, Codex CLI, Pi CLI, Antigravity CLI). ACP (Agent Client Protocol) is the only live agent protocol. Claude, Codex, Pi and Antigravity run through external ACP adapters; Jockey owns the shared client, session lifecycle and decision UI (see ACP Transport).

Further documentation is indexed in docs/README.md.

Build, Test, and Development Commands

# Frontend & Tauri Development
pnpm dev          # Start the Vite dev server only (port 1420); use `pnpm tauri dev` for the app
pnpm build        # Build production frontend into dist/
pnpm tauri dev    # Start full Tauri desktop app (frontend + Rust backend)
pnpm tauri build  # Build distributable app bundle

# Rust Backend (from project root — use --manifest-path for CI or scripts)
cargo check --manifest-path src-tauri/Cargo.toml  # Fast Rust type check
cargo test --manifest-path src-tauri/Cargo.toml   # Run Rust tests
cargo clippy --manifest-path src-tauri/Cargo.toml # Rust lint checks
cargo fmt --manifest-path src-tauri/Cargo.toml    # Format Rust code

Project Structure & Architecture

File Layout

• src/: SolidJS + TypeScript UI.
  • App.tsx — Main view entry.
  • index.tsx — Bootstraps app.
  • index.css — Tailwind and CSS design tokens (--ui-*).
  • components/ — ui/ (design-system primitives), composer/, management/ (settings tabs), sidebar/, plus chat, git, files, and terminal panels.
  • hooks/ — Session and agent state (useAgentData, useAgentContext, etc.).
  • lib/ — tauriApi.ts (typed invoke wrappers), engineEvents.ts (engine event listeners), acpEventBridge.ts (live ACP stream), commandUi/ (composer command registry), browserMock.ts (runs the UI without Tauri).
• src-tauri/src/: Rust backend.
  • lib.rs — Registers Tauri commands (generate_handler!), state, and startup recovery.
  • engine/ — Engine service layer: turn lifecycle, queue, transcript recording, events, and engine commands.
  • acp/ — Runtime adapters and transports (see below).
  • chat.rs, chat/ — Chat core: prompt building, context bundle, and session runtime between the engine and acp.
  • db/ — SQLite persistence (pooled, migrations gated on user_version).
  • commands/ — Tauri #[command] handlers (runtime control, git, completion, ...).
  • web_gateway/ — axum HTTP + SSE gateway for the phone companion (src/companion/, built to dist-companion/ and embedded by build.rs); token auth, default port 8420.
  • jockey_mcp/ — Built-in MCP bridge exposing get_session_context, list_roles, list_skills, get_skill, invoke_role.
  • importer/ — Claude/Codex/Pi transcript import.
  • git/ — Git operations behind the git_*_cmd commands.
  • runtime_kind.rs, runtime_profile.rs — Canonical runtime keys and custom runtime profiles.
• docs/: Architecture notes, reviews, roadmap, and reference material (index in docs/README.md).
• public/: Static assets packaged by Vite.
• Generated output: dist/ (frontend build) and src-tauri/target/ (Rust build artifacts); do not commit these.