termcanvas: Instructions file for Codex

AGENTS.md

This file explains the local architecture of the TermCanvas app so future agents can extend it safely.

Product intent

This is a minimal infinite-canvas Electron app for spatial terminal workflows.

Each node is a real interactive terminal, not a text note. The product should stay simple and terminal-first.

Architecture overview

Main process — main.js

Responsibilities:

• create the Electron window
• own the terminal session registry
• spawn PTY clients through node-pty
• attach PTY clients to long-lived tmux sessions when tmux is available
• fall back to plain shell PTYs when tmux is unavailable
• validate that a renderer only talks to its own terminal sessions
• detach live tmux-backed sessions when a window closes
• permanently destroy a terminal session when the user closes a node
• own workspace folder import, refresh, watch, and preview access
• own app-session file persistence in Electron userData
• own file dialog and local file read/write for canvas JSON and app-data JSON import/export

Important rule:

Real shell processes belong in main, never in the renderer.

Terminal identity model

The current session store is:

• Map<terminalId, session>

Important distinction:

• terminalId is the current renderer-to-main attachment id
• sessionKey is the stable terminal identity saved in app-session snapshots
• tmux session names are derived from sessionKey

Each session currently tracks:

• ownerWebContentsId
• pty
• shellName
• cwd
• backend ("tmux" or "pty")
• sessionKey
• tmuxSessionName
• isDisposing

Detach semantics matter:

• closing the app/window should detach from tmux-backed sessions in normal runs
• clicking a node close button should kill the underlying session permanently
• smoke-test mode disables persistent relaunch behavior so tests do not leak sessions

App-session persistence

The app now persists a normalized JSON snapshot under Electron userData.

That snapshot includes: