Polter Terminal Agent Supervisor
Put one Claude Code session in charge of independent agents running in other terminal tabs.
- Source repo
- Lugia123/polter
- Stars
- ★ 20
- Last updated
- today
- License
- MIT
- Primary language
- Zig
- FA score
- 47/100 · Major gaps
At a glance
- How it runs
- Works with
- Portable with changesClaude CodeCodex (Partial support)
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- 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.
- Not a fit if
- Teams wanting unattended long runs: permission prompts still need a human
- Linux users: no official binary, source build only
- Teams needing a full task-management system: the panel tracks only ownership and completion
- Source review
- 47/100 · Major gaps
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 | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Polter Terminal Agent Supervisor This agent | 47 · Major gaps | Desktop appFree + model costs | ★ 20 | today | Zig | Claude Code |
| MassGen | 50 · Major gaps | CLIFree + model costs | ★ 1.1k | 4mo ago | Python | Codex · Claude Code · OpenAI API · Claude API |
| tRPC-Agent-Go | 56 · Major gaps | Library / SDKFree + model costs | ★ 1.9k | today | Go | OpenAI API |
| BeeAI Framework | 50 · Major gaps | Library / SDKFree + model costs | ★ 3.5k | 5d ago | Python | — |
How does FollowAgents rate this agent?
Why each dimension lost points
SECURITY.md describes token authentication, supervisor authorization, shields, and local socket restrictions; the README also documents a switch to disable proxy approvals. Least privilege, confirmation, and rollback receive partial credit because the same evidence says screenshots are available by default to any agent holding a token and prompt authorization starts enabled. Data flows are explained through local storage, event filtering, and a user-triggered update request. Sensitive-data protections are less complete in the supplied evidence. Dependency security is only partially covered by build and dependency context, with no visible vulnerability-response process. Security documentation distinguishes code claims, limitations, and roadmap inference; Ghostty and its license are attributed.
The development guide gives detailed examples of test-filter pitfalls, build races, and watchdog behavior, but broad README product claims are not corroborated item by item by the supplied static source sample, limiting self-consistency credit. CI shows build and test configuration, but the evidence does not establish availability of all external tools and runtime environments. The plugin silently drops events on subprocess errors, avoiding host blockage at the cost of failure visibility.
The README targets developers coordinating agents across terminal sessions and describes supervisor, worker, and common CLI scenarios. SECURITY.md explains boundaries for supervisors, plugins, and unmarked terminals, though default screenshot access and prompt authorization make the defaults less restrictive. The sampled skill has a clear activation condition, but one commit-message skill cannot establish trigger precision across the product. Installation notes cover macOS, Windows, and Linux source builds; platform gaps, unsigned macOS setup, and plugin version requirements limit the score.
The README is organized around installation, quick start, features, security, architecture, and FAQ, with platform instructions and examples. The MIT license and upstream copyright attribution are clear. Known limitations include the Linux screenshot module not yet being ported, plugin version constraints, and silent event drops. Versioning and maintenance responsibility are only thinly evidenced, and the sampled skill covers commit messages rather than proving stable naming and navigation across all skills.
The task board, group chat, terminal inspection, and resource panel offer usable outputs for multi-agent coordination, and the README describes a practical workflow. Credit is limited because the supplied evidence does not establish the cost-benefit of the advertised automation, continuous delivery, or performance claims for ordinary use. Reading and typing into peer terminals also means utility depends on careful configuration.
SECURITY.md ties many claims to functions and code paths, while the plugin source explains event filtering, session ownership, and queue behavior. The documentation says code takes precedence and separates measured observations from inference. Scores are limited because this is a partial source sample: many README performance, security, and comparison claims lack corroboration across supplied sources, and static review cannot verify runtime behavior.
- SECURITY.md says screenshot access is enabled by default for agents holding a token; review screenshot access and terminal shields carefully.
- Supervisor prompt answering is enabled by default. The README says high-risk actions are escalated, but the supplied sample cannot verify how that classification works.
- The opencode plugin silently drops events when the Polter subprocess fails; account for this when relying on continuous status reporting.
- The README makes broad performance, security, and competitor-comparison claims that this static source packet cannot independently verify.
Maintain this project? Add the FARS badge to your README
[](https://followagents.com/en/agents/polter)<a href="https://followagents.com/en/agents/polter"><img src="https://followagents.com/badge/polter.svg" alt="FARS review"></a>Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v0.11.2239 Polter 0.11.2239
Release notes excerpt
Polter 0.11.2239 — 53 commits since 0.11.2186, all of them this project's own. No upstream merge is in this one. The control room - Performance, tasks and chat pages beside the supervisor page, on macOS and on Windows, drawn from the core's answers. - The tasks page: a key bar under the list, a selected row that shows, hover, f to filter by title with the matches marked, closed tasks hidden and said so, and the list following the selection. On macOS a long list no longer redraws every row on every update, so scrolling it with a task open no longer drops frames. …View on GitHub ↗ -
v0.11.2186 Polter 0.11.2186
Release notes excerpt
Polter 0.11.2186 — 51 commits since 0.10.2135, all of them this project's own. No upstream merge is in this one. Supervisors and workers - A project has one supervisor. Adding a second to its group is refused while the first is still minding it. - Workers stack to the supervisor's right. The first worker splits the supervisor's pane to the right, and every worker after it is stacked in front in that pane. Panes you opened yourself are never stacked into. Two launches close together: the second waits up to three seconds for the first. …View on GitHub ↗ -
v0.10.2135 Polter 0.10.2135
Release notes excerpt
Polter 0.10.2135 — 130 commits since 0.10.2005, all of them this project's own. No upstream merge is in this one. More agent CLIs - Codex. A role can start Codex, and Polter learns its turns and approvals through Codex's own hooks, on macOS and on Windows. A Codex taken over goes on with its own session, and never with somebody else's: when Polter cannot tell which session in a directory is this one, it names none. Codex's skills and rules go under CODEX_HOME. - Antigravity CLI (agy). A supervisor or a worker can be agy. Polter never …View on GitHub ↗
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.Can it approve permission prompts or remove terminal locks automatically?
How does Polter decide that an agent is stuck?
Can I use an agent CLI other than Claude Code?
Thanks — we use this to improve the page.