{"id":47728533,"url":"https://github.com/soul-brews-studio/maw-js","last_synced_at":"2026-05-26T03:02:36.657Z","repository":{"id":342929576,"uuid":"1175322103","full_name":"Soul-Brews-Studio/maw-js","owner":"Soul-Brews-Studio","description":"maw.js — Multi-Agent Workflow orchestrator. Remote tmux orchestra control with CLI + React/Three.js Web UI. Evolved from multi-agent-workflow-kit.","archived":false,"fork":false,"pushed_at":"2026-04-26T02:03:23.000Z","size":507471,"stargazers_count":13,"open_issues_count":8,"forks_count":27,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-26T04:09:01.788Z","etag":null,"topics":["bun","multi-agent","oracle","react","threejs","tmux"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Soul-Brews-Studio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["nazt"]}},"created_at":"2026-03-07T14:54:18.000Z","updated_at":"2026-04-26T02:02:50.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Soul-Brews-Studio/maw-js","commit_stats":null,"previous_names":["soul-brews-studio/maw-js"],"tags_count":170,"template":false,"template_full_name":null,"purl":"pkg:github/Soul-Brews-Studio/maw-js","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Soul-Brews-Studio%2Fmaw-js","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Soul-Brews-Studio%2Fmaw-js/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Soul-Brews-Studio%2Fmaw-js/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Soul-Brews-Studio%2Fmaw-js/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Soul-Brews-Studio","download_url":"https://codeload.github.com/Soul-Brews-Studio/maw-js/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Soul-Brews-Studio%2Fmaw-js/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32324552,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-26T23:26:28.701Z","status":"online","status_checked_at":"2026-04-27T02:00:06.769Z","response_time":128,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["bun","multi-agent","oracle","react","threejs","tmux"],"created_at":"2026-04-02T21:04:40.867Z","updated_at":"2026-05-26T03:02:36.650Z","avatar_url":"https://github.com/Soul-Brews-Studio.png","language":"TypeScript","funding_links":["https://github.com/sponsors/nazt"],"categories":[],"sub_categories":[],"readme":"# maw\n\n[![CI](https://github.com/Soul-Brews-Studio/maw-js/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/Soul-Brews-Studio/maw-js/actions/workflows/ci.yml?query=branch%3Amain) [![Coverage](https://img.shields.io/endpoint?url=https%3A%2F%2Fgist.githubusercontent.com%2Fnazt%2Fb00c729c7f40d4804f82011167bfd9d8%2Fraw%2Fmaw-js-coverage.json\u0026cacheSeconds=300)](docs/testing/coverage-gap-analysis.md) [![License](https://img.shields.io/badge/license-BUSL--1.1-blue)](./LICENSE) [![CalVer](https://img.shields.io/github/v/release/Soul-Brews-Studio/maw-js?label=calver)](https://github.com/Soul-Brews-Studio/maw-js/releases) [![Bun](https://img.shields.io/badge/runtime-Bun%201.3%2B-f9f1e1)](https://bun.sh) [![Test files](https://img.shields.io/badge/test_files-750%2B-brightgreen)](./test)\n\n\u003e Multi-Agent Workflow — wake agents, talk across machines, see the mesh.\n\n**maw is a CLI for running multiple AI agents across machines.** You wake\nan agent in a tmux window, send it tasks, watch its screen, and see what\nit cost — all from one terminal. One node or twenty; same commands. Built\non [Bun](https://bun.sh) and [Claude Code](https://claude.com/claude-code).\n\n\n## Install\n\n```bash\n# One line:\ncurl -fsSL https://raw.githubusercontent.com/Soul-Brews-Studio/maw-js/main/install.sh | bash\n\n# Or manually:\nbun add -g github:Soul-Brews-Studio/maw-js\n\n# Or from source:\nghq get Soul-Brews-Studio/maw-js \u0026\u0026 cd \"$(ghq root)/github.com/Soul-Brews-Studio/maw-js\" \u0026\u0026 bun install \u0026\u0026 bun link\n```\n\n\u003e **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).\n\n## Recovering from `maw: command not found`\n\nIf `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:\n\n1. **One-shot reinstall**: `bun add -g github:Soul-Brews-Studio/maw-js`\n2. **Self-heal command**: `bunx -p github:Soul-Brews-Studio/maw-js maw doctor` — auto-detects + restores\n3. **Shell hook**: source `scripts/maw-heal.sh` from your `.bashrc` / `.zshrc` — checks on every shell init\n\nDefense-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.).\n\nFull runbook: [`docs/install-recovery.md`](docs/install-recovery.md).\n\n## Quick Start\n\n```bash\nmaw serve                                # start API + UI on :3456\nmaw ui install                           # download the federation lens\nmaw ui                                   # → http://localhost:3456/federation_2d.html\nmaw ls --recent 5                        # find recent sessions\nmaw wake neo --split                     # wake side-by-side with an oracle\nmaw bring neo --to work:review --pick    # bring to an explicit session:window when fuzzy\nmaw hey neo \"what are you working on?\"   # bare-name addressing works\n```\n\n## Installing the UI\n\n`maw` installs API-only. The React frontend ships separately from\n[Soul-Brews-Studio/maw-ui](https://github.com/Soul-Brews-Studio/maw-ui).\n\n### Quick install (recommended — requires `gh` auth)\n\n```bash\nmaw ui install                       # latest release\nmaw ui install --version v1.15.0     # specific version\nmaw ui status                        # verify installation\n```\n\nDownloads `dist.tar.gz` from the maw-ui GitHub Release and extracts to the\nactive maw data dir (`~/.maw/ui/dist/` by default today, or\n`$XDG_DATA_HOME/maw/ui/dist/` when `MAW_XDG=1`). Restart the maw server to\nserve the new UI.\n\n### Manual install (no `gh`)\n\n```bash\n# Download dist.tar.gz from a release page, then:\nMAW_UI_DIR=\"${XDG_DATA_HOME:-$HOME/.local/share}/maw/ui/dist\"\nmkdir -p \"$MAW_UI_DIR\"\ntar -xzf dist.tar.gz -C \"$MAW_UI_DIR\" --strip-components=1\n```\n\n### Build from source\n\n```bash\nghq get -u github.com/Soul-Brews-Studio/maw-ui\ncd \"$(ghq root)/github.com/Soul-Brews-Studio/maw-ui\"\nbun install \u0026\u0026 bun run build\nln -sf \"$(pwd)/dist\" \"${XDG_DATA_HOME:-$HOME/.local/share}/maw/ui/dist\"\n```\n\n## Runtime paths and XDG migration\n\n`maw` now has a central path resolver for config, state, data, and cache.\nLegacy installs remain readable, but new runtime writers are moving away from\n`~/.config/maw/` and direct `~/.maw/` roots.\n\n```bash\nmaw doctor xdg                         # show active config/state/data/cache roots\nmaw doctor xdg --json                  # machine-readable migration inventory\nmaw doctor xdg --migrate --dry-run     # preview safe copy-forward moves\nmaw doctor xdg --migrate               # copy legacy artifacts into XDG targets\nMAW_XDG=1 maw doctor xdg               # opt into spec-correct runtime paths\n```\n\nThe migration command is intentionally non-destructive: it copies missing\nartifacts forward and preserves existing destinations plus legacy sources.\n\n## Wake from anywhere\n\n```bash\nmaw wake org/repo                        # clone via ghq + wake\nmaw wake https://github.com/org/repo     # full URL works too\nmaw wake org/repo --issue 5              # clone + send issue as prompt\nmaw bud myname --root                    # create a fresh oracle (no parent)\nmaw bud myname --from neo                # bud from an existing oracle\n# 👉 maw bud \u003cstem\u003e always creates repo \u003cstem\u003e-oracle.\n#    Never include \"-oracle\" in \u003cstem\u003e — it doubles the suffix.\n#    e.g.  maw bud fusion       → fusion-oracle ✓\n#          maw bud fusion-oracle → fusion-oracle-oracle ✗\n```\n\n## Federation\n\nTalk across machines with HMAC-SHA256 signing.\n\n```bash\nmaw hey neo \"hello\"                      # default: inbox + immediate pane delivery\nmaw hey neo \"later\" --inbox              # queue-only: write receiver inbox, skip pane injection\nmaw hey white:neo \"hello\"                # canonical form — remote node, window 1\nmaw hey white:neo:3 \"hello hermes\"       # pick a specific tmux window (#410)\nmaw peek white:neo                       # see their screen\nmaw ping                                 # check peer connectivity\n\n# Config (maw.config.json)\n{\n  \"node\": \"oracle-world\",\n  \"federationToken\": \"shared-secret-min-16-chars\",\n  \"namedPeers\": [{ \"name\": \"white\", \"url\": \"http://10.20.0.7:3456\" }]\n}\n```\n\n## The Lens (maw-ui)\n\nSee the mesh in a browser. Any federation can point the lens at any backend:\n\n```bash\nmaw ui                                   # local lens\nmaw ui white                             # lens pointed at white's data\nmaw ui --tunnel 10.20.0.16               # SSH tunnel + lens URL\n```\n\nThe 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.\n\nFrontend repo: [Soul-Brews-Studio/maw-ui](https://github.com/Soul-Brews-Studio/maw-ui)\n\n## CLI\n\n```bash\nmaw ls                           # compact session summary\nmaw ls -v / -c                   # detailed / compact views\nmaw ls --recent [n]              # sort by creation time\nmaw peek [agent]                 # see agent screen\nmaw hey \u003cagent\u003e \u003cmsg\u003e [--inbox]  # send now by default; --inbox queues only\nmaw wake \u003coracle\u003e [task]         # wake oracle in tmux\nmaw wake --dry-run/--list        # preview without side effects\nmaw wake --from-snapshot         # restore from a wake snapshot\nmaw sleep \u003coracle\u003e               # gracefully stop\nmaw done \u003cwindow\u003e                # auto-save + clean up worktree/branch\nmaw new \u003cname\u003e                   # create a workspace session\nmaw team bring \u003cteam\u003e            # bring oracles into a workspace\nmaw team create/oracle-invite    # team management\nmaw scaffold \u003cname\u003e              # structure-only project creation\nmaw snapshots list/show          # browse wake snapshots\nmaw bud \u003cname\u003e [--from parent]   # spawn new oracle\nmaw fleet ls/health/doctor       # fleet config + health tools\nmaw oracle scan                  # discover oracles across nodes\nmaw plugin install \u003cname\u003e        # install a registry or peer plugin\nmaw \u003cplugin\u003e serve               # run plugin-owned browser/process UIs\nmaw fck                          # command correction plugin\nmaw fleet-ui serve               # fleet dashboard plugin\nmaw messages serve               # message ledger browser plugin\nmaw ui                           # open federation lens\nmaw serve [port]                 # start API server (default: 3456)\n```\n\nFull command reference: `maw --help`\n\n## Plugin Ecosystem\n\n`maw` is now a plugin OS as much as a CLI. Core commands stay small,\nwhile registry plugins add focused tools that can be enabled, served,\nor removed without changing the engine.\n\n```bash\nmaw plugin ls                    # installed + tiered plugins\nmaw plugin install \u003cname\u003e        # install from maw-plugin-registry or peers\nmaw plugin enable \u003cname\u003e         # opt into disabled-but-installed tools\nmaw \u003cplugin\u003e serve               # run a plugin-owned browser/process UI\n```\n\nThe plugin manifest supports CLI commands, capabilities, APIs, lifecycle\nhooks, and engine-backed `serve` processes. Registry plugins such as\n`fleet-ui`, `messages`, and `fck` can extend the operator surface without\npromoting every experiment into core.\n\n## Team Workspaces\n\nUse `maw new` to create a shared tmux workspace, then bring a team of\noracles into it. This is the dynamic version of a static MAWK profile:\none lead shell plus one window per specialist.\n\n```bash\nmaw new project-room --no-attach\nmaw team create project-room\nmaw team oracle-invite mawjs-issuer --team project-room\nmaw team bring project-room\n```\n\n## Wake Lifecycle\n\nWake is now a lifecycle, not just a launch command. Plugins can declare\n`hooks.wake`, `hooks.serve`, and `hooks.sleep` in `plugin.json`; maw can\npreview wake plans, record snapshots, and restore from a previous launch.\n\n```bash\nmaw wake neo --dry-run           # inspect target/session/plugin effects\nmaw snapshots list               # list captured wake state\nmaw wake neo --from-snapshot \u003cid\u003e\n```\n\n## Federation API\n\n| Endpoint | Purpose |\n|----------|---------|\n| `GET /api/config` | Node identity + agents map |\n| `GET /api/fleet-config` | Fleet entries with sync_peers + lineage |\n| `GET /api/feed?limit=200` | Live event log |\n| `GET /api/federation/status` | Peer connectivity |\n| `POST /api/peer/exec` | Signed command relay between nodes |\n| `POST /api/proxy/*` | HTTP relay for mixed-content peers |\n\nFull reference: [`docs/federation.md`](docs/federation.md)\n\n## Architecture\n\n```\nmaw-js (backend + CLI)              maw-ui (frontend)\n├── src/commands/  (CLI + plugin dispatch) ├── src/components/\n├── src/api/       (engine + plugin APIs)   ├── src/hooks/\n├── src/engine/    (WebSocket + serve proxy)├── src/lib/\n├── src/transports/ (HTTP/tmux/hub)         └── 16 HTML entry points\n├── plugins        (89 installed plugin surfaces)\n├── test/          (750+ test files)\n└── install.sh\n```\n\n## Evolution\n\n```\nOct 2025   maw.env.sh            30+ shell commands\nMar 2026   maw.js                 Bun/TS rewrite, tmux orchestration\nMar 2026   maw-js + maw-ui        Backend/frontend split\nApr 2026   v2.0.0-alpha.66        Plugin OS foundation, Bun runtime,\n                                   federation API + maw-ui split\nMay 2026   v26.5.20-alpha.2203    Plugin engine, lifecycle hooks,\n                                   team workspaces, 89 plugins,\n                                   750+ test files, 100% line/function coverage,\n                                   portable Rust spec fixtures\n```\n\n## Federation testing\n\nPeer handshake regressions hide on a single host. The Docker harness\nspins up two `maw-js:test` containers on a shared network and runs\n`maw peers probe` both directions as a round-trip smoke test.\n\n```bash\nbash scripts/test-docker-federation.sh   # build + up + probe + teardown\nbash scripts/dev-federation.sh up        # leave the 2-node stack running\n```\n\nCI runs the same script via `.github/workflows/federation-docker.yml`\non any PR that touches `docker/**`, `src/transports/**`, or the peers\nplugin. Full runbook: [`docs/federation/docker-testing.md`](docs/federation/docker-testing.md).\n\nOnboarding a new node? Use `maw pair generate` / `maw pair \u003curl\u003e \u003ccode\u003e`\nfor a 6-char ephemeral handshake — see\n[`docs/federation/pair-code.md`](docs/federation/pair-code.md).\n\n## maw-rs port\n\nThe Rust port is tracked through portable JSON fixtures instead of prose-only\nspecs. See [`docs/maw-rs-port-status.md`](docs/maw-rs-port-status.md) for the\ncurrent fixture inventory, crate lanes, and contributor entry points.\n\n## Marketplace\n\nPlugins can be discovered and installed peer-to-peer (Shape A, no central\nregistry required). See\n[`docs/plugins/shape-a-demo.md`](docs/plugins/shape-a-demo.md) for a\n7-step walkthrough — peers, federated search, `@peer` install, consent.\n\nFor fresh-install bootstrap, plugin source tiers, vendored registry plugins,\nand `maw plugin install` trust/lock behavior, see\n[`docs/plugins/install-architecture.md`](docs/plugins/install-architecture.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoul-brews-studio%2Fmaw-js","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsoul-brews-studio%2Fmaw-js","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsoul-brews-studio%2Fmaw-js/lists"}