English | Русский

aimux is an MCP server for durable task state, session operations, deep research, binary upgrades, and caller-centered structured reasoning.

The current post-purge live surface is intentionally small:

• 4 server tools: status, sessions, deepresearch, upgrade
• 1 methodology-bearing task entry point for code and review workflows
• 1 caller-centered think harness plus 22 cognitive move tools

The former CLI-launching MCP tools (exec, agent, agents, critique, investigate, consensus, debate, dialog, audit, workflow) were removed from the live surface. Their pre-purge architecture is frozen at snapshot/v5.0.3-pre-cli-purge and documented in docs/architecture/cli-tools-current.md. The next Layer 5 surface is tracked separately by AIMUX-9 / DEF-1.

Download the latest release binary for your platform:

Windows (PowerShell):

$version = "5.12.0"
gh release download "v$version" --repo thebtf/aimux --pattern "aimux_${version}_windows_amd64.zip" --output aimux.zip
Expand-Archive aimux.zip -DestinationPath "$env:LOCALAPPDATA\aimux" -Force
Remove-Item aimux.zip
# Add to PATH (current session):
$env:PATH = "$env:LOCALAPPDATA\aimux;$env:PATH"
aimux.exe --version

Linux / macOS (bash):

version="5.12.0"
os=$(uname -s | tr '[:upper:]' '[:lower:]')
arch=$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')
gh release download "v${version}" --repo thebtf/aimux --pattern "aimux_${version}_${os}_${arch}.tar.gz" --output aimux.tar.gz
mkdir -p ~/.local/bin
tar xzf aimux.tar.gz -C ~/.local/bin aimux
rm aimux.tar.gz
chmod +x ~/.local/bin/aimux
aimux --version

$env:GOTOOLCHAIN = "go1.25.10"
go build -o aimux.exe ./cmd/aimux/
.\aimux.exe --version

Requires Go 1.25.10 or newer.

Add aimux to .mcp.json (Claude Code) or the equivalent config for your MCP client:

{
  "mcpServers": {
    "aimux": {
      "command": "aimux",
      "args": []
    }
  }
}

If the binary is not on PATH, use the full path:

{
  "mcpServers": {
    "aimux": {
      "command": "C:/Users/you/AppData/Local/aimux/aimux.exe",
      "args": []
    }
  }
}

Run tools/list from any MCP-capable client. A current build should expose 28 tools: the 4 server tools, the task entry point, the think harness, and 22 cognitive move tools.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

Common development and release checks:

$env:GOTOOLCHAIN = "go1.25.10"
go build ./...
go test ./... -count=1 -timeout 300s
go test ./tests/critical -count=1 -timeout 300s
$env:AIMUX21_E2E = "1"
go test ./test/e2e -run 'TestE2E_(AIMUX21|CodeEntry|ReviewEntry|TaskRouter|Resume)' -count=1 -timeout 600s
go vet ./...
go mod verify
govulncheck ./...

Set-Location loom
go test ./... -count=1

Use docs/PRODUCTION-TESTING-PLAYBOOK.md for customer-mode release walkthroughs.

The task tool supports three code execution modes controlled by the navigator parameter:

Codex CLI always uses --dangerously-bypass-approvals-and-sandbox --skip-git-repo-check --json. Prompt delivered via stdin controls mode behavior.

think(action=start|step|finalize) is the canonical caller-centered thinking harness. The caller owns the final answer; aimux tracks visible work products, evidence, gate status, confidence ceilings, unresolved objections, budget state, and a bounded trace_summary.

Typical flow:

1. think(action=start, task=..., context_summary=...) creates a session and returns allowed cognitive moves plus a first prompt.
2. think(action=step, session_id=..., chosen_move=..., work_product=..., evidence=[...], confidence=...) records a visible move result and returns gate/confidence feedback.
3. think(action=finalize, session_id=..., proposed_answer=...) accepts only when the loop, evidence, confidence, objections, and budget gates support it.

Legacy think(thought=...) calls fail closed with a migration error. They do not route by keywords, create implicit sessions, or return pattern suggestion fields.

The 22 cognitive move tools provide in-process structured reasoning moves. They do not spawn AI CLIs.

Each per-pattern result includes gate status and an advisor recommendation. Stateless calls return gate_status: "complete"; stateful pattern sessions can request additional steps when the gate finds missing evidence or insufficient reasoning depth.

flowchart TD
    Client[MCP client] --> Server[aimux MCP server]
    Server --> Budget[response budget layer]
    Budget --> Sessions[sessions/status handlers]
    Budget --> Research[deepresearch handler]
    Budget --> Upgrade[upgrade handler]
    Budget --> Think[think harness and cognitive move handlers]
    Budget --> Task[task router]

    Sessions --> Loom[LoomEngine]
    Task --> Loom
    Task --> CodeWorker[code worker: pair / solo write / solo diff]
    Task --> ReviewWorker[review worker: structural / behavioural / adversarial]
    CodeWorker --> Codex[codex CLI via pipe + stdin]
    Loom --> SQLite[(SQLite task/session state)]
    Research --> Gemini[Gemini SDK]
    Think --> Gates[pattern gates and advisor]
    Upgrade --> Binary[local or release binary swap]

Loom is the canonical runtime job/task state backend. The legacy JobManager runtime backend has been removed. Public session/status responses read from Loom-managed task state and legacy session metadata where needed for migration visibility.

The Loom engine is also a standalone nested Go module:

• Module path: github.com/thebtf/aimux/loom
• Consumer guide: loom/USAGE.md
• Contract: loom/CONTRACT.md
• Recovery guide: loom/RECOVERY.md

Current production surface:

• Session and task health/status operations.
• Deep research through Gemini SDK.
• Binary update with local source install and deferred fallback when live handoff is not supported.
• Caller-centered think harness and 22 local cognitive move tools.
• Loom-backed task state and recovery.
• Task entry point with 3 execution modes: pair (driver+navigator), solo write, solo diff.

Out of current scope:

• Agent registry execution over MCP.
• Multi-model orchestration tools over MCP.
• Pipeline v5 Layer 5 exposure (beyond the task entry point).

Those removed surfaces are not runtime defects in the current build. They are future design work under AIMUX-9 / DEF-1.

Before a release:

1. Build with Go 1.25.10 or newer.
2. Run the full Go test suite.
3. Run the critical suite under tests/critical/.
4. Run go vet, go mod verify, and govulncheck.
5. Walk through docs/PRODUCTION-TESTING-PLAYBOOK.md in customer mode.
6. Verify installed/running binary freshness with upgrade(action="check").
7. Verify local-source install through an MCP client or mcp-launcher -mode install.

MIT. See LICENSE.