maqcli

The MAQ master orchestrator — a token-efficient, agent-agnostic supervisor CLI that sits on top of any worker CLI (AI or not) and runs every task through a Scout → Plan → Execute → Verify pipeline. It also runs as a secure daemon so a phone/app can drive it over one normalized event stream.

It does not replace your coding agent. It organizes, supports, and verifies its work — and when no AI is involved, it runs raw commands safely instead.

• Zero runtime dependencies — Node built-ins + global fetch only.
• Runs fully offline via a deterministic heuristic provider (no API key), and connects to real providers (OpenAI / Anthropic / Ollama / Groq / any OpenAI-compatible or LiteLLM proxy) when you configure one.
• Safe execution — every command runs via spawn with an argument array and shell: false; user/model values are never shell-interpreted.
• Secure daemon — HTTP + SSE, bearer-token auth, loopback-only by default.

Install / build

cd cli
npm install      # installs the TypeScript toolchain (dev only)
npm run build    # tsc -> dist/
npm test         # build + node --test  (60 tests)

Then run it:

node dist/index.js <command>
# or, after `npm link` / global install:
maq <command>     # (also aliased as `maqcli`)

Commands

| Command | What it does | |---|---| | maq detect | Scan PATH + each tool's auth dir for worker CLIs; report installed/authenticated/json-stream and the auto target. | | maq scout "<task>" | Deterministic, read-only recon (files, README, manifest, git history, complexity). Zero token cost. | | maq plan "<task>" | Scout + verifier-gated candidate plan (Best-of-N with early exit). | | maq run "<task>" [opts] | Full pipeline; dispatch the winning plan to a worker CLI (streamed) or run raw (--target none). | | maq verify [--cwd <dir>] | Run the project's tests (or cross-model review) as the completion signal. | | maq serve [opts] | Start the HTTP+SSE daemon (the app seam). Prints a bearer token. | | maq models | Show the configured provider, tier models, prices, and availability. | | maq probe | Probe the connectivity tier (real STUN/UDP + TCP + LAN interfaces). | | maq skills [init\|path] [--tier] | List/scaffold the tier-aware skills/rules layer injected into planning. | | maq subagent "<task>" | Run an isolated sub-agent (fresh context) that returns a concise summary. | | maq tools [<name>] [--args JSON] | List the safe tool registry, or run one (read_file/list_dir/grep_text/…). | | maq sessions [<id>] [pause\|resume\|cancel] | List/inspect/control daemon sessions (needs MAQ_TOKEN). | | maq config [get\|set\|path\|reset] | Read/update ~/.maqcli/config.json. | | maq version / maq help | — |

run options

-t, --target <t>   auto | claude-code | codex | gemini | opencode | aider | amazon-q | none
    --dry-run      plan and show the commands without executing
    --json         stream normalized events (one JSON object per line)
    --cwd <dir>    working directory

serve options

--host <h>   bind address (default 127.0.0.1; env MAQ_HOST)
--port <p>   port (default 7717; env MAQ_PORT)
--token <t>  bearer token (default env MAQ_TOKEN, else generated + printed)
--cors <o>   allow a browser origin (default off; env MAQ_CORS_ORIGIN)

Model providers (LiteLLM-style, one interface)

All master-model calls go through one ModelProvider interface. Select a provider with maq config set provider <name>. API keys come from the environment only — never config files. Missing keys fall back to the offline heuristic provider so the pipeline always runs.

| provider | env | notes | |---|---|---| | heuristic | — | offline, deterministic, $0 (default) | | openai | OPENAI_API_KEY (OPENAI_BASE_URL?) | /v1/chat/completions | | anthropic | ANTHROPIC_API_KEY | Messages API, anthropic-version: 2023-06-01 | | ollama | OLLAMA_HOST? | local, native /api/chat, free | | groq | GROQ_API_KEY | OpenAI-compatible, free tier | | openai-compatible / litellm | MAQ_PROVIDER_BASE_URL (MAQ_PROVIDER_API_KEY?) | any OpenAI-compatible endpoint / LiteLLM proxy | | cli:<agent> | — | reuse an authenticated worker CLI (e.g. cli:gemini, cli:codex) as the master's own model — $0 marginal (the user's existing subscription pays) |

$0 intelligence layer (maq models auto)

The master's own thinking (Scout/Plan/Verify) should cost ~$0. maq models inspects the environment and ranks the cheapest capable master model:

maq models list      # ranked catalog with availability + reasons
maq models cheapest  # the single best $0-or-cheapest option right now
maq models auto      # write that choice into config (provider + cheapModel)

