Problem Large codebases often stall when CI fails or reviewers request changes. Teams must manually spawn fix‑up branches, run tests, and keep track of multiple PRs. The current workflow is error‑prone and consumes developer time that could be spent on new features.

What This Does agent-orchestrator creates a self‑contained fleet of AI coding agents. Each agent runs in its own Git worktree, is paired with a runtime (tmux or Docker), and talks to a tracker (GitHub, Linear). Agents automatically fix CI failures, address review comments, and open PRs; a dashboard (http://localhost:3000) shows all sessions and only notifies humans when judgment is required. Core contracts live in packages/core/src/types.ts; plugins implement those contracts and are discovered via the plugin registry (packages/core/src/plugin-registry.ts). The CLI (packages/cli/src/index.ts) drives the orchestrator, while the core lifecycle manager (packages/core/src/lifecycle-manager.ts) coordinates session creation, monitoring, and teardown.

How It Is Wired

Execution start – packages/cli/src/index.ts parses CLI flags and calls start in packages/core/src/lifecycle-manager.ts (line 583).

Session creation – create (in packages/plugins/agent-aider/src/index.ts line 211, also used by other agents) builds the launch command via getLaunchCommand, then invokes tmux/docker through packages/cli/src/lib/shell.ts (exec, execSilent).

External effects – The shortest path to a file write is main → ensureServer → spawn → postLaunchSetup → setupCodexWorkspace → atomicWriteFile (creates a random secret via randomBytes(6).toString).

Network calls – Functions such as git, gh, and POST (found in shell.ts and plugin modules) issue outbound HTTP/Git commands; they are called 8‑10 times each across the codebase.

Blast‑radius hubs – packages/core/src/types.ts is imported by 13 modules; any change here ripples widely. packages/core/src/session-manager.ts (19 functions, 13 callers) orchestrates session metadata and is another hot spot.

Plugin flow – The registry (createPluginRegistry, register, get) loads each plugin’s PluginModule. Agents (agent-aider, agent-claude-code, agent-codex, agent-opencode) provide create*Agent functions that return a runnable process. Notifiers (e.g., notifier-composio) listen for events via the core event bus.

How To Use It

# Clone and install
git clone https://github.com/moses-y/agent-orchestrator.git
cd agent-orchestrator
pnpm install            # pnpm is the declared package manager

# Bootstrap a project (example in repo)
cd ~/my-project
ao init --auto          # reads agent-orchestrator.yaml.example

# Start the dashboard and spawn an agent
ao start                # launches the web UI on port 3000
ao spawn my-project 123 # 123 may be a GitHub issue, Linear ticket, or ad‑hoc ID

Configuration lives in agent-orchestrator.yaml (root) and follows the schema shown in the README. No additional environment variables are required beyond a GitHub token (GITHUB_TOKEN) for the gh CLI, which the CI workflow already supplies.

Real‑World Use A SaaS team integrates the orchestrator into their CI pipeline. When a nightly build fails, the CI job runs ao spawn service-api 456. The agent checks out a worktree, runs the failing test suite inside a tmux session, patches the code, commits, pushes a branch, and opens a PR. Reviewers receive a Slack webhook (via notifier-slack) only if the agent cannot resolve the failure, dramatically reducing manual triage time.

Code Health & Issues

  • High – Duplicated code blocks – Repeated 6‑line snippets across 78 files (packages/cli/__tests__/commands/*.test.ts, packages/cli/src/commands/*.ts). Fix: extract shared helpers.
  • Medium – Oversized files – packages/core/src/types.ts, session-manager.ts, and related tests exceed 700 lines; split by responsibility.
  • Medium – High branching density – metadata.ts, format.ts, lifecycle-manager.ts contain >57 branches in <200 lines; refactor to strategy tables.
  • Medium – Hub module – types.ts is a central dependency; keep it stable and consider moving volatile logic elsewhere.
  • Medium – Deep nesting – plugins/scm-github/src/index.ts and similar have indentation depth 6; flatten with early returns.

CI / Ops findings

  • Pin GitHub Actions to commit SHAs (high).
  • Declare least‑privilege GITHUB_TOKEN permissions (medium).
  • Enable Dependabot or Renovate (medium).
  • Pin Docker base images by digest (medium).
  • Add a dependency‑vulnerability scan step (medium).
  • Set persist-credentials: false on checkout (medium).
  • Define timeout-minutes on workflow jobs (low).

The Bottom Line agent-orchestrator provides a solid, extensible framework for autonomous AI agents that can keep CI green and PRs up‑to‑date. The architecture is well‑modular, but core hub files (types.ts, session-manager.ts) are large and highly coupled, making large‑scale changes risky. Addressing the duplicated‑code and branching‑density hotspots, plus tightening CI security settings, will improve maintainability and safety for production use. Suitable for teams ready to adopt AI‑driven code maintenance and comfortable working in a monorepo with pnpm and GitHub Actions.