Polter Terminal Agent Supervisor
Put one Claude Code session in charge of independent agents running in other terminal tabs.
- Source repo
- Lugia123/polter
- Stars
- ★ 11
- Last updated
- today
- License
- MIT
- Primary language
- Zig
- FA score
- 80/100 · Good
At a glance
- Works with
- Portable with changesClaude CodeCodex (Partial support)
- You'll need
- Typical use
- A developer running several Claude Code sessions can appoint one session to distribute work and gather reports from the others.
- Main limitation
- Only Claude Code has been tested. Codex is mentioned as a target workflow, but other MCP clients and the seven provisioning plugins should be treated as unverified.
- Source review
- 80/100 · Good
What does this agent do, and when should you use it?
Polter is a Ghostty fork that combines a native terminal emulator with multi-agent supervision. It designates an ordinary Claude Code terminal as the supervisor, then exposes MCP operations for reading text from other tabs, typing into them, opening tabs, and starting independent agent sessions. A chat TUI and task panel present the collaboration, while conversations, terminal transcripts, task changes, and hourly statistics are persisted under `$XDG_STATE_HOME/polter/`. Workers are separate terminal sessions rather than in-process sub-agents, so their work reaches the shared filesystem incrementally. Polter itself needs no account or API key and makes no network request unless the user selects Check for Updates, although an agent CLI must be on `PATH` when the application starts. Claude Code is the only tested client; release bundles cover macOS and Windows, while Linux requires a source build.
The user starts Claude Code in a terminal tab and selects Agents → Make This Terminal a Supervisor; Polter types an instruction telling that session to read its supervising skill. Through its MCP tool surface, the supervisor can read the text displayed by any tab, send text through the paste path, open tabs, and launch agents in them. It can create a persistent group chat, assign work, collect reports, and receive notices based on how long a terminal screen remains unchanged; it does not parse CLI output or decide on its own whether the agent is stuck or thinking. Agents → Terminal Conversations and polter +chat open the chat interface, where tab and shift+tab rotate through the conversation, task panel, and run statistics. The main additions over Ghostty are src/poltergeist/, the MCP tool surface, chat TUI, terminal transcripts, and plugin host. Runtime records are written to $XDG_STATE_HOME/polter/chat/, terminals/, tasks/, and stats/ without redaction.
- A developer running several Claude Code sessions can appoint one session to distribute work and gather reports from the others.
- Someone leaving a long coding run overnight can use screen-quiescence notices to identify sessions that may have stopped making visible progress.
- A team coordinating independent sessions in one working tree can retain line-by-line terminal transcripts and inspect them with
grepthe next morning. - A user who needs lightweight ownership and completion tracking inside a terminal can use the persistent group chat and task panel without adopting a full project-management system.
- An engineer evaluating MCP-based CLI orchestration can experiment with the plain MCP server and seven shipped provisioning plugins, while budgeting validation work for clients other than Claude Code.
How do you install or deploy this agent?
First ensure that an agent CLI is on PATH and remains discoverable when Polter starts. Only Claude Code is explicitly tested. Polter needs no account or API key of its own; authentication requirements for the agent CLI are not documented in the supplied material.
On macOS 13 or later, download Polter-*-macos-universal.zip from the latest release and run:
unzip Polter-*-macos-universal.zip
xattr -dr com.apple.quarantine Polter.app
mv Polter.app /Applications/Launch Polter from Finder or the Dock. Starting it from a terminal may give it a different PATH, preventing the provisioning plugin from finding the agent CLI.
On Windows 10 or later, download and extract Polter-*-windows-x64.zip, run polter-host.exe, and keep both DLLs and share/ beside the executable. Select “Run anyway” if SmartScreen intervenes. The documented Windows port implements 70 of 76 core actions, explicitly refuses four, and still owes two.
No Linux binary is supplied. Linux users must build from source; the supplied material points to dev-docs/preview-manual.md but does not include copyable build commands.
How do you use this agent?
- Open a Polter tab, change to the intended working directory, and start Claude Code.
- Select
Agents → Make This Terminal a Supervisor. Polter instructs the session to read itssupervisingskill. - Send this verification request to the supervisor:
Call the `me` tool and tell me what it says.A returned terminal ID confirms that the MCP tools are available. If the me tool is missing, check whether the plugin is disabled, whether claude was on PATH when Polter started, and whether poltergeist-register-mcp is off.
- Describe the job directly to the supervisor. It can create the group, open tabs, claim terminals, and track timing without the user supplying terminal IDs or tool names.
- Open
Agents → Terminal Conversationsor run:
polter +chatUse tab and shift+tab to switch among the conversation, task panel, and statistics views. Defaults are usable as supplied: poltergeist-watch controls screen sampling, poltergeist-quiescence-after sets the still-screen notification delay, and poltergeist-register-mcp controls MCP registration at startup.
What are this agent's strengths and limitations?
- The supervisor operates independent terminal sessions, avoiding reliance on in-session sub-agents that may stop partway through long runs.
- It uses text-based screen access and a plain MCP interface; Polter itself requires neither an account nor an API key and does not need routine network access.
- Chat, task changes, terminal transcripts, and hourly statistics persist locally and remain inspectable after an application restart.
- It retains Ghostty's renderer, VT implementation, font stack, and native UI while adding the MCP surface, chat TUI, transcripts, and plugin host.
- Permission boundaries are deliberately conservative: it will not answer an agent's permission prompt or let an agent remove a user-applied hold or shield.
- Only Claude Code has been tested. Codex is mentioned as a target workflow, but other MCP clients and the seven provisioning plugins should be treated as unverified.
- Stored conversations and terminal activity are not redacted, so
$XDG_STATE_HOME/polter/must be protected like sensitive shell history. - Quiescence detection measures only unchanged screen time and cannot reliably distinguish a stalled agent from one doing long-running work.
- It cannot resolve permission prompts or bypass an agent's own permissions, so unattended jobs may still pause for human input.
- The Windows port does not yet implement every core action, and Linux users receive no binary.
- The task panel intentionally tracks only ownership and completion; it is not intended to become a full task-management system.
How does this agent compare with similar options?
Compared with tmux, Polter adds MCP control, cross-tab text reading and input, still-screen notifications, persistent group chat, and a task panel rather than offering terminal multiplexing alone. Its relationship to Ghostty is not a rewrite or a competing terminal core: Polter directly forks Ghostty, retains its rendering, VT, font, and native UI layers, and adds src/poltergeist/, the MCP surface, chat TUI, transcripts, and plugin host.
Key facts side by side with the most closely related agents.
| Agent | Source review | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|
| Polter Terminal Agent Supervisor This agent | 80 · Good | ★ 11 | today | Zig | Claude Code |
| MassGen | 51 · Major gaps | ★ 1.1k | 3mo ago | Python | Codex · Claude Code · OpenAI API · Claude API |
| Spring AI Alibaba | 53 · Major gaps | ★ 11k | 8d ago | Java | — |
| tRPC-Agent-Go | 53 · Major gaps | ★ 1.8k | 2d ago | Go | OpenAI API |
How does FollowAgents rate this agent?
Why each dimension lost points
The design includes per-terminal tokens, a supervisor role, target-side shield/watch marks, plugin call allowlists, refusal to answer permission prompts, and user-initiated update checks. Network, logging, and credential flows are described in unusually concrete terms. Deductions apply because unmarked terminals are the open case, same-user processes are outside the security boundary, terminal sends lack per-action confirmation, logs are enabled by default with neither redaction nor retention, Windows log permissions are unverified, and plugin-settings permission hardening may fail with only a warning. Dependency-security evidence is limited to a fixed Zig version and major-version-pinned CI actions; no dependency audit, vulnerability scan, or mitigation record is shown. Typing and opening tabs have material effects but their scope and safeguards are documented; there is no general rollback for commands already sent or filesystem changes made by agents. Ghostty provenance, fork status, copyrights, and non-affiliation are clearly attributed.
The README, security document, CI workflow, and cross-platform adapter comparison are strongly consistent about behavior and platform boundaries. The comparison harness explicitly checks exit codes, byte-level JSON, and narrowly justified normalizations, supporting full self-consistency credit. Requirements and failure-prone environment details are documented, with macOS tests and a Linux core build in CI, but only Claude Code is tested, Linux supervision is unverified, and much Windows behavior is inferred from code. The FAQ, explicit refusals, resolution failures, and harness diagnostics provide useful failure messages, although the supplied material does not establish uniformly actionable diagnostics across every runtime path.
The source clearly addresses multi-session Claude Code/Codex supervision, overnight work, and later transcript review, while distinguishing terminals, supervisors, workers, task panels, and ordinary sub-agents. Capability limits and non-goals are thorough: it does not decide that an agent is stuck, answer permission prompts, bypass agent permissions, or become a full task system. Triggering is generally precise, but screen stillness is only a signal and distinguishing thought from failure remains the supervisor model's judgment; displayed content can also trigger prompt-injection behavior. macOS, Windows, and Linux differences are documented, but Linux has no binary and is unverified, Windows lacks some actions, and non-Claude clients are merely claimed compatible through MCP rather than tested.
The README has strong navigation across downloads, quick start, settings, FAQ, upstream relationship, and design documents. Prerequisites, platform installation, a concrete verification prompt, and troubleshooting are well covered. Limitations—including indefinite unredacted logs, prompt injection, no audit or RPC fuzzing, and incomplete platform validation—are stated plainly. The complete MIT text attributes upstream and fork contributors. Naming mixes Polter, poltergeist, and GHOSTTY_POLTER_* identifiers, reducing naming stability somewhat. A latest-release link and update mechanism exist, but no versioning policy or changelog evidence is supplied. Maintenance scope, private vulnerability reporting, and the one-author situation are explicit, while response commitments and a broader maintenance plan are absent.
The group conversation, restart-persistent task panel, statistics view, text transcripts, and stillness indicators are immediately usable outputs for supervising multiple terminals. Compared with ordinary terminal multiplexing, cross-tab reading and typing plus agent coordination provide substantial marginal value. The cost-benefit score is reduced because this requires a large Ghostty fork, an additional supervisor session, and persistent local records while introducing prompt-injection and terminal-control risks; the supplied static evidence also contains no user study or quantified productivity outcome.
SECURITY traces most mechanical claims to specific files, functions, and lines and explicitly defers to code when prose disagrees. The README, license, CI workflow, and adapter comparison script independently reinforce platform status, provenance, test scope, and behavioral boundaries. Facts, design decisions, observations, unverified points, and work not performed are carefully separated—especially the distinction between code review, audit, and machine testing—so all three verifiability criteria are thoroughly supported by the supplied static evidence.
- Terminal and chat logging are enabled by default, unredacted, and retained indefinitely. They may contain API keys, tokens, paths, and command output; effective Windows file permissions should be verified first.
- A supervisor places text from worker screens into the model context without a trust boundary or injection marker. Untrusted web content, build output, and commit messages can therefore induce supervisor actions.
- Any caller holding a valid terminal token can reach an unmarked terminal, and other processes running as the same user are outside the isolation boundary. Apply watch/shield marks deliberately and treat plugins as local executable programs.
- No security audit, RPC fuzzing, or real Linux supervision test is reported. Windows log permissions and most Windows behavior also lack machine-level verification.
- The distributed macOS build is unsigned and the installation instructions remove quarantine. Independently verify the artifact, revision provenance, and available checksums before doing so.
FAQ
Does Polter require another account, API key, or network connection?
Why are the Polter tools missing from the supervisor session?
claude not being on PATH when Polter started, or poltergeist-register-mcp being disabled. MCP registration points to whichever build started most recently.