Overview¶
Nexus turns a private GitHub repository into the control surface for a long-running multi-agent coding session on a Linux host. The agents run inside a tmux session under agent-sandbox; the operator drives them from anywhere there's a GitHub-mobile push notification.
The problem nexus is built for¶
Modern AI coding agents have become capable enough to do real, multi-hour work — but their interaction model assumes the operator is sitting in front of a terminal the whole time. That's a poor fit for:
- Multi-day research codebases where a single experiment, refactor, or paper-figure rebuild spans many hours of agent thinking, intermittently needs a human nudge ("skip the slow preprocessing", "use the cached embeddings"), and must survive SSH drops, browser tab closes, and operator sleep.
- Lab- and group-scale workflows where one person coordinates several parallel agent tasks across a shared codebase, often from a phone in between meetings.
- Hosts with already-established constraints — Slurm clusters, lab GPUs, paid compute — where the agent has to run where the code, data, and credentials already live.
Nexus solves the coordination layer: agents run as long-lived tmux windows on the operator's own host; a watcher loop turns local state and GitHub comments into a paste-driven event stream; a GitHub App is the bot identity that posts the dashboard, reactions, and worker hand-offs back to GitHub so the operator's phone wakes them when the agents need a decision.
Who it's for¶
You're a likely fit if all of these are true:
- You're already running AI coding agents (Claude Code today; the architecture is agent-agnostic) on real, multi-step engineering work.
- You have a Linux host you can leave running indefinitely — a lab workstation, an HPC interactive node, a personal server. Nexus assumes a long-lived tmux session; ephemeral CI containers are the wrong shape.
- You have GitHub admin on a private repo and can install a GitHub App you create.
- You're comfortable editing a YAML config, generating an RSA key for a GitHub App, and running shell scripts.
You're probably not a fit if:
- You want a turnkey hosted product — nexus is code you run on your own Linux host; there is no service to sign up for.
- You want multi-user access to one bot — the eligibility filter authorizes exactly one GitHub login as the directive source; siblings ignored.
- Your security model can't tolerate
--dangerously-skip-permissionson Claude Code, even inside agent-sandbox's bubblewrap boundary. The orchestrator is launched with that flag; the filesystem blast radius is bounded by the sandbox but network and compute side effects are not.
Scope boundaries¶
A few things nexus deliberately is not, so expectations stay calibrated:
- One operator per instance.
github.user_loginconfigures the single authorized operator. The eligibility filter inmonitor/watcher/main.shrejects every other author by construction, so the bot cannot be hijacked by repo collaborators leaving instructions. - Not a CI replacement. Nexus is for human-supervised research and refactoring work where the agent's judgment is the point. CI is for deterministic, scripted checks; nexus is the layer above.
- Not a security product. agent-sandbox provides filesystem isolation, not network or compute isolation — see Admin → Security. The bot's authorization scope is
github.user_loginonly; sub-tier policies for external public repos live inCLAUDE.md's "GitHub writes — identity and authorization" section.
Architecture in three sentences¶
A watcher bash loop polls local state and GitHub once per cycle (default 60s, monitor.interval_seconds) and pastes a state-change report into the orchestrator's tmux pane. An orchestrator Claude Code session reads each report, posts 👀 / 🚀 reactions through a GitHub App bot, updates the pinned dashboard issue's body, and either replies in-thread or spawns a worker in a fresh tmux window. Workers do the actual code work and hand off via monitor/ng wrap-up, which uploads a structured report to the asset+issue repo, comments on the issue, and rockets the trigger comment.
For the full architecture diagram and the watcher's emit classifier semantics, see Reference → Architecture. For the day-to-day operator playbook, see Operating → Overview.
Prerequisites¶
You'll need the following before the Install walkthrough. None are unusual; most are already on a typical research host.
- A Linux host you can leave a tmux session running on. Persistent SSH-able machine — workstation, HPC interactive node, dev server. Walltime-limited compute (most batch queues) is the wrong shape; the orchestrator must survive hours-to-days idle.
agent-sandbox. Kernel-enforced filesystem sandbox. Installed per-user withbrew install agent-sandboxafterbrew tap katosh/tools. Required.- A GitHub account with admin on a private repo. You'll create a private repo to host issues and assets, and a GitHub App to act as the bot. Both belong to you (or your org).
- Claude Code. Today's reference orchestrator. The architecture is agent-agnostic but the launch prompt assumes Claude Code; other harnesses need a re-port.
- The
ghCLI. The binary is a hard runtime dependency —monitor/ngshells out togh apifor every GitHub call. Authenticating it as your GitHub user is optional: the bot supplies its own GitHub App token, and your personal auth is only used for the one-time asset-repo creation (which has a browser fallback). - A handful of standard shell tools —
bash,tmux,git,gh,jq,openssl,python3withpyyaml,curl. Listed inmonitor/README.md"Tech stack".
Optional but recommended:
- A phone-push channel — Pushover (preferred), ntfy (fallback), or email (emergency tier). Configured under
notifications.*inconfig/nexus.yml. See Operating → Notifications. labsh— project-local JupyterLab with persistent kernels. Worth installing if any of your projects load slow-to-build state (large DataFrames, fitted models) that agents would otherwise rebuild every turn.