agent stack - Moses Yebei

The Problem

Co‑ordinating multiple AI agents to build, test, and merge code is error‑prone when each agent is a separate process with its own tooling. Existing approaches require manual queue management, duplicated configuration, and fragile hand‑offs. The result is slow feedback and a high risk of merge conflicts.

What This Does

agent‑stack turns a single Linux box into a fully‑automated software team. The operator agent, visible in console/src/main.ts, talks to the user, creates a project template in rig/template/, and hands out git worktrees (“seats”) that run the appropriate LLM (Claude, Codex, or GPT‑6) through @openrig/cli. Each seat writes its own activity to a shared history file, while the console in console/ shows a read‑only overview of the fleet: Mission Control, Seat Matrix, River, and Focus.

The merge gate is enforced by Jev (jev/lib/engine.js) which evaluates a set of typed decisions: CI status, cross‑family review, QA verdict, and a live Jev decision. A PR is merged only when all verdicts agree.

How It Is Wired

Entry point: console/src/main.ts launches the full‑screen UI.
Internal call graph:
main.ts imports draw.ts, term.ts, views/*.ts, history.ts, and model.ts.
draw.ts renders the Mission Control layout and subscribes to the shared history file (console/src/data.ts reads console/src/history.ts).
term.ts exposes a read‑only terminal view that connects to the seat’s tmux session via the agent‑* scripts in bin/.
model.ts pulls the current state from the rig/template and config/*.json, and feeds it to the view layer.

What this code touches outside itself:
File system: writes to console/src/history.ts and reads the seat logs under each seat's worktree.
Network: each seat runs @openrig/cli which talks to the OpenRig daemon (bin/openrig-daemon-cycle) and to the LLM endpoints defined in config/*.json.
External processes: the bin scripts invoke openrig and playwright to run tests or open a browser.

File responsibility:
console/ – UI rendering and history aggregation.
bin/ – command wrappers that launch OpenRig or Playwright.
rig/template/ – YAML/JSON templates for seat roles and defaults.
jev/ – typed decision engine.
config/ – LLM and proxy configuration.

The system has a single data source: the shared history file. All state changes propagate through that file, providing a narrow blast radius for modifications.

How To Use It

Setup ``bash git clone https://github.com/moses-y/agent-stack cd agent-stack npm install ``
Configuration - Edit config/claude-proxy-settings.json to point to your OpenAI credentials. - Set OPENRIG_WORKSPACE to a directory where seat worktrees will live.
Running ``bash npm run start:console ` (This runs console/src/main.ts via ts-node.) To onboard a repo: `bash bin/agent-project-new shop ``

Real‑World Use

A dev in a product team runs agent-claude-trust to verify that an operator seat can safely use the trusted Claude model. Then they run rig-console --fixture docs/fixtures/demo-fleet.json to observe a demo fleet. The operator writes a feature request, the team plans, writes tests first, builds, and the merge gate automatically approves the PR. After merge, agent-waves-sync deploys to staging, and the witness seat runs the fresh agent on the deployed app.

Code Health & Issues

Low – Secret‑shaped paths present (docs/incidents/2026-09-30-playwright-secrets.md).
Med – No license file found; CI is only a single test workflow (.github/workflows/test.yml).
Low – Tests cover only 23 % of JavaScript functions (test/ contains 79 files).

These counts come from the static audit reported in the repo. No additional critical issues were found.

The Bottom Line

agent‑stack offers a pragmatic, low‑friction way to orchestrate AI‑driven development on a single host. Its strengths lie in the tight coupling between the console UI, seat templates, and Jev decision engine. The main trade‑offs are the lack of a formal license and limited test coverage, which may concern security‑critical teams. It is best suited for internal tooling where a single Linux machine can run multiple LLMs and where the devs are comfortable with the existing configuration files.

What the analyser found

Deployment readiness

5/7

Container image
CI pipeline
Lockfile committed
Test suite
README
License
No committed secrets

Composition

367 files

Markdown90
JavaScript78
YAML24
JSON23
TypeScript14
Shell6

React

Architecture

Top-level areas of the codebase, sized by module count. Arrows show how many imports cross from one area into another.

graph TD g0["test 60 modules"] g1["console 14 modules"] g2["orchestration 8 modules"] g3["jev 6 modules"] g4["docs 3 modules"] g5["proxy 2 modules"] g2 -->|4| g3 g0 -->|1| g2

Module dependencies

The 10 most depended-upon modules of 95, from static import analysis. Red outline marks a module in an import cycle.

graph LR n0_console_src_term["term"] n1_console_src_model["model"] n2_console_src_draw["draw"] n3_console_src_views_chrome["chrome"] n4_jev_lib_engine["engine"] n5_console_src_theme["theme"] n6_console_src_history["history"] n7_orchestration_lib["lib"] n8_jev_lib_store["store"] n9_console_src_views_home["home"] n2_console_src_draw --> n0_console_src_term n2_console_src_draw --> n5_console_src_theme n6_console_src_history --> n1_console_src_model n5_console_src_theme --> n0_console_src_term n3_console_src_views_chrome --> n0_console_src_term n3_console_src_views_chrome --> n5_console_src_theme n3_console_src_views_chrome --> n1_console_src_model n3_console_src_views_chrome --> n2_console_src_draw n9_console_src_views_home --> n0_console_src_term n9_console_src_views_home --> n2_console_src_draw n9_console_src_views_home --> n1_console_src_model n9_console_src_views_home --> n6_console_src_history n9_console_src_views_home --> n3_console_src_views_chrome n4_jev_lib_engine --> n8_jev_lib_store n7_orchestration_lib --> n8_jev_lib_store

Dependencies

1 of 4 declared dependencies are a major version behind. Resolved 4 of 4 against the registry.

Package	Declared	Latest	Behind
`zod`	3.25.76	4.4.3	1 major

Findings

LowSecret-shaped paths present; the code-health audit confirms or clears them docs/incidents/2026-09-30-playwright-secrets.md

What would stop me shipping this

Ranked by severity × confidence × production reach. Reach is the honest discriminator across a collection that is mostly other people's code: the same finding matters more in something that ships.

high2

medium3

low1

Add a LICENSE; redistribution rights are undefinedhigh

no licence file at the repository root

Fix: Add MIT or Apache-2.0 at the repository root.

Make CI invoke the test suite it hashigh81 occurrences

.github/workflows

81 test files, no test command in any workflow

A green check that never executed an assertion is worse than no check, because reviewers trust it.

Fix: Add a test step to the existing workflow rather than a new workflow.

Enable Dependabot or Renovatemedium

1 manifest(s), no update bot configured

Without a bot a published advisory sits unpatched until someone audits by hand, which across 1,322 repositories means never.

Fix: Commit .github/dependabot.yml covering the repo ecosystems plus github-actions.

Gate pull requests on a dependency vulnerability scanmedium

.github/workflows

no dependency scan in CI

This is the one gate that would catch a known-vulnerable package before it reaches a build, and no repository in the sample had it.

Fix: Add dependency-review-action on pull_request, or osv-scanner on push and a schedule.

Set persist-credentials: false on checkoutmedium

.github/workflows/test.yml

checkout keeps the token, then dependencies are installed

The token stays in .git/config for every later step, so a malicious postinstall script reads a pushable credential without one ever being passed to it.

Fix: Add with: persist-credentials: false, and pass an explicit token only to the step that pushes.

Add the repository convention files this project lackslow3 occurrences

missing .editorconfig, .gitattributes, a formatter config

Without them one contributor's editor writes tabs into a Python file, a shell script commits with CRLF and fails in the container, and a notebook diff is unreviewable.

Fix: Add .editorconfig, .gitattributes with text=auto eol=lf, and a formatter config.

Checked deterministically against the repository tree and a bounded set of its files: committed credentials, unpinned actions and base images, missing lockfiles and update bots, workflows that discard failures, published advisories against the declared dependencies, runtime configuration, licensing and notebook reproducibility. No language model is involved in this section.