pmtui

Product Introduction

1. Definition: pmtui is a native Rust-based, tmux-backed supervisor and dashboard for persistent, long-running AI coding agent sessions. It falls into the technical categories of AI agent orchestration, developer productivity tools, and terminal user interface (TUI) applications.
2. Core Value Proposition: It exists to solve agent loop drift in long-horizon AI coding tasks. pmtui keeps the supervision loop outside the AI agent (like Claude Code or Cursor's agent mode), rebuilding the prompt from a persistent goal and the agent's last status on a configurable cadence. Its primary value is asynchronous AI collaboration, ensuring continuous progress while minimizing human-in-the-loop interruptions by surfacing only decisions that genuinely require human judgment.

Main Features

1. Persistent, Project-Based Agent Sessions: Each managed project maintains a dedicated, persistent tmux terminal session running a claude or codex agent. This stateful design ensures conversation history, code context, and agent memory are preserved across work sessions, reboots, and disconnections. The architecture is file-based, with session state written to disk, making the dashboard (pmtui) functional independently of the optional daemon (pmd).
2. Intelligent Autopilot & Heartbeat System: The optional pmd daemon acts as a headless driver, implementing a heartbeat mechanism for sessions in Autopilot mode. It nudges idle agents, reads decision markers they write, detects stalls, and automatically handles routine choices. It escalates non-routine decisions to the user via logs and desktop notifications, enabling asynchronous, goal-directed AI coding.
3. Dual-View Ratatui Dashboard: The pmtui dashboard offers two optimized views. The Sessions view provides a terminal-first list with a live transcript sidebar for deep context. The Tasks view organizes sessions as cards across workflow columns (Paused, Needs You, Pending, Autopilot, Working), answering "what should I do next." It features full mouse support and theming via 38 opaline themes.
4. Child Job Spawning for Sandboxed Work: Agents can delegate isolated tasks to headless child jobs via the pmtui spawn command. This system runs up to five concurrent children in separate git worktrees/branches, preventing conflicts. It is designed to work within AI sandboxes (like Codex's), is request-idempotent, and requires user approval (a) to merge results, enabling complex multi-agent task decomposition.

Problems Solved

1. Pain Point: Agent context loss and drift during extended, unattended coding tasks. Standard AI agent loops can forget long-term goals, get stuck, or require constant babysitting.
2. Target Audience: Senior Software Engineers and Tech Leads managing multiple complex codebases; Open-Source Maintainers handling issue triage and PR reviews; DevOps/SRE Engineers automating infrastructure code; Solo Founders & Indie Hackers building products with AI pair programmers.
3. Use Cases: Asynchronously progressing a feature branch while focusing on other work; Managing a backlog of bugs by assigning each to a persistent agent with a specific goal; Running automated code refactoring or dependency upgrades across multiple repositories with human oversight only for critical decisions; Orchestrating a multi-step, research-heavy coding task by breaking it into sequenced child jobs.

Unique Advantages

1. Strengths & Limitations (Pros & Cons):
   • Pros: Exceptional reliability and performance from being written in Rust; statically linked Linux binaries for broad compatibility; non-blocking auto-update mechanism; elegant tmux-based isolation preserving full terminal semantics; powerful file-based architecture decoupling UI from daemon.
   • Cons: Requires tmux 3.0+ and comfort with terminal multiplexers; inherently tied to the Claude Code/Codex CLI ecosystem; the autopilot logic depends on the agent's ability to output structured decision markers; currently a command-line tool without a web or GUI frontend.
2. Key Alternatives & Differentiation:
   • Cursor's Agent Mode: A fully integrated, GUI-based agent within an editor. pmtui differentiates by being editor-agnostic, session-persistent across restarts, and designed for multi-project, asynchronous management via a dedicated dashboard, unlike Cursor's single-session, in-editor focus.
   • Custom Scripts with claude CLI: Users could write shell scripts to manage agents. pmtui provides a production-grade, standardized framework with state management, a real-time dashboard, audit logging, child job queuing, and a formal specification, eliminating ad-hoc script maintenance.
   • Other AI Orchestrators (e.g., LangGraph): These are general-purpose frameworks for building agentic workflows. pmtui is a highly specialized, opinionated product focused exclusively on the concrete use case of persistent AI coding sessions, offering a batteries-included, zero-configuration tool rather than a low-level toolkit.

Frequently Asked Questions (FAQ)

1. How does pmtui's autopilot prevent AI agents from going off track? pmtui's autopilot combats drift by externalizing the control loop. Instead of the agent managing its own state, the pmd daemon periodically rebuilds the agent's prompt from the persistent, user-defined goal and the agent's latest status, effectively re-anchoring the agent to the original objective on every nudge and preventing cumulative context deviation.
2. Can I use pmtui with OpenAI's GPT or other AI models besides Claude? Currently, pmtui is specifically designed and integrated with the Claude Code (claude) and Codex (codex) command-line interfaces. Its prompt structuring, decision marker parsing, and spawn system are optimized for these agents. Using it with other models would require significant adaptation of its engine layer.
3. Is it safe to run pmtui's daemon (pmd) continuously on my machine? Yes. The pmd daemon is a minimal, headless Rust binary that only interacts with its designated tmux socket and session state files. It performs no network calls itself (the AI CLI handles that) and operates with the same permissions as the user who started it. The installer also runs a checksum verification on pre-built binaries.
4. What happens if my computer sleeps or I lose internet connection while a session is in autopilot? The persistent tmux session and on-disk state ensure resilience. Upon resuming or reconnecting, the pmd daemon will re-sync with the tmux session. If the AI agent process inside tmux died, pmd can restart it and re-inject the last known context and goal, minimizing progress loss.
5. How does the child job (pmtui spawn) feature handle conflicts in my main git branch? Each child job operates in its own independent git worktree on a dedicated branch. This means the child's commits are isolated from your main working directory and from other concurrent children. No changes reach your primary checkout until you explicitly accept (a) the completed job in the dashboard, providing a safe sandbox for parallel experimentation.