https://github.com/jahala/umbel
Remote-control interactive agent CLIs (Claude Code, Codex, Gemini) over tmux. One binary, three faces, one provider abstraction. Subscription-billed.
https://github.com/jahala/umbel
agent-orchestration ai-tools automation bun claude-code codex gemini mcp multi-agent tmux typescript
Last synced: 1 day ago
JSON representation
Remote-control interactive agent CLIs (Claude Code, Codex, Gemini) over tmux. One binary, three faces, one provider abstraction. Subscription-billed.
- Host: GitHub
- URL: https://github.com/jahala/umbel
- Owner: jahala
- License: mit
- Created: 2026-05-21T21:20:29.000Z (about 1 month ago)
- Default Branch: master
- Last Pushed: 2026-06-19T22:43:25.000Z (6 days ago)
- Last Synced: 2026-06-20T00:14:02.129Z (6 days ago)
- Topics: agent-orchestration, ai-tools, automation, bun, claude-code, codex, gemini, mcp, multi-agent, tmux, typescript
- Language: TypeScript
- Homepage: https://jahala.github.io/umbel/
- Size: 823 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- Funding: .github/FUNDING.yml
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
Awesome Lists containing this project
README
# umbel
[](https://jahala.github.io/umbel/)
[](LICENSE)
[](https://github.com/jahala/umbel/actions)
🌱 **[What is umbel? →](https://jahala.github.io/umbel/)** · the visual overview
**Spawn other-provider agent workers from inside your agent session.** Drive `claude`, `codex`, `gemini`, or `opencode` interactively in tmux from a CLI, MCP server, or YAML workflow. One binary, one provider abstraction — subscription-billed for claude/codex/gemini, bring-any-model for opencode.
## Claude Code orchestrating Codex (and Gemini, in parallel)
Your `claude` session can't spawn a `codex` session directly. With `umbel mcp` configured, it can:
```jsonc
// .mcp.json
{ "mcpServers": { "umbel": { "command": "umbel", "args": ["mcp"] } } }
```
Your Claude Code agent now has `umbel_spawn`, `umbel_send`, `umbel_wait`, `umbel_read`, `umbel_kill`, and `umbel_help` in its toolbelt. Tell it:
> Spawn a Codex reviewer in `./worktrees/a` and a Gemini tester in `./worktrees/b`. Have them work in parallel, then synthesize their findings.
It'll stand up both workers, dispatch the prompts, wait for completion, and read their outputs. Three subscriptions, three roles, one orchestration. The host's context stays clean — it spends tokens on planning and synthesis, not on doing the work itself.
The server ships a server-level `instructions` block plus an on-demand `umbel_help` tool (topics: `lifecycle`, `workflow`, `providers`) so your agent learns when to reach for umbel and how to use it without being drowned in upfront context.
## Supervisor mode (CLI)
The same verbs from your shell — useful in scripts, cron, or when driving umbel without an MCP host:
```bash
umbel spawn --name reviewer --provider claude --cwd ./worktrees/review --model sonnet
umbel spawn --name fixer --provider codex --cwd ./worktrees/fix --model o4-mini
umbel send reviewer "review the diff and write findings to review.md"
umbel wait reviewer
umbel read reviewer
```
A single supervisor can drive workers across providers concurrently. The provider is recorded in `meta.json` per session so `send`/`wait`/`read`/`kill` auto-route — no `--provider` needed after spawn.
Full verb list: `spawn`, `send`, `wait`, `status`, `ls`, `kill`, `attach`, `read`, `capture`, `logs`, `run`, `mcp`.
## Workflow mode
Declarative multi-step pipelines, mixed-provider per step:
```yaml
workers:
reviewer:
provider: claude
model: sonnet
cwd: ./worktrees/review
fixer:
provider: codex
model: o4-mini
cwd: ./worktrees/fix
steps:
- run: reviewer
prompt: "Review PR #{{ env.PR }}. Write findings to review.md."
wait: { stop: $session, timeout: 10m }
outputs:
review: file:./worktrees/review/review.md
- run: fixer
needs: [reviewer]
prompt: "Apply these fixes:\n{{ steps.reviewer.outputs.review }}"
wait:
all:
- { stop: $session }
- { file: ./worktrees/fix/tests-passed }
```
```bash
umbel run review-then-fix.yaml
```
Steps run in parallel where `needs` allows. Templating is intentionally minimal: `{{ env.X }}`, `{{ steps.NAME.outputs.X }}`, `{{ $session }}`.
## `umbel -p` — drop-in for `claude -p` / `codex -p` / `gemini -p`
Same flags as the vendor `-p` mode, with provider as a parameter:
```bash
umbel -p "summarise $FILE" --provider claude --model sonnet --allowedTools Read
umbel -p "summarise $FILE" --provider codex --model o4-mini
umbel -p "summarise $FILE" --provider gemini --model gemini-2.5-pro
umbel -p "summarise $FILE" --provider opencode --model opencode/big-pickle # free, keyless
umbel -p "summarise $FILE" --provider opencode --model ollama/qwen2.5-coder # local
```
`--provider` defaults to `claude` (so `umbel -p` mirrors `claude -p`). Cold-start ~3–5s on first call; use `--name` / `--resume` to keep a session warm:
```bash
umbel -p --name analyst --provider claude "first question"
umbel -p --resume analyst "follow-up" # reuses the warm session, same provider
```
## Install
```bash
bun install && bun run build
```
Homebrew tap coming. For now, build from source.
## Requires
- `tmux` >= 3.0
- macOS or Linux
- At least one provider CLI installed:
- `claude` (Claude Pro / Max — subscription-billed)
- `codex` (ChatGPT Plus / Pro / Team / Enterprise — subscription-billed)
- `gemini` (Google AI Pro / Ultra — subscription-billed)
- `opencode` (no subscription — local via `ollama/…`, free-tier via `opencode/big-pickle`, or API-billed via `anthropic/…` / `openrouter/…` with your own key)
Providers without their binary installed simply can't be selected. `umbel spawn --provider gemini` fails loudly when tmux can't exec `gemini`.
## Architecture
No daemon. `tmux` is the daemon; `~/.umbel/` is the state store. Every `umbel` invocation is short-lived. Completion detection uses each provider's native lifecycle event (Claude `Stop`, Codex `Stop`, Gemini `AfterAgent`, OpenCode `session.status` idle) — not terminal scraping. Agent output is read from each provider's transcript (JSONL for claude/codex/gemini; `opencode export` JSON for opencode), never from `capture-pane`. Providers are pluggable via a small interface (`src/core/providers/types.ts`) — adding a new CLI is a ~150 LOC implementation, not a rewrite. See [`docs/architecture-v3.md`](docs/architecture-v3.md) for the full design.
**What it is, and where it's headed:** umbel is the reliable, neutral execution boundary for *one unit of agent work* — the worker an orchestrator (agent, workflow, or human) commands and reads structured results back from. The thesis, the contract, and the trust-layer roadmap (typed + verified results) live in [`docs/positioning.md`](docs/positioning.md).
## Why this exists
Anthropic, OpenAI, and Google all priced their `-p` / `--print` modes at API rates while leaving the interactive TUI on subscription. `umbel` gives you a programmatic surface over the *interactive* binary of whichever vendor you're paying — so the work you'd otherwise do by hand in the TUI runs against the subscription you already pay for, not per-token API billing on top.
OpenCode has no subscription. It adds a different lane: **local** (your hardware, free, `ollama/…`), **free-tier** (OpenCode Zen, keyless, limited), or **API-billed** (your own key for `anthropic/…`, `openrouter/…`). Together, OpenCode makes umbel a **unified orchestration layer over any agent CLI** — great for running free local workers alongside your subscription claude/codex/gemini without any cost trade-off.
The `claude` provider can also point at any Anthropic-compatible endpoint — DeepSeek, OpenRouter, a local proxy — via `--env` (`ANTHROPIC_BASE_URL` + `ANTHROPIC_AUTH_TOKEN` + `ANTHROPIC_MODEL`): Claude Code's harness, a different model, billed per-token. See [custom model endpoints](docs/cli-reference.md#custom-model-endpoints-claude-provider).
Aimed at solo developers automating their own work. Not for commercial resale or evasion at scale. See [`docs/tos.md`](docs/tos.md) for the defensibility spectrum across all three vendors.
## Sister project
[**walkie-clawkie**](https://github.com/jahala/walkie-clawkie) — push-to-talk messaging between agents while their sessions are running. Complementary, not overlapping: umbel dispatches and waits; walkie-clawkie lets sessions talk to each other mid-turn.
## Contributing
PRs welcome. See [CONTRIBUTING.md](CONTRIBUTING.md). Test first — every fix and feature starts with a failing test.
## Support
[](https://buymeacoffee.com/jahala)
## License
MIT — see [LICENSE](LICENSE).