Vigil Multi-Agent Terminal Orchestrator
Run manager-led coding-agent trees while preserving every CLI's native terminal, history, and permission flow.
- Source repo
- butterlatte-zhang/vigil
- Stars
- ★ 28
- Last updated
- 29d ago
- License
- GPL-3.0
- Primary language
- Swift
- FA score
- 69/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformCodex · Claude Code
- Cost
- Free software; you pay for model usage
- Setup effort
- Medium · a few setup steps
- You'll need
- Typical use
- A developer handling several independent issues can assign each issue to a worker and place a more complex issue under a sub-manager that decomposes it further.
- Not a fit if
- Developers on Windows, Linux, or Intel Macs
- Users who want a graphical settings panel instead of JSON config files
- Organizations that cannot comply with GPL-3.0 licensing terms
- Source review
- 69/100 · Some gaps
What does this agent do, and when should you use it?
Vigil is a native macOS terminal application that organizes Claude Code, Codex, and OpenCode processes into manager-led trees. Every node runs the actual agent CLI in a managed PTY and retains its native TUI and session history, so the application does not answer prompts or approvals for the user. Root and sub-manager nodes delegate and communicate through MCP-backed spawn, send, kill, and report operations, while results return upward as summaries. A unidirectional SessionStore processes Command and Effect values, and cross-subtree traffic passes through the lowest common ancestor to prevent cycles. Vigil persists orchestration events and node transcripts locally for read-only replay and native CLI resume, making it most suitable for developers who want structured parallel coding work and can accept its macOS 14+, Apple Silicon boundary.
The user opens a project, selects a detected Claude Code, Codex, or OpenCode entry, and gives the root manager a task through the central native terminal. Vigil launches each CLI in a managed PTY: a root receives the MCP operations spawn, send, and kill; a sub-manager also receives report; and a leaf worker receives report only. Managers can create further managers or workers, send task detail down the tree, and collect completion summaries upward; messages between subtrees route through their lowest common ancestor. Every mutation enters the single SessionStore as a Command and exits as an Effect, while the UI only reads store state. Vigil writes the orchestration event stream and each node transcript under ~/Library/Application Support/Vigil/sessions/<id>/, reconstructs completed trees for read-only inspection, and resumes them through claude --resume, codex resume, or opencode --session. Agent registry, role, prompt, runtime, and appearance settings are maintained as JSON files under ~/.config/vigil/.
- A developer handling several independent issues can assign each issue to a worker and place a more complex issue under a sub-manager that decomposes it further.
- A team already using Claude Code, Codex, or OpenCode can combine those CLIs in one orchestration tree without replacing their native terminal interfaces.
- A maintainer who needs an audit trail can reopen a completed session, reconstruct its node tree, and inspect the full transcript of any node.
- A user concerned about exhausting the root manager's context can keep implementation detail in lower nodes and roll only summaries back up.
- A project that needs an explicit isolation policy can share a working directory with assigned file ownership or use git worktree without accepting a hidden branching strategy.
How do you install or deploy this agent?
Recommended installation: download https://github.com/butterlatte-zhang/vigil/releases/latest/download/Vigil-macos.dmg, open the DMG, and drag Vigil into Applications. If macOS asks for confirmation on first launch, choose Open. The runtime requirements are macOS 14 or newer, Apple Silicon, and at least one claude, codex, or opencode CLI available on PATH.
Building from source requires Xcode 26.2 and Swift 6.2.3:
git clone https://github.com/butterlatte-zhang/vigil.git
cd vigil/app
swift run VigilNo separate Vigil credential is documented; an installed, usable agent CLI is a prerequisite.
How do you use this agent?
On first launch, Vigil probes PATH in the order claude, codex, then opencode and seeds its agent registry with the detected CLIs. If none is found, the launcher displays a warning. Add or open a project, select an available agent in the launcher, and type a task into the central terminal to start the root manager. Use the live node tree to inspect or switch nodes, and enter any node's native TUI when direct intervention is needed. Completed sessions remain grouped by project in the sidebar: click one for read-only replay, or press Enter to resume it through the corresponding CLI's native mechanism. Edit ~/.config/vigil/agents.json, roles.json, and launcher.json to change agents, roles, or defaults; runtime and visual settings live in runtime.json and appearance.json.
What are this agent's strengths and limitations?
- Its manager-worker hierarchy sends detail downward and summaries upward instead of treating every terminal as a peer, limiting the context carried by high-level managers.
- Claude Code, Codex, and OpenCode can participate in the same tree while retaining their own TUI, permission handling, and session-resume mechanisms.
- Per-node transcripts and spawn, send, kill, and report events are persisted, allowing the original tree and each node's activity to be audited later.
- The MCP operation surface is scoped by node identity, giving roots, sub-managers, and leaf workers different structural permissions.
- File-based configuration and optional git worktree isolation avoid imposing a hidden sandbox, branch strategy, or model selection policy.
- The documented build runs only on Apple Silicon Macs with macOS 14 or newer; no Windows, Linux, or Intel Mac deployment is provided.
- Vigil is explicitly pre-1.0 and under active development, with rough edges and a configuration surface whose defaults may continue to change.
- At least one supported agent CLI must already be installed; Vigil does not provide its own model runtime, and undetected CLIs are unavailable.
- Single-parent routing and cascade-kill deliberately constrain collaboration to a tree, so it does not fit workflows that require an open peer-to-peer mesh.
- There is no graphical settings panel; paths, environment variables, roles, models, and runtime behavior are configured through JSON files.
- GPL-3.0-or-later obligations may be unsuitable for some organizations, which would need to evaluate the separately referenced commercial license.
How does this agent compare with similar options?
Compared with manually opening multiple terminals, pasting prompts, and carrying results between agents, Vigil maintains the task hierarchy and result routing itself. Compared with side-by-side peer sessions that each retain full context, it favors deeper orchestration, single-parent routing, and rolled-up summaries; the corresponding tradeoff is a fixed tree topology rather than an open communication mesh.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Vigil Multi-Agent Terminal Orchestrator This agent | 69 · Some gaps | Desktop appFree + model costs | ★ 28 | 29d ago | Swift | Codex · Claude Code |
| Open Swarm | 40 · Major gaps | — | ★ 827 | 1mo ago | JavaScript | Claude API |
| pitwall | 70 · Some gaps | — | ★ 19 | 1d ago | Go | Codex · Claude Code |
| zerostack | 57 · Major gaps | CLIFree + model costs | ★ 1.7k | 3d ago | Rust | OpenAI API · Claude API |
How does FollowAgents rate this agent?
Why each dimension lost points
The README gives substantive least-privilege evidence by scoping MCP tools by role: root managers receive spawn/send/kill, sub-managers also receive report, and leaves receive report only. It also says native CLIs retain their own permission mechanisms, unavailable CLIs are not advertised, failed delivery produces an error, and local configuration/session paths are disclosed. Deductions apply because agents.json may contain keys and environment variables without documented permissions, encryption, redaction, retention, or cleanup controls; no dependency lock, security scan, or SBOM evidence is supplied, and workflow actions use mutable version tags rather than commit hashes. Per-operation confirmation for kill and cascade-kill is unclear, replay cannot undo filesystem or other external changes, and the unknown publisher is accompanied by no explicit author identity or security contact in the supplied files.
The source describes CLI probing, warnings for missing agents, direct process invocation, native resume commands, and explicit delivery failures. It also includes deterministic push/PR CI and release-time signature and launch checks on macOS 14 and 15, supporting ordinary dependency and failure handling. The main deduction is a material internal inconsistency: the README says Vigil never supplies approval keystrokes, while the mechanism test explicitly intercepts, decides, and injects approval, and the Claude hook automatically allows or denies operations. These may be historical experiments, but their status is not identified. Failure messages are demonstrated only selectively, and comprehensive recovery behavior is not shown.
The intended audience, parallel coding-agent scenarios, and tradeoff between a hierarchy and an open mesh are described thoroughly. Claude Code, Codex, and OpenCode can be mixed, while roles, models, arguments, environment variables, prompts, runtime settings, and project overrides are configurable. Role tool boundaries and single-parent routing are explicit, and macOS requirements are precise. Trigger precision loses a point because the files define structural permissions but do not comprehensively specify when an agent should semantically invoke spawn, send, kill, or report, or how mistaken invocations are prevented.
The README has strong organization across features, installation, configuration, architecture, shortcuts, replay, status, contribution, and licensing. DMG and source installation instructions specify macOS, architecture, toolchain, and CLI prerequisites. The GPL-3.0-or-later statement is backed by a full GPLv3 license text. Deductions apply because the project is explicitly pre-1.0 with moving configuration and defaults, without a migration commitment; examples are useful but there is no dedicated FAQ or systematic troubleshooting section; no versioned changelog is supplied; and contribution channels exist without clearly identifying maintainers, support expectations, a security-reporting route, or release responsibility.
Native TUIs, a live agent tree, upward summaries, transcript replay, node revival, notification navigation, and file-based configuration form a practical orchestration workflow. Hierarchical routing, mixed CLI support, and an audit trail offer clear marginal value over manually shuttling messages between terminals. Cost-benefit is deducted because multi-agent operation can multiply model, context, and supervision costs, while the release workflow itself notes elevated macOS runner costs; the supplied material provides no resource caps, budget controls, performance measurements, or scaling limits.
Several claims are tied to concrete configuration files, role-tool mappings, persistence paths, CI, and release-verification workflows. The test files additionally illustrate PTY approval handling and a structured Claude hook, providing some cross-file corroboration. Deductions apply because the supplied evidence omits the core Swift implementation, detailed assertions, and test results, so claims such as unidirectional state flow, lowest-common-ancestor routing, exact history reconstruction, and honest delivery cannot be traced end to end. Promotional claims are not always separated from demonstrated facts, and the auto-approval tests conflict with the current README positioning without explanation.
- The project is pre-1.0 and explicitly warns that configuration surfaces and defaults will move; pin a release and assess migrations before production adoption.
- agents.json may contain agent keys, base URLs, and other environment variables. No encryption, restrictive-permission, or log-redaction policy is documented, so treat it as sensitive plaintext configuration.
- Persisted sessions include full terminal transcripts and orchestration events that may contain source code, prompts, secrets, or command output; no retention, deletion, or redaction policy is supplied.
- The README's claim that Vigil never supplies user input conflicts with tests that auto-decide approvals and inject keystrokes. Confirm whether those mechanisms ship in production and whether they are enabled by default.
- Replay and resume are not transactional rollback and cannot reverse changes made by agents to repositories, network services, or other external systems.
- Support is limited to Apple Silicon on macOS 14 or newer, and users must separately install, authenticate, and maintain at least one supported agent CLI.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
v0.1.7 Vigil 0.1.7
Release notes excerpt
Fixed - A spawned Codex worker's first prompt no longer sits unsubmitted in its composer. Vigil typed the task, waited 150 ms and pressed Enter without ever checking that the Enter took. Codex started on a fresh CODEX_HOME (every Vigil node gets one) draws its composer almost immediately but swallows an Enter that arrives in the first seconds of startup, so the pasted task stayed in the box until a human pressed Enter. Injection is now closed-loop: Vigil waits for the pasted text to land and stop changing, presses Enter, confirms the box emptied, and if not re-presses Enter with back …View on GitHub ↗ -
v0.1.6 Vigil 0.1.6
Release notes excerpt
Fixed - Switching to a worker or sub-manager no longer fills Claude Code's input box with an old prompt. A node that was born in the background gets its terminal surface reconstructed from the parser's screen state on first select. That reconstruction carried the alternate screen but not the mouse-tracking, focus-reporting, cursor-key and keypad modes the agent had enabled, so the surface believed mouse tracking was off while the alternate screen was on. In that state the terminal converts every scroll-wheel tick into an Up/Down cursor key, and Claude Code reads Up as history recall. T …View on GitHub ↗ -
v0.1.5 Vigil 0.1.5
Release notes excerpt
Fixed - Report watchdog no longer nags workers that are legitimately waiting. A worker whose turn ended with background subagents still running (claude's turn_duration line reports pendingBackgroundAgentCount > 0) is no longer reminded to report; the decision is also deferred by a short grace so it reads the transcript line claude writes *after* the Stop hook fires. In an audit of 142 local sessions about 30% of reminders hit exactly this state and produced "still in progress" filler in the manager's context. …View on GitHub ↗