Ranking (best first): an authenticated worker CLI (reuse the user's subscription, $0 marginal) → a free-tier key (Groq / Gemini Flash) → a local Ollama model → the cheapest paid key (gpt-4o-mini / haiku) → the offline heuristic ($0 floor). Heavy Worker executions stay BYO-key; only the light master loop is auto-optimized. This is the PRODUCTION_GUIDE "$0 daemon thinking" strategy, implemented.

Every call has an AbortController timeout (MAQ_MODEL_TIMEOUT_MS) and bounded retries with backoff (MAQ_MODEL_RETRIES) on 429/5xx/network errors. Real usage is used for token/cost accounting when the API returns it; prices come from a built-in table (override with MAQ_PRICES).

RouteLLM-style tiering

Cheap work (Scout triage, Verify review, non-complex Plan) routes to a cheap model; genuinely complex Plans escalate to a strong model. Configure both:

maq config set provider openai
maq config set cheapModel  gpt-4o-mini
maq config set strongModel gpt-4o
maq config set defaultTarget codex

Harness features (lift any model toward frontier-level results)

The point of the harness: a cheap model inside a good harness beats a strong model with no harness. These supply, externally, the mechanisms a long-horizon model does internally (plan → delegate → verify → self-improve):

• Skills / rules layer (maq skills) — standing instructions injected into planning, loaded from built-in defaults + ~/.maqcli/skills + project .maq/skills/*.md + AGENTS.md/CLAUDE.md. Tier-aware: scaffolding rules are dropped for the strong tier (rules written for a weak model hold a strong one back). maq skills init scaffolds starter files.
• Sub-agent isolation (maq subagent) — run a scoped sub-task in a fresh, minimal context that returns only a concise summary (containment over delegation), so you get the token savings of isolation.
• Safe tool registry (maq tools) — read_file / list_dir / grep_text / headroom_retrieve, sandboxed to the working dir; opt-in http_get (MAQ_ALLOW_NET=1). Advertisable as tool-use schemas.
• Session control (maq sessions <id> pause|resume|cancel) — pause at phase boundaries, resume, or cancel (kills in-flight worker processes via abort).
• Self-learning — verify failures append a lesson to AGENTS.md.

Set skillsDir and thinkingEffort via maq config.

Daemon + app seam

maq serve exposes the orchestrator over one normalized contract so the app never speaks any worker CLI's dialect:

GET  /health                     liveness (no auth)
GET  /v1/agents                  detected worker CLIs
GET  /v1/connectivity            connectivity tier probe
GET  /v1/sessions                list session summaries
POST /v1/sessions                start a session {task,target?,cwd?,dryRun?}
GET  /v1/sessions/:id            one session (summary + events)
GET  /v1/sessions/:id/events     SSE stream (replay history, then live)
POST /v1/sessions/:id/message    deliver a message to a session {text}

Security: every route except /health requires Authorization: Bearer <token> (constant-time compared). Binds to 127.0.0.1 by default; binding to all interfaces is allowed but logged loudly. Put a tunnel/tailnet in front for remote access rather than opening inbound ports.

Multi-agent coordination uses CAO-style vocabulary in the session registry: assign (async, fire-and-forget), handoff (sync, await completion), and sendMessage (inbox delivery) — the vocabulary, not the tmux/Bedrock runtime.

How it works

task ─▶ SCOUT ─▶ PLAN ─▶ EXECUTE ─▶ VERIFY ─▶ result
        (read-  (branch/  (worker    (tests as   │
         only,   filter/   CLI, live  ground      └▶ on failure: append a
         0-tok)  commit)   streamed)  truth)         lesson to AGENTS.md

• Complexity gating — trivial tasks skip Scout/Plan; standard/complex tasks get the full pipeline, keeping multi-agent overhead off work that doesn't need it.
• Verifier-gated planning — short candidate approaches scored against checkable structure; the first clear winner short-circuits the rest.
• Streamed execution — worker stdout/stderr is parsed line-by-line into normalized events (agent.stdout, agent.stderr, tool.call, agent.event) in real time; JSON-line streams (e.g. Claude Code) become structured events.
• Headroom-style compression — worker output is compressed before it would reach a model, with the original retrievable by reference.
• Verify-by-default + self-learning — tests are the ground truth; on failure a structured lesson is appended to AGENTS.md so the worker sees corrective guidance next time.

Configuration

~/.maqcli/config.json (override the directory with MAQ_CONFIG_DIR):

{
  "masterModel": "heuristic-local",
  "defaultTarget": "auto",
  "provider": "heuristic",
  "cheapModel": "heuristic-local",
  "strongModel": "heuristic-local",
  "compactionThreshold": 0.6,
  "projectTargets": {}
}

Extending

• New worker CLIs — add an entry to KNOWN_AGENTS in src/core/registry.ts.
• New providers — implement ModelProvider (see src/core/providers.ts) and register it in getProvider (src/core/model.ts).
• Upstream Headroom — swap the local Headroom class for the headroomlabs-ai/headroom engine without changing callers.

Status

The cli/ master tier is functional and tested (96 tests, package v0.15.1): offline pipeline, real model providers, RouteLLM-style tiering, streamed execution, a secure daemon with SSE + web UI, session/multi-agent management with pause/resume/cancel, crash-resume board, a real connectivity probe, a tier-aware skills/rules layer + discipline pool, sub-agent isolation, MCP, and a safe tool registry.

Full walkthrough: see GUIDE.md.