Vekhyat Jain
Back to the map

agent-hub

A command-line tool that lets one coding agent start other agents as helpers, give each of them a task, and collect their reports.

Status
Working and open source
My role
Solo. I designed and wrote it
Built with
Python
Runs on
Linux with a graphical session

Where it began

A coding agent usually works alone: one task, one window, one line of thought. I was curious what changes when an agent can split up a job and hand parts of it to others: a reviewer, someone to write the tests, a second opinion on a design. Handing out the work is only half of it. The other half is getting the answers back, reliably.

I also wanted to see every helper while it works, instead of letting it run somewhere out of sight. So each helper gets its own terminal, where I can watch it and type into it whenever it needs me.

What it does

You ask your agent in plain words and name agent-hub. The agent then runs the commands itself.

You:     Use agent-hub to have Codex review this branch while you write the tests.

Agent:   $ agent-hub spawn codex reviewer 'Review this branch and list the top issues' --cwd ~/app
         ...writes the tests...
         $ agent-hub wait --timeout 900
         [reviewer done; closed]
         1. Race in cache.py:88 ...

Each helper is a real, interactive Claude Code, Codex, OpenCode, or Grok session, signed in with the accounts you already use. The agent doing the asking can be any of these too, or anything else with a shell.

How it works

  1. Start a helper. agent-hub spawn opens a terminal window with a real session in the chosen project directory, and returns the helper’s screen, so the caller can see any sign-in or permission prompt waiting for it.
  2. Brief it. The hub adds a short note to the helper’s first prompt: when finished, report with agent-hub done ID "result"; if unsure, ask with agent-hub tell ID "question".
  3. Wait on many at once. agent-hub wait returns whichever report comes in first, from any helper, and points out a helper that is stuck at a permission dialog.
  4. Come back to it later. resume reopens a finished helper’s conversation, so you can go back and ask it to check a fix.

Choices I made

  • Reports, not screen scraping. The caller never has to read a helper’s screen and guess whether it is done. Claude and Codex helpers also send a report on their own whenever a turn ends.
  • Only a command-line tool. No server, no tool schemas, no tmux, nothing running in the background. A small skill teaches agents the commands, and it loads only when you mention agent-hub.
  • Your logins stay yours. Every sign-in goes through that tool’s own browser flow. The installer never reads credential files, and it never replaces an agent-hub command it did not put there itself.
  • Leave nothing behind. On a systemd user session, closing a helper reliably cleans up every process it started.

Where it stands

It works on Linux, in Foot, Ghostty, Kitty, Alacritty, WezTerm, or xterm, and needs Python 3.12 or newer. Beyond that I haven’t tried it: other platforms are untested.

Source and install instructions on GitHub