Vigil Multi-Agent Terminal Orchestrator
Run manager-led coding-agent trees while preserving every CLI's native terminal, history, and permission flow.
Per-dimension scores and reasoning
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.
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.
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 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.
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.