This directory contains architectural and design documentation for the tmuxy project. It is written for both human developers and AI coding agents (Claude Code, Copilot, etc.) that work on this codebase.
Before starting work: Read the docs relevant to the area you're changing. They provide critical context about architecture, constraints, and conventions that aren't obvious from reading code alone.
After finishing work: If your changes affect behavior described here, update the relevant docs or flag the misalignment.
For AI agents: The project's AGENTS.md references these docs and includes rules about reviewing them. Key constraints (e.g., all tmux commands must go through control mode) are documented here because they prevent crashes and data loss.
| Document |
What it covers |
When to read it |
| ARCHITECTURE.md |
High-level system overview: components, how they interact, key design decisions, file structure |
Starting any work on the project; onboarding |
| STATE-MANAGEMENT.md |
Frontend XState machine (states, context, actors, child machines, selectors, React hooks) and backend Rust state (AppState, SessionConnections, TmuxMonitor, StateAggregator, MonitorCommand, StateEmitter) |
Changing state handling, adding events, modifying the machine, or working on the Rust backend |
| DATA-FLOW.md |
SSE/HTTP protocol, Tauri IPC, adapter pattern, delta protocol, connection lifecycle, keyboard input flow, and three real-world deployment scenarios |
Working on client-server communication, the adapter layer, or deployment configuration |
| Document |
What it covers |
When to read it |
| TMUX.md |
Control mode architecture, command routing rules (which commands must use control mode vs. safe as subprocesses), new-window crash workaround, version-specific bugs, tmux configuration, flow control, and the @tmuxy-* window/pane tag schema (floats, pane groups, the stash session, window filtering) |
Any work involving tmux commands, pane/window operations, floats, pane groups, or shell scripts |
| COPY-MODE.md |
Client-side copy mode reimplementation: vi keybindings, scrollback loading, selection/clipboard, entry/exit triggers, key files |
Working on copy mode, scrollback, or keyboard handling during copy mode |
| Document |
What it covers |
When to read it |
| SECURITY.md |
Threat model, optional password auth, loopback by default, known risks (no TLS, file access, run-shell), deployment recommendations |
Deploying tmuxy, adding network-facing features, or assessing risk |
| NON-GOALS.md |
What tmuxy intentionally does NOT do (no terminal emulation, no live local scrollback buffer, no local echo, no canvas rendering, etc.) |
Before proposing a new feature; understanding design boundaries |
| Document |
What it covers |
When to read it |
| TESTS.md |
Every test layer and the CI job that runs it, where a new test belongs, known coverage gaps, and the guidelines for each test type |
Writing, placing or debugging tests; reading a CI failure |
| PERFORMANCE.md |
Speed measurement along two independent axes: core + client processing (Axis A) vs transport (Axis B), and the harness for each |
Benchmarking, profiling, or investigating latency |
| TELEMETRY.md |
Unified cross-layer action tracing (XState/Effect/Rust/Tauri) into one local NDJSON file: schema, instrumentation seams, redaction boundary |
Debugging complex cross-layer issues; adding instrumentation |
| RUNBOOK.md |
Task-to-command matrix and practical execution order |
Choosing the right command set for a specific change |
| CI-TRIAGE.md |
Fast triage workflow for CI failures, with job-to-command mappings and artifact entry points |
Investigating red GitHub Actions runs |
| Document |
What it covers |
When to read it |
| RICH-RENDERING.md |
Terminal image protocols (iTerm2, Sixel), OSC sequences (hyperlinks, clipboard, notifications), current implementation status |
Working on terminal rendering, OSC parsing, or considering rich content features |
| ARCHITECTURE-INDEX.md |
Compact feature-to-files lookup index optimized for retrieval by AI agents |
Quickly locating implementation entry points |
- No project-specific code in docs. Describe architecture in prose and tables. Reference file paths instead of embedding code snippets (they go stale).
- Use ASCII diagrams, not Mermaid. Plain ASCII art in fenced code blocks works everywhere.
- Uppercase filenames (e.g.,
ARCHITECTURE.md) to match README.md convention and distinguish docs from code.
- Cross-reference related docs with a "Related" section at the bottom of each file.