ahub

Русская версия

Let an orchestrator hand work to worker models and spend its own context only on decisions.

agent-hub is a local service that sits between an orchestrator (Claude Code, or any CLI agent over MCP) and worker models. The orchestrator files a task and goes quiet. The hub runs the worker in its own git worktree, checks the result — a commit, a diff inside the allowed files, the acceptance tests — sends it to reviewer models in fresh sessions, retries failures, keeps the budgets, and wakes the orchestrator with one line when there is something to decide: accept, send back with notes, or reject. Nothing else reaches the orchestrator's context unless it asks for it: one event line, a summary capped at 4 KB, a one-word decision.

The short version of everything below is in the user guide.

How it works

flowchart TD
  C["Claude Code"] -->|"ahub task new"| S["ahub service: queue, budgets, events"]
  S --> W["worker model in its own git worktree"]
  W --> G{"gates: commit, diff inside paths, acceptance tests"}
  G --> R["review panel: reviewer models in fresh sessions"]
  R --> V{"all agree?"}
  V -->|"no — up to N rounds"| W
  V -->|"yes"| E["event DONE"]
  E -->|"ahub watch wakes Claude"| C
  C -->|"ahub accept / rework / reject"| S

The hub never merges on its own: the decision after done belongs to the orchestrator or to you. A network error is retried, silence gets one continuation, a quota limit waits for its window (or the fallback model), a timeout / budget limit turns into needs_decision — a task never hangs silently. Events are stored until they are acknowledged, so a restarted session or a closed terminal does not drop a "done".

See a task run

Features

Supported providers

The hub is not tied to any model. Any model a provider exposes can be added with ahub models add and given to a role with ahub models role; ahub setup probes what you actually have and picks the defaults.

What it costs

What follows is what work on this repository actually cost, at the tariffs it actually paid.

* The Opus column is the same token count — the ones the hub recorded for every session of the task — priced at Opus 5.5. Opus might finish the same work in fewer steps, so read it as an order of magnitude, not as a bill.

These are promotional rates (the opencode Go contributor tier, free models). They can change or end; free models can also be rate-limited or disappear — the hub probes them (ahub models check) and falls back to another alias.

The roles are not tied to these models either: any cheap model works in the worker or the reviewer role. Examples from the opencode Go catalog at the time of writing, per million tokens, input / output: MiMo v2.6 Flash $0.14 / $0.28, DeepSeek v4.1 Flash $0.15 / $0.60; agy (a Google account quota) and codex (a ChatGPT plan) cost no per-token money. ahub setup probes what you have and picks; ahub models role changes it later.

On any tariff the hub saves the orchestrator's context: Claude spends a few KB per task — one event line, a capped summary, a one-word decision — instead of doing the work itself.

How it compares

Several projects connect Claude Code to other agents. Most are thin bridges (start a session, poll its status). agent-hub is narrower in scope and deeper in the task lifecycle:

If you want a dashboard for twenty parallel agents with PR automation, use a fleet orchestrator. If you want Claude Code to stop burning its context on work a cheaper model can do — and to trust the result — this is it.

Install

Requires Python 3.11+, git, and at least one provider: opencode (free models work), Google Antigravity CLI (agy) or Codex CLI (@openai/codex).

pipx install ahub
ahub setup                 # language, project, providers, models, service, Claude skill, Telegram (optional)
ahub doctor                # what is wrong and how to fix it
ahub providers             # the providers ahub knows: found, logged in, enabled, models

ahub setup --yes takes all defaults without questions. The wizard finds every provider, shows which are installed and logged in and which are missing with an install hint, lets you switch each one on or off, and probes the models live to pick the role defaults. Telegram is optional: pipx install 'ahub[telegram]'.

Platforms: Linux (systemd), macOS (launchd; tested in CI), Windows via WSL2 only.

Per-provider proxy and the Codex sandbox: the guide.

Quick start for Claude Code

ahub setup --claude gives Claude Code everything it needs in one step: the ahub skill, a short block in the project CLAUDE.md and the permission Bash(ahub:*) in .claude/settings.json — so ahub … runs without a question every time (ahub doctor shows both).

ahub task new --kind code --title "add retry to the payment client" \
  --spec-file spec.md --paths "app/payments/**,tests/**" --accept "tests/test_payments.py"

Claude keeps a Monitor on ahub watch; when a line arrives it runs ahub status T12 and decides:

DONE T12 code «add retry to the payment client» — report 2.1 KB; ready; $0.04

ahub accept T12                                # merge --no-ff, re-run acceptance
ahub rework T12 --notes "…"                    # send it back with notes, same session
ahub reject T12 --reason "…"                   # drop it, worktree cleaned up

Other agents talk to the same stdio server over MCP: claude mcp add ahub -- ahub mcp, and the same server in the Codex or Cursor config.

Interactive console

ahub with no arguments opens the console when stdin and stdout are TTYs (a pipe or --json keeps the one-shot output byte-identical); ahub top opens the same console:

╭──────────────────────────────╮
│ ✻ ahub 3.0.0 · demo          │
│ project: demo · /srv/demo    │
│ service running (tick 3s ago)│
╰──────────────────────────────╯
⏺ ✢ T12  add retry to payments
  ⎿ writing code · spark · 2m 13s
◦ T13  queued · waiting for T12
⏺ T11  waiting for you
  ⎿ Next: ahub accept T11 …
> /accept T11

Stages read at a glance: ⏺ white + spinner — active (writing code, studying, running tests, in review); ◦ dim — queued; ⏺ yellow — waiting for you; ✗ red — error/dead; ⏸ dim — stopped. Every command calls the same functions as the CLI; /help lists them, ? shows the shortcuts.

Documentation

• docs/guide.md — user guide: install, providers, tasks, watching, costs, troubleshooting
• Developer docs, in English only: docs/ARCHITECTURE.md (code map, start here), docs/architecture.md (design), docs/contracts.md (interfaces between the parts), CONTRIBUTING.md

Development

python -m venv .venv && .venv/bin/pip install -e '.[dev]'
.venv/bin/python -m pytest -q          # ~6 min, no network, HOME is faked
AHUB_LIVE=1 .venv/bin/python -m pytest -m live   # real providers, costs money

License

MIT