https://github.com/soul-brews-studio/maw-js
maw.js — Multi-Agent Workflow orchestrator. Remote tmux orchestra control with CLI + React/Three.js Web UI. Evolved from multi-agent-workflow-kit.
https://github.com/soul-brews-studio/maw-js
bun multi-agent oracle react threejs tmux
Last synced: 25 days ago
JSON representation
maw.js — Multi-Agent Workflow orchestrator. Remote tmux orchestra control with CLI + React/Three.js Web UI. Evolved from multi-agent-workflow-kit.
- Host: GitHub
- URL: https://github.com/soul-brews-studio/maw-js
- Owner: Soul-Brews-Studio
- License: other
- Created: 2026-03-07T14:54:18.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-26T02:03:23.000Z (about 2 months ago)
- Last Synced: 2026-04-26T04:09:01.788Z (about 2 months ago)
- Topics: bun, multi-agent, oracle, react, threejs, tmux
- Language: TypeScript
- Size: 484 MB
- Stars: 13
- Watchers: 0
- Forks: 27
- Open Issues: 8
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.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
# maw
[](https://github.com/Soul-Brews-Studio/maw-js/actions/workflows/ci.yml?query=branch%3Amain) [](docs/testing/coverage-gap-analysis.md) [](./LICENSE) [](https://github.com/Soul-Brews-Studio/maw-js/releases) [](https://bun.sh) [](./test)
> Multi-Agent Workflow — wake agents, talk across machines, see the mesh.
**maw is a CLI for running multiple AI agents across machines.** You wake
an agent in a tmux window, send it tasks, watch its screen, and see what
it cost — all from one terminal. One node or twenty; same commands. Built
on [Bun](https://bun.sh) and [Claude Code](https://claude.com/claude-code).
## Install
```bash
# One line:
curl -fsSL https://raw.githubusercontent.com/Soul-Brews-Studio/maw-js/main/install.sh | bash
# Or manually:
bun add -g github:Soul-Brews-Studio/maw-js
# Or from source:
ghq get Soul-Brews-Studio/maw-js && cd "$(ghq root)/github.com/Soul-Brews-Studio/maw-js" && bun install && bun link
```
> **Versioning**: `maw-js` uses [CalVer](https://calver.org) — `v{yy}.{m}.{d}[-alpha.{HHMM}]` (e.g. `v26.5.17-alpha.752`). Migrated from SemVer alpha on 2026-04-18. Cutting a release? See [CONTRIBUTING.md → Versioning](./CONTRIBUTING.md#versioning). Background: [CHANGELOG](./CHANGELOG.md#versioning--calver-since-2026-04-18) · umbrella [#526](https://github.com/Soul-Brews-Studio/maw-js/issues/526).
## Recovering from `maw: command not found`
If `maw` vanishes unexpectedly (see [#531](https://github.com/Soul-Brews-Studio/maw-js/issues/531) — root cause: npm name collision, fixed in #557 via rename to `maw-js`), recovery paths:
1. **One-shot reinstall**: `bun add -g github:Soul-Brews-Studio/maw-js`
2. **Self-heal command**: `bunx -p github:Soul-Brews-Studio/maw-js maw doctor` — auto-detects + restores
3. **Shell hook**: source `scripts/maw-heal.sh` from your `.bashrc` / `.zshrc` — checks on every shell init
Defense-in-depth: `maw update` stashes the binary to `~/.bun/bin/maw.prev` before any destructive `bun remove` and restores on retry-fail (#551). `maw doctor` remains useful if the binary disappears for other reasons (older alpha, manual `bun remove`, disk full, etc.).
Full runbook: [`docs/install-recovery.md`](docs/install-recovery.md).
## Quick Start
```bash
maw serve # start API + UI on :3456
maw ui install # download the federation lens
maw ui # → http://localhost:3456/federation_2d.html
maw ls --recent 5 # find recent sessions
maw wake neo --split # wake side-by-side with an oracle
maw bring neo --to work:review --pick # bring to an explicit session:window when fuzzy
maw hey neo "what are you working on?" # bare-name addressing works
```
## Installing the UI
`maw` installs API-only. The React frontend ships separately from
[Soul-Brews-Studio/maw-ui](https://github.com/Soul-Brews-Studio/maw-ui).
### Quick install (recommended — requires `gh` auth)
```bash
maw ui install # latest release
maw ui install --version v1.15.0 # specific version
maw ui status # verify installation
```
Downloads `dist.tar.gz` from the maw-ui GitHub Release and extracts to the
active maw data dir (`~/.maw/ui/dist/` by default today, or
`$XDG_DATA_HOME/maw/ui/dist/` when `MAW_XDG=1`). Restart the maw server to
serve the new UI.
### Manual install (no `gh`)
```bash
# Download dist.tar.gz from a release page, then:
MAW_UI_DIR="${XDG_DATA_HOME:-$HOME/.local/share}/maw/ui/dist"
mkdir -p "$MAW_UI_DIR"
tar -xzf dist.tar.gz -C "$MAW_UI_DIR" --strip-components=1
```
### Build from source
```bash
ghq get -u github.com/Soul-Brews-Studio/maw-ui
cd "$(ghq root)/github.com/Soul-Brews-Studio/maw-ui"
bun install && bun run build
ln -sf "$(pwd)/dist" "${XDG_DATA_HOME:-$HOME/.local/share}/maw/ui/dist"
```
## Runtime paths and XDG migration
`maw` now has a central path resolver for config, state, data, and cache.
Legacy installs remain readable, but new runtime writers are moving away from
`~/.config/maw/` and direct `~/.maw/` roots.
```bash
maw doctor xdg # show active config/state/data/cache roots
maw doctor xdg --json # machine-readable migration inventory
maw doctor xdg --migrate --dry-run # preview safe copy-forward moves
maw doctor xdg --migrate # copy legacy artifacts into XDG targets
MAW_XDG=1 maw doctor xdg # opt into spec-correct runtime paths
```
The migration command is intentionally non-destructive: it copies missing
artifacts forward and preserves existing destinations plus legacy sources.
## Wake from anywhere
```bash
maw wake org/repo # clone via ghq + wake
maw wake https://github.com/org/repo # full URL works too
maw wake org/repo --issue 5 # clone + send issue as prompt
maw bud myname --root # create a fresh oracle (no parent)
maw bud myname --from neo # bud from an existing oracle
# 👉 maw bud always creates repo -oracle.
# Never include "-oracle" in — it doubles the suffix.
# e.g. maw bud fusion → fusion-oracle ✓
# maw bud fusion-oracle → fusion-oracle-oracle ✗
```
## Federation
Talk across machines with HMAC-SHA256 signing.
```bash
maw hey neo "hello" # default: inbox + immediate pane delivery
maw hey neo "later" --inbox # queue-only: write receiver inbox, skip pane injection
maw hey white:neo "hello" # canonical form — remote node, window 1
maw hey white:neo:3 "hello hermes" # pick a specific tmux window (#410)
maw peek white:neo # see their screen
maw ping # check peer connectivity
# Config (maw.config.json)
{
"node": "oracle-world",
"federationToken": "shared-secret-min-16-chars",
"namedPeers": [{ "name": "white", "url": "http://10.20.0.7:3456" }]
}
```
## The Lens (maw-ui)
See the mesh in a browser. Any federation can point the lens at any backend:
```bash
maw ui # local lens
maw ui white # lens pointed at white's data
maw ui --tunnel 10.20.0.16 # SSH tunnel + lens URL
```
The lens reads `?host=` at runtime ([drizzle studio pattern](https://local.drizzle.studio)). Packed-serve mode: `maw ui install` downloads the lens, `maw serve` serves it alongside the API on a single port.
Frontend repo: [Soul-Brews-Studio/maw-ui](https://github.com/Soul-Brews-Studio/maw-ui)
## CLI
```bash
maw ls # compact session summary
maw ls -v / -c # detailed / compact views
maw ls --recent [n] # sort by creation time
maw peek [agent] # see agent screen
maw hey [--inbox] # send now by default; --inbox queues only
maw wake [task] # wake oracle in tmux
maw wake --dry-run/--list # preview without side effects
maw wake --from-snapshot # restore from a wake snapshot
maw sleep # gracefully stop
maw done # auto-save + clean up worktree/branch
maw new # create a workspace session
maw team bring # bring oracles into a workspace
maw team create/oracle-invite # team management
maw scaffold # structure-only project creation
maw snapshots list/show # browse wake snapshots
maw bud [--from parent] # spawn new oracle
maw fleet ls/health/doctor # fleet config + health tools
maw oracle scan # discover oracles across nodes
maw plugin install # install a registry or peer plugin
maw serve # run plugin-owned browser/process UIs
maw fck # command correction plugin
maw fleet-ui serve # fleet dashboard plugin
maw messages serve # message ledger browser plugin
maw ui # open federation lens
maw serve [port] # start API server (default: 3456)
```
Full command reference: `maw --help`
## Plugin Ecosystem
`maw` is now a plugin OS as much as a CLI. Core commands stay small,
while registry plugins add focused tools that can be enabled, served,
or removed without changing the engine.
```bash
maw plugin ls # installed + tiered plugins
maw plugin install # install from maw-plugin-registry or peers
maw plugin enable # opt into disabled-but-installed tools
maw serve # run a plugin-owned browser/process UI
```
The plugin manifest supports CLI commands, capabilities, APIs, lifecycle
hooks, and engine-backed `serve` processes. Registry plugins such as
`fleet-ui`, `messages`, and `fck` can extend the operator surface without
promoting every experiment into core.
## Team Workspaces
Use `maw new` to create a shared tmux workspace, then bring a team of
oracles into it. This is the dynamic version of a static MAWK profile:
one lead shell plus one window per specialist.
```bash
maw new project-room --no-attach
maw team create project-room
maw team oracle-invite mawjs-issuer --team project-room
maw team bring project-room
```
## Wake Lifecycle
Wake is now a lifecycle, not just a launch command. Plugins can declare
`hooks.wake`, `hooks.serve`, and `hooks.sleep` in `plugin.json`; maw can
preview wake plans, record snapshots, and restore from a previous launch.
```bash
maw wake neo --dry-run # inspect target/session/plugin effects
maw snapshots list # list captured wake state
maw wake neo --from-snapshot
```
## Federation API
| Endpoint | Purpose |
|----------|---------|
| `GET /api/config` | Node identity + agents map |
| `GET /api/fleet-config` | Fleet entries with sync_peers + lineage |
| `GET /api/feed?limit=200` | Live event log |
| `GET /api/federation/status` | Peer connectivity |
| `POST /api/peer/exec` | Signed command relay between nodes |
| `POST /api/proxy/*` | HTTP relay for mixed-content peers |
Full reference: [`docs/federation.md`](docs/federation.md)
## Architecture
```
maw-js (backend + CLI) maw-ui (frontend)
├── src/commands/ (CLI + plugin dispatch) ├── src/components/
├── src/api/ (engine + plugin APIs) ├── src/hooks/
├── src/engine/ (WebSocket + serve proxy)├── src/lib/
├── src/transports/ (HTTP/tmux/hub) └── 16 HTML entry points
├── plugins (89 installed plugin surfaces)
├── test/ (750+ test files)
└── install.sh
```
## Evolution
```
Oct 2025 maw.env.sh 30+ shell commands
Mar 2026 maw.js Bun/TS rewrite, tmux orchestration
Mar 2026 maw-js + maw-ui Backend/frontend split
Apr 2026 v2.0.0-alpha.66 Plugin OS foundation, Bun runtime,
federation API + maw-ui split
May 2026 v26.5.20-alpha.2203 Plugin engine, lifecycle hooks,
team workspaces, 89 plugins,
750+ test files, 100% line/function coverage,
portable Rust spec fixtures
```
## Federation testing
Peer handshake regressions hide on a single host. The Docker harness
spins up two `maw-js:test` containers on a shared network and runs
`maw peers probe` both directions as a round-trip smoke test.
```bash
bash scripts/test-docker-federation.sh # build + up + probe + teardown
bash scripts/dev-federation.sh up # leave the 2-node stack running
```
CI runs the same script via `.github/workflows/federation-docker.yml`
on any PR that touches `docker/**`, `src/transports/**`, or the peers
plugin. Full runbook: [`docs/federation/docker-testing.md`](docs/federation/docker-testing.md).
Onboarding a new node? Use `maw pair generate` / `maw pair `
for a 6-char ephemeral handshake — see
[`docs/federation/pair-code.md`](docs/federation/pair-code.md).
## maw-rs port
The Rust port is tracked through portable JSON fixtures instead of prose-only
specs. See [`docs/maw-rs-port-status.md`](docs/maw-rs-port-status.md) for the
current fixture inventory, crate lanes, and contributor entry points.
## Marketplace
Plugins can be discovered and installed peer-to-peer (Shape A, no central
registry required). See
[`docs/plugins/shape-a-demo.md`](docs/plugins/shape-a-demo.md) for a
7-step walkthrough — peers, federated search, `@peer` install, consent.
For fresh-install bootstrap, plugin source tiers, vendored registry plugins,
and `maw plugin install` trust/lock behavior, see
[`docs/plugins/install-architecture.md`](docs/plugins/install-architecture.md).