FullFran/nyxterm / .agents/skills/architecture
architecture
VerifiedOverall stack and module shape for nyxterm. Load when touching Tauri commands, PTY wiring, frontend↔backend IPC, or xterm rendering.
Architecture
Stack
- Backend: Rust 2021+, Tauri 2,
portable-pty. - Frontend: React 18 + TypeScript 5 + xterm.js (with
fit,search,webgl,web-links,serializeaddons). - IPC: Tauri
invoke()for commands; Tauri channels for binary streams (no JSON encoding of PTY output).
Module shape (target)
nyxterm/
├── src-tauri/src/
│ ├── modules/
│ │ ├── pty/ # spawn, reader, flusher, waiter, signals, OSC filter
│ │ ├── multiplex/ # panes, splits, sessions
│ │ ├── shell/ # shell init (ZDOTDIR injection like Ghostty/Terax)
│ │ ├── fs/ # file ops for the AI harness
│ │ ├── theme/ # palette emit + theme reload
│ │ └── ai/ # provider routing, MCP client
│ ├── lib.rs # app init, command registration
│ └── main.rs
└── src/
└── modules/
├── terminal/ # TerminalPane, xterm wiring, renderer pool
├── multiplex/ # pane grid UI
├── ai/ # chat panel, tool calls
├── command-palette/
└── settings/
PTY wiring (the pattern we copy from terax-ai)
Three concurrent threads per PTY session:
- Reader: blocking read of 16 KiB chunks, push through a DA filter, buffer with backpressure cap (4 MiB).
- Flusher: coalesces bursts (4 ms window, 50 ms idle ceiling). Emits
ArrayBufferchunks to the frontend channel. - Waiter: blocks on child exit, drains the reader, emits final buffer + exit code.
See pty-handling for the gotchas (SIGWINCH, ConPTY, OSC 7 trust).
IPC contract
Commands (frontend → backend):
#[tauri::command] fn pty_open(cols: u16, rows: u16, cwd: Option<String>, env: WorkspaceEnv) -> SessionId
#[tauri::command] fn pty_write(session_id: SessionId, data: String)
#[tauri::command] fn pty_resize(session_id: SessionId, cols: u16, rows: u16)
#[tauri::command] fn pty_close(session_id: SessionId)
Channels (backend → frontend):
data: ArrayBuffer— raw PTY bytes, no encoding.exit: i32— exit code on child termination.
Frontend receives ArrayBuffer and writes directly into xterm via term.write(bytes). Do NOT base64-encode — that doubles bandwidth and burns CPU.
Rendering
- xterm.js with WebglAddon for GPU rendering. Handle context-loss with a 250 ms re-attach (terax-ai pattern).
- Renderer pool: up to 5 reusable xterm instances kept off-screen. When releasing a slot, track
altScreenAtReleaseso we can SIGWINCH-kick the next bind for clean TUI repaint.
What lives where
| Concern | Layer |
|---|---|
| PTY syscalls, signals | Rust (src-tauri/src/modules/pty) |
| Theme palette source-of-truth | Rust emits, frontend listens |
| Pane layout state | Frontend (Zustand or similar), persisted via Engram |
| AI tool execution (Read/Write/Edit/Bash) | Rust (sandboxed where possible) |
| AI chat UI | React |
| MCP client | Rust |
When you change this
Update this skill and AGENTS.md's skills table. Architectural changes are SDD-tracked (proposal → design → ...).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 318k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |