Documentation index

Using Programa

• keyboard-shortcuts.md: default shortcuts, action ids and chord syntax for custom bindings.
• settings-json.md: every key in ~/.config/programa/settings.json.
• programa-json.md: programa.json commands and recipes, the layout schema, and saved layouts.
• workspace-interface.md: the pane tab bar, agent logos on tabs, edge fades, and the ports panel.
• terminal-themes.md: terminal themes, opacity, blur and font.
• notifications.md: notifications, the sidebar agent indicator, and agent hook examples.
• program-status.md: the OSC 7501 program status protocol for reporting what a program is doing.
• troubleshooting.md: log locations, finding the socket, and what to put in a bug report.
• diagnostics.md: the always-on local diagnostics log.
• environment-variables.md: every PROGRAMA_* and PROGRAMAD_* variable.

Automation and agents

• socket-api.md: the control socket, its security model, discovery, and the core methods; the full method list is contracts/v2/methods.json.
• mcp-server.md: the MCP server and its tools.
• agent-skill.md: the installable agent skill.
• agent-usage.md: what token data Claude Code and Codex record, and programa usage.
• agent-detection-manifests.md: the manifest format for screen-based agent detection.
• aside-browser.md: Using the Aside browser from agents in Programa panes.

Building, testing and releasing

• testing-layout.md: the four test harnesses and how to run them.
• cpu-harness.md: the CPU occlusion measurement harness.
• release.md: how a commit becomes a release, and the required secrets.
• ghostty-fork.md: the patches Programa carries on Ghostty and how to update the fork.
• windows-testing.md: testing the Windows build.
• windows-signing.md: signing the Windows executable.

Removed features

• removed/README.md: features deleted on purpose, with what to keep in mind if they return.

Plans

Design and planning documents. Most start with a Status: line.

• plans/agent-events.md: normalized agent lifecycle events.
• plans/agent-state-unification.md: one source of agent state and one sidebar indicator.
• plans/appdelegate-shortcut-coupling.md: why shortcut routing stays in AppDelegate.
• plans/core-foundations-resume-2026-09-16.md: recovery log for the core foundation work.
• plans/core-seam.md: the seam between the app and a replaceable core.
• plans/detached-sessions.md: sessions that survive quit and crash.
• plans/diff-review-panel.md: the agent diff review panel.
• plans/dual-platform-rolling-release-2026-09-16.md: macOS and Windows assets on one rolling release.
• plans/local-attention-classification.md: optional local classification of which workspace needs attention.
• plans/main-window-appkit-ownership.md: moving main window ownership to AppKit.
• plans/native-frontends-shared-core-2026-09-16.md: native frontends over one shared core.
• plans/native-sidebar-owner-experiment.md: the native sidebar owner experiment and its no-go result.
• plans/reliability-2026-09-13.md: the session reliability release.
• plans/rust-core-concepts.md: inventory of concepts a replacement core must reproduce.
• plans/rust-core-spike.md: the Rust core spike and its decision.
• plans/screen-manifest-detection.md: screen-based agent detection.
• plans/settings-mcp-tools.md: reading and writing settings over the socket and MCP.
• plans/snapshot-restore.md: session snapshot history and restore.
• plans/t3code-inventory.md: inventory of the t3code project.
• plans/windows-frontend-tab-drag-2026-09-16.md: draggable tabs in the macOS and Windows frontends.
• plans/worktree-and-layouts.md: git worktree workflow and named layouts.