episko: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Episko is a Tauri v2 desktop app (Rust backend + vanilla-TS frontend) that launches and manages many coding-agent sessions at once (each in its own PTY) and streams provider capabilities such as status, context, usage and approvals back into the app. Claude Code and Codex are integrated providers; the remaining discovered CLIs use a terminal-only adapter. macOS-first; still an early spike.

The deep design notes live in docs/, one file per area, indexed at the bottom of this file. Read the matching doc before working on an area. This file keeps the commands, the module maps, and the invariants that apply to almost any change.

Commands

pnpm install            # first time
pnpm tauri dev      # run the app (Tauri + Vite dev server on fixed port 1420)
pnpm tauri build    # production bundle
pnpm build          # typechecks BOTH projects + vite build (frontend only; the beforeBuildCommand)
pnpm exec tsc --noEmit       # typecheck src/ only (tsconfig is noEmit)
pnpm exec tsc -p tsconfig.test.json --noEmit   # typecheck test/ (the other half)
pnpm test               # vitest: frontend unit tests (test/*.test.ts)
pnpm coverage           # the same suites with v8 coverage

Rust backend (run from src-tauri/): cargo check, cargo test, cargo build, cargo clippy --all-targets. Clippy is a CI gate (-- -D warnings, both OSes). Run rustup component add clippy first, then run every gate above locally before pushing, on the toolchains CI uses (stable Rust, the .nvmrc Node via nvm use). All three suites have gone red in CI for exactly one reason: the check was never run locally.

• Package manager: pnpm, never npm (pnpm-lock.yaml; packageManager pins the version; CI uses --frozen-lockfile).
• Half the Rust is platform-cfg-gated and invisible to any one machine. The cfg-flip trick type-checks the other half; see docs/testing.md for the procedure and its limits, and commit your real changes before running it.
• Never build a test's temp path by hand. testutil::scratch_dir resolves before it returns so fixtures compare like with like; env::temp_dir() is a symlink on macOS and an 8.3 short name on the Windows runner (docs/testing.md).