convez.ai
AgenteDevOps & InfraestruturaAvançado
mkober

MuxCode

mkober/muxcode

Ambiente de desenvolvimento multi-agent nativo de tmux com agentes especializados

Ver no GitHub
InicialPluginScore · de 0 a 100

Ambiente multi-agent de desenvolvimento construído sobre tmux, neovim e Claude Code. Dez agentes especializados (planejador, editor, builder, tester, etc.) rodam em janelas tmux independentes, coordenados por um barramento de mensagens baseado em arquivos, mantendo você sempre no controle do fluxo de desenvolvimento.

Instalação

$npx convez-ai mkober/muxcode

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
42%
Último commit
há 20 horas
Versão
v0.1.81
Issues abertas
61
Contribuidores
1

Casos de uso

  • Automação de ciclos completos de desenvolvimento (edição, build, testes, deploy)
  • Desenvolvimento colaborativo entre agentes IA e desenvolvedor humano em tempo real
  • Fluxos de trabalho determinísticos com roteamento baseado em hooks Go, não em LLM

Veredito

MuxCode é uma solução sofisticada e ambiciosa para orquestração de agentes IA em ciclos de desenvolvimento locais. Adota abordagens inteligentes (comunicação via arquivos JSONL, hooks determinísticos, permissões scoped) que a diferenciam de arquiteturas puramente LLM-roteadas, mas exige expertise significativa em Go, tmux e setup local para ser operacional.

README

A tradução para o português deste README ainda está na fila.

MuxCode

███╗   ███╗██╗   ██╗██╗  ██╗   ██████╗ ██████╗ ██████╗ ███████╗
████╗ ████║██║   ██║╚██╗██╔╝  ██╔════╝██╔═══██╗██╔══██╗██╔════╝
██╔████╔██║██║   ██║ ╚███╔╝   ██║     ██║   ██║██║  ██║█████╗
██║╚██╔╝██║██║   ██║ ██╔██╗   ██║     ██║   ██║██║  ██║██╔══╝
██║ ╚═╝ ██║╚██████╔╝██╔╝ ██╗  ╚██████╗╚██████╔╝██████╔╝███████╗
╚═╝     ╚═╝ ╚═════╝ ╚═╝  ╚═╝   ╚═════╝ ╚═════╝ ╚═════╝ ╚══════╝

A multi-agent coding environment built on tmux — where you stay in the loop.

MuxCode demo

What is MuxCode?

MuxCode is a tmux-native multi-agent development environment. Ten specialist AI agents — planner, editor, builder, tester, dev server, reviewer, deployer, runner, log watcher, and git manager — each run in their own tmux window, coordinated through a file-based message bus. You work in neovim alongside an editing agent, and every other part of the development lifecycle has its own dedicated agent a function key away.

You stay in control. The edit agent is your primary interface — it helps you write code and delegates to specialists when you're ready. Ask for a build, and the build agent runs it. Tests fire automatically on success. Review follows tests. Results flow back while you keep editing. The chain routing is hook-driven — Go hooks checking exit codes, not LLM routing decisions — so dispatch is deterministic and fast.

MuxCode supports multiple AI CLI providers. Each agent window can independently use Claude Code, OpenCode, Codex CLI, or a local LLM via Ollama — a single session can mix providers. Claude Code provides full hook support for deterministic chains. OpenCode brings multi-provider LLM access (Anthropic, OpenAI, Google, Groq, Bedrock) via its TUI. Codex CLI runs in full-auto mode with its own agent definitions. Ollama reduces API costs for structured-command roles. Provider assignment is per-agent at launch time via environment variables.

The coordination layer is entirely local. Agents communicate through JSONL files in /tmp/. Memory persists across sessions as markdown files. The bus binary is stdlib-only Go — no external dependencies, no containers, no databases. If Ollama goes down, affected agents fall back to Claude Code automatically, and the bus daemon handles restart and recovery.

Each agent has scoped tool permissions — the build agent can't edit files, the commit agent can't deploy infrastructure, the edit agent can't run builds or git commands. This separation prevents agents from stepping on each other and keeps the human in the loop for every code change.

┌──────────────────────────────────────────────────────────────────┐
│  F1 Plan  F2 Edit  F3 Build  F4 Test  F5 Serve  F6 Review        │
│  F7 Deploy  F8 Run  F9 Watch  F10 Commit                         │
├──────────────────────────────────────────────────────────────────┤
│                                                                  │
│  ┌──────────────┐    ┌──────────────┐    ┌──────────────┐        │
│  │ edit         │    │ build        │    │ test         │        │
│  │ nvim | agent │──→ │ term | agent │──→ │ term | agent │        │
│  └──────────────┘    └──────────────┘    └──────────────┘        │
│         │                                       │                │
│         │            ┌──────────────┐           │                │
│         └───────────→│ review       │←──────────┘                │
│                      │ term | agent │                            │
│                      └──────────────┘                            │
│                                                                  │
│  Message Bus: /tmp/muxcode-bus-{session}/                        │
│  Memory:      .muxcode/memory/                                   │
└──────────────────────────────────────────────────────────────────┘

How it works

You launch muxcode, pick a project (or pass a path directly), and a tmux session spins up with ten windows — one per agent. The plan window opens neovim on the left (showing the last-edited doc) and the plan agent on the right. The edit window opens neovim and the edit agent. Every other window has a terminal pane alongside its specialist agent.

A typical workflow looks like this:

  1. You edit code in neovim, talking to the edit agent when you need help.
  2. You ask for a build. The edit agent sends a request to the build agent, which runs your build command and reports back.
  3. Tests fire automatically. A bash hook detects the successful build and triggers the test agent — no LLM decision-making, just an exit code check.
  4. Review follows tests. Same pattern — if tests pass, the review agent picks up the diff and flags anything worth discussing.
  5. You iterate. Results flow back to the edit agent. If the reviewer finds issues, you fix them and kick off another cycle.
  6. You commit when ready. The commit agent handles staging, committing, and pushing. A pre-commit safeguard blocks commits if other agents still have pending work.

The entire build-test-review chain is hook-driven — Go hooks check exit codes and fire the next step. No tokens are spent on routing decisions, and the chain runs at the speed of your tools, not your LLM. Chain actions support conditional expressions — route builds to deploy on release branches, to test on feature branches — all config-driven with first-match-wins semantics.

The muxcode tui command launches a live dashboard showing which agents are busy, idle, or waiting on messages, so you always know what's happening across the session. You can add a dashboard window by including status in your MUXCODE_WINDOWS list.

Agents

MuxCode ships with ten specialist agents, each in its own tmux window:

Window (F-key)AgentWhat it does
plan (F1)PlannerMaintains requirements specs, architecture docs, and planning artifacts
edit (F2)Code editorYour primary interface — orchestrates by delegating, never runs build/test/git directly
build (F3)Code builderCompiles and packages your project
test (F4)Test runnerRuns your test suite and reports results
serve (F5)Dev serverStarts, monitors, and auto-restarts local development servers
review (F6)Code reviewerReviews diffs for bugs, style issues, and improvements
deploy (F7)Infra deployerRuns infrastructure deployments and diffs
run (F8)Command runnerExecutes ad-hoc commands
watch (F9)Log watcherMonitors logs — local files, CloudWatch, Kubernetes, Docker
commit (F10)Git managerHandles all git operations — commits, branches, rebases, pushes

Agent mode — Press F2 when already on the edit window to cycle to the autonomous agent, which reads Jira stories and drives the full story lifecycle (requirements → PR → implementation → PR) without user intervention. Press F2 again to cycle back to the editor. Both sessions persist across cycles. See Agents for details.

Additional roles that share a host agent's window or are available as opt-in:

RoleHost / accessWhat it does
analyzeOpt-in windowWatches file changes and provides codebase analysis — add analyze to MUXCODE_WINDOWS
apiModal popupAPI tester — opens via prefix + i or muxcode modal open api. Manages collections, executes requests, tracks history
docsplanDocumentation writer — handled by the plan agent
researcheditWeb search and codebase exploration — handled by the edit agent
pr-readcommitPR review analysis — handled by the commit agent
status—Live TUI dashboard (muxcode tui) — add status to MUXCODE_WINDOWS to include

Default model assignments

Out of the box, MuxCode uses Claude Code for orchestration roles and OpenCode for command-execution roles:

RoleDefault CLIDefault model
plan, editClaude Codeclaude-opus-4-8
reviewOpenCodeopencode-go/mimo-v2.5-pro
analyzeOpenCodeopencode-go/qwen3.6-plus
build, test, serve, deploy, run, watch, commitOpenCodeopencode-go/minimax-m2.7
apiClaude Codeclaude-sonnet-4-5

OpenCode Go models are available through OpenCode Go. Override the model per role with MUXCODE_{ROLE}_MODEL for OpenCode roles (e.g. MUXCODE_BUILD_MODEL=opencode-go/minimax-m2.7) or MUXCODE_{ROLE}_CLAUDE_MODEL for Claude Code roles. Override the CLI provider per role with MUXCODE_{ROLE}_CLI.

Recommended multi-provider configuration

The defaults above already provide a cost-effective split — Claude Code for orchestration (edit, plan) and OpenCode with role-specific models for everything else. To further customize, add Codex CLI for reasoning-heavy roles:

# ~/.config/muxcode/config or .muxcode/config

# Reasoning-heavy roles — Codex CLI with gpt-5.5
MUXCODE_REVIEW_CLI=codex
MUXCODE_ANALYZE_CLI=codex

# Cost optimization — use Haiku for API role
MUXCODE_API_CLAUDE_MODEL=claude-haiku-4-5

This gives you:

RoleProviderModelWhy
editClaude CodeOpus 4.8Full hook support, orchestration, code editing
commitOpenCodeMiniMax M2.7Git operations — prompt-instructed chains
buildOpenCodeMiniMax M2.7Runs ./build.sh — structured commands, no hooks needed
testOpenCodeMiniMax M2.7Runs ./test.sh — structured commands, no hooks needed
serveOpenCodeMiniMax M2.7Dev server lifecycle — start, monitor, restart
deployOpenCodeMiniMax M2.7Runs CDK/terraform — command execution role
runOpenCodeMiniMax M2.7Ad-hoc commands — capable free model
watchOpenCodeMiniMax M2.7Log tailing — lightweight, read-only
reviewCodex CLIgpt-5.5Deep code reasoning, thorough diff analysis
analyzeCodex CLIgpt-5.5Codebase-wide analysis, pattern detection

Provider tradeoffs:

ProviderHooksChainsIdle detectionSandboxBest for
Claude CodeYesDeterministicYesNoEdit, commit — need hooks + control
OpenCodeNoPrompt-instructedLimitedNoBuild, test, deploy — command execution
Codex CLINoPrompt-instructedHeuristicYesReview, analyze — read-only reasoning
Local LLMNoPrompt-instructedNoNoCost-sensitive structured commands

Codex CLI sandbox restriction: Codex CLI sandboxes all filesystem writes and blocks outbound network access. This makes it unsuitable for roles that write to .git (commit) or push to remotes. Use Claude Code or OpenCode for git operations. Codex is best for read-only roles like review and analyze.

Any role can use any provider. Set MUXCODE_{ROLE}_CLI to claude, opencode, codex, or local:

  • MUXCODE_{ROLE}_CLI=claude — Claude Code (full hook support, deterministic chains)
  • MUXCODE_{ROLE}_CLI=opencode — OpenCode TUI (multi-provider LLM access, autonomous context management)
  • MUXCODE_{ROLE}_CLI=codex — Codex CLI (OpenAI models, sandboxed — read-only roles only)
  • MUXCODE_{ROLE}_CLI=local — Local LLM via Ollama (free, structured commands)

Per-role model selection is also supported via MUXCODE_{ROLE}_CLAUDE_MODEL (Claude Code), MUXCODE_{ROLE}_CODEX_MODEL (Codex CLI, default gpt-5.5), or MUXCODE_{ROLE}_MODEL (OpenCode/local, falls back to MUXCODE_OLLAMA_MODEL, default qwen2.5-coder:7b). If Ollama is unreachable at launch, affected agents fall back to Claude Code automatically.

Each agent has constrained tool permissions — the build agent can run builds but can't edit files, the commit agent can run git but can't deploy infrastructure. This separation prevents agents from stepping on each other. Tool profiles are automatically translated to each provider's permission format (Claude Code's --allowedTools, OpenCode's permission blocks, or the harness's IsToolAllowed()).

You can customize or replace any agent by dropping a markdown file in .claude/agents/ (per-project) or ~/.config/muxcode/agents/ (global). See Agents for details.

Key features

Multi-CLI provider support

  • Provider interface — Abstraction layer (bus/provider.go) encapsulating all CLI-specific behavior: launch, idle detection, notifications, lifecycle management, and agent configuration
  • Claude Code provider — Full integration: hook-driven chains, idle prompt detection, startup acceptance, /compact injection, --allowedTools permissions
  • OpenCode provider — TUI mode integration: bare opencode binary launch, box-drawing frame detection, display-message notifications, auto-compact, permission block generation. Multi-provider LLM access (Anthropic, OpenAI, Google, Groq, Bedrock)
  • Codex CLI provider — Automatic approval mode: codex -a never --no-alt-screen launch, .codex/AGENTS.md generation, send-keys wake-up with message payload injection, heuristic task completion detection
  • Per-agent provider assignment — Each tmux window independently resolves its CLI via MUXCODE_{ROLE}_CLI. A single session can mix Claude Code, OpenCode, Codex CLI, and local LLM agents
  • Graceful degradation — Non-hook providers (OpenCode, Codex CLI, local LLM) degrade gracefully: chains disabled (system prompt instructs bus messaging instead), idle detection skipped, tool profiles translated to provider-native permission format
  • Hot reload — Switch any agent's CLI provider or model at runtime without restarting the session. muxcode reload <role> --cli opencode --model opencode-go/mimo-v2.5-pro gracefully stops the agent, writes session-scoped runtime overrides, and relaunches. Provider selector modal (Prefix + R) provides a visual TUI for browsing installed providers and models. Persistent config via muxcode config set/get/list with full resolution chain: runtime override → per-role env → global env → config file → default
  • Interactive installer — install.sh detects and offers to install Claude Code, OpenCode, and Codex CLI, with default provider selection when multiple are available

Agent orchestration

  • 10 specialist agents — Plan, edit, build, test, serve, review, deploy, run, watch, and commit — each with scoped tool permissions and its own tmux window
  • Autonomous agent mode — An autonomous agent shares the F2 window with the editor. Press F2 to cycle between them. The agent reads Jira stories, creates requirements docs, opens review PRs, implements approved requirements, and submits completed PRs — all without user intervention. Configurable via natural-language task files (.muxcode/agent-tasks.md) and a customizable story-lifecycle skill
  • Hook-driven automation chains — Build→test→review and deploy→run→watch chains fire via bash exit codes. Deterministic, fast, zero token cost for routing
  • Conditional chain actions — Chain actions support 8 condition types (files_match, branch_match, env_set, output_contains, etc.) with first-match-wins on action arrays. Route builds to deploy on release branches, to test on feature branches — all config-driven
  • Event subscriptions — Fan-out after chain execution. Subscribe any agent to build/test/deploy/run/watch events with outcome and condition filtering
  • Spawned agents — Create temporary agents for one-off tasks in their own tmux window. Results collected automatically on completion
  • Modal windows — On-demand overlay windows for specialized tasks. API testing opens via prefix + i or muxcode modal open api. Declarative config with size presets and optional pane splits
  • Pre-commit safeguards — Commit delegation blocked when other agents have pending work, preventing incomplete commits
  • Workflow state machine — Persistent state tracking through the development lifecycle (idle → editing → building → testing → reviewing → committing → deploying → running → watching). 16 states with automatic regression on file edits, color-coded display. Query with muxcode workflow

Local LLM & cost control

  • Ollama integration — Any agent role can run via a local LLM instead of Claude Code. Per-role model selection via MUXCODE_{ROLE}_MODEL
  • Ollama health monitoring — Watcher detects stuck inference (not just process liveness), auto-restarts Ollama and affected agents with 3-strike escalation
  • LLM harness — Standalone binary with guardrails for smaller models: tool call filtering, loop prevention, structured task formatting, corrective feedback
  • Agent health monitoring — Watcher probes agent tmux panes every 30s, auto-restarts dead agents after 3-strike escalation (log → alert → restart)

Transactional messaging

  • Delivery tracking — Every message gets a delivery status (sent → delivered → responded → expired). Track with muxcode track <msg-id>
  • Task tracking — Delegated work is tracked with timeouts. The --wait flag on send commands creates a task entry and polls until a response arrives. List in-flight tasks with muxcode tasks
  • Message dedup — Duplicate messages (same sender/target/action/type) within a 30-second window are atomically suppressed to prevent chain loops

Memory & context

  • Persistent memory — Two-layer system: project-level (.muxcode/memory/) and global (~/.config/muxcode/memory/). Daily rotation with 30-day archive retention
  • BM25 search — Search memory across projects and sessions with IDF weighting, stemming, stop words, and quoted phrase matching
  • Drop-in context files — Per-role context injection via context.d/ directories. Auto-detects 17 project types (Go, Node.js, Python, Rust, CDK, etc.)
  • Skills and plugins — Reusable instruction sets in markdown that auto-inject into agent prompts based on role
  • Session compaction — Agents snapshot context to memory for long-running sessions. Watcher triggers compaction alerts when context approaches limits

Developer experience

  • Managed Neovim config — MuxCode ships its own neovim configuration via NVIM_APPNAME=muxcode, fully isolated from your personal ~/.config/nvim/. Includes Dracula theme, treesitter, render-markdown.nvim, telescope, and vim-tmux-navigator out of the box. Extend with ~/.config/muxcode/nvim/lua/user/plugins.lua
  • Inline diff preview — Every Write/Edit tool call opens a scrollbound diff split in neovim before you accept or reject
  • Inline response delivery — The --wait flag on send commands polls for responses inline — no manual inbox checking needed
  • Left-pane pollers — Each window shows live history: build/test results with pass/fail stats, review findings, deploy status, git log, API history, analyze insights
  • Live TUI dashboard — Dracula-themed dashboard showing agent status, message flow, and session health
  • Demo mode — Scripted demo scenarios that replay bus message sequences with tmux window switching, suitable for screen recording and presentations. Run with muxcode demo
  • Session inspection — Query any agent's status, message history, or busy state from the CLI

Automation & integration

  • Webhook HTTP endpoint — HTTP-to-bus bridge for CI/CD, GitHub webhooks, monitoring. Optional bearer token auth
  • Cron scheduling — Recurring tasks on intervals (@every 5m, @hourly, @daily), managed by the bus daemon
  • Background process tracking — Launch long-running processes, track status, get notified on completion
  • Atlassian integration — Jira issue descriptions, PR comments, and Confluence page updates via Atlassian REST API. Jira key extracted from branch name, Confluence pages identified by ID, URL, or space+title
  • Lifecycle logging — Persistent JSONL logs recording the full startup-to-cleanup lifecycle. Survives session restarts, filterable by source/level/event/time

Safety & guardrails

  • Scoped tool permissions — Per-role tool profiles enforce what each agent can and can't do. Build can't edit files, commit can't deploy, edit can't run builds
  • Loop detection — Bus detects agents stuck in repetitive patterns and escalates to the edit agent
  • Edit guard — Sync hook blocks prohibited commands (build, test, git, deploy) in the edit window with delegation instructions
  • PII scrubbing — Automatic redaction of emails, SSNs, credit cards, AWS keys, JWTs, and other secrets from tool output in PII-sensitive roles (api, runner, watch)
  • Daemon self-monitoring — Keepalive heartbeat with companion monitor process (watch --monitor) — auto-restarts the daemon if it hangs

See the Architecture and Agent Bus docs for the full details.

How MuxCode compares to autonomous AI coding tools

Tools like OpenClaw, Devin, OpenHands, and SWE-agent push toward fully autonomous software engineering — give the AI a task, let it plan and execute end-to-end with minimal human input. MuxCode shares some of the same building blocks but takes a different approach to how humans and AI agents collaborate.

OpenClaw is a good point of comparison because it's also open-source and runs locally. It's a long-running Node.js service that acts as a message router between chat platforms (WhatsApp, Telegram, Discord) and an AI agent that can browse the web, read and write files, and run shell commands autonomously. It can manage Claude Code sessions, run tests, capture errors via Sentry, and open PRs on GitHub — all without you in the loop. MuxCode solves many of the same problems but keeps you in your terminal, in your editor, making the decisions.

What they have in common

Both MuxCode and autonomous AI tools solve the same coordination problems:

  • Persistent memory — Context that survives across sessions, searchable and shared between agents
  • Skills and plugins — Reusable instruction sets that shape agent behavior for specific tasks or domains
  • Event-driven automation — Chains of actions that trigger automatically based on outcomes
  • Session management — Context compaction, history tracking, and long-running session support
  • Background process tracking — Launching, monitoring, and reacting to long-running tasks
  • Loop detection — Guardrails that catch agents stuck in repetitive failure patterns

Where MuxCode differs

Human-in-the-loop, not fully autonomous. MuxCode keeps you as the orchestrator. The edit agent delegates on your behalf — you see every step, you decide what happens next. Autonomous tools aim to minimize human involvement, handling planning, execution, and error recovery on their own.

Local-first, minimal infrastructure. The message bus is JSONL files in /tmp/. The memory system is markdown files in your project directory. There's no database, no container runtime. An optional webhook HTTP endpoint bridges external tools (CI/CD, GitHub) to the bus, but it's a single lightweight server — not a required runtime. Autonomous tools typically require a runtime environment — SQLite, vector databases, sandboxed execution containers.

Tmux-native, editor-centric. You work in your actual editor alongside the agents. Press F3 to watch the build agent work. Press F9 to see the commit agent run git commands. There's no web UI, no chat interface separate from your terminal. Autonomous tools typically abstract the execution environment behind an API or web interface.

Hook-driven orchestration, not LLM-driven. The build-test-review and deploy-run-watch chains fire via exit codes in Go hooks — deterministic, fast, zero token cost for routing. Conditional chain actions add branch-aware, file-aware routing without leaving the config-driven model. Autonomous tools typically use the LLM itself to decide what to do next, which is more flexible but slower and more expensive.

Composable specialists, not a monolithic agent. Each agent is a focused role with constrained permissions. The build agent can't edit files. The commit agent can't deploy. The serve agent manages dev servers but can't modify source code. This separation of concerns mirrors how teams actually work. Autonomous tools often use a single agent with broad capabilities that handles everything.

Zero external dependencies. The bus binary is stdlib-only Go — it compiles in seconds with no dependency management. The launcher, agent bootstrap, and hooks are all Go subcommands of the single muxcode binary (with utility shell scripts for tmux/vim timing-sensitive operations). Autonomous tools typically have significant dependency trees (Python packages, Node modules, system libraries).

The tradeoff is clear: autonomous tools can handle more without you, but MuxCode gives you visibility and control at every step. If you want to understand what's happening in your codebase — not just get a result — MuxCode is designed for that workflow.

Quick start

Prerequisites

  • tmux >= 3.0
  • Go >= 1.22
  • At least one AI CLI provider:
    • Claude Code CLI (claude) — recommended, full hook support
    • OpenCode (opencode) — alternative, multi-provider LLM access
    • Codex CLI (codex) — alternative, OpenAI models
  • jq
  • Neovim
  • fzf (optional, for interactive project picker)
  • Ollama (optional, for local LLM agents)

Install

git clone https://github.com/mkober/muxcode.git
cd muxcode
./install.sh

The installer checks prerequisites, builds the Go binary, and installs everything to ~/.local/bin/ and ~/.config/muxcode/. It interactively detects and offers to install AI CLI providers (Claude Code, OpenCode, and/or Codex CLI), sets up the managed neovim config (via NVIM_APPNAME=muxcode), tmux integration, and Claude Code hooks (when Claude Code is selected). Your personal ~/.config/nvim/ is never modified.

For subsequent builds after pulling updates:

./build.sh

Launch

# Interactive project picker (requires fzf)
muxcode

# Direct path
muxcode ~/Projects/my-app

# Custom session name
muxcode ~/Projects/my-app my-session

Workspace trust

When Claude Code opens a new workspace for the first time, it shows a "Yes, I trust this folder" safety prompt in every agent window. MuxCode automatically accepts this prompt on your behalf — a background process polls each agent pane after launch and presses Enter on any window showing the trust dialog. This runs over ~18 seconds to catch slow-starting agents, and skips panes that are already past the prompt.

Configuration

MuxCode uses a shell-sourceable config file. Resolution order:

  1. $MUXCODE_CONFIG (explicit path)
  2. .muxcode/config (project-local)
  3. ~/.config/muxcode/config (user global)
  4. Built-in defaults

See Configuration for the full variable reference.

Runtime configuration

Switch providers or models at runtime without restarting your session:

# Reload a single agent with a different provider/model
muxcode reload review --cli codex --model gpt-5.5

# Reload with compaction (saves context before restart)
muxcode reload build --cli opencode --compact

# Reload all agents
muxcode reload --all

# Persistent config (survives session restarts)
muxcode config set MUXCODE_BUILD_CLI opencode
muxcode config get MUXCODE_BUILD_CLI
muxcode config list

Or press Prefix + R to open the visual provider selector — browse installed providers and models, pick one, and the agent reloads automatically.

OpenCode agents

Any agent role can run via OpenCode instead of Claude Code. OpenCode is an open-source AI coding agent with multi-provider LLM support (Anthropic, OpenAI, Google, Groq, Bedrock) and a full TUI interface. This is useful when you want to use non-Anthropic models for specific roles or take advantage of OpenCode's autonomous context management.

Setup

  1. Install OpenCode:

    curl -fsSL https://opencode.ai/install | bash
    
  2. Set per-role overrides in .muxcode/config:

    MUXCODE_BUILD_CLI=opencode     # build agent uses OpenCode
    MUXCODE_TEST_CLI=opencode      # test agent uses OpenCode
    

    Or set the session-wide default:

    MUXCODE_AGENT_CLI=opencode     # all agents use OpenCode
    MUXCODE_EDIT_CLI=claude        # except edit — keep Claude Code for hooks
    
  3. Launch MuxCode normally — configured roles launch the OpenCode TUI, others use Claude Code.

How it works

OpenCode agents run as interactive TUI sessions in their tmux panes. MuxCode generates per-role agent definitions in .opencode/agents/<role>.md with tool permissions translated from muxcode's tool profiles. The TUI manages its own context window, compaction, and tool execution autonomously.

Since OpenCode has no hook system, chain-driven features (build→test→review, deploy→run→watch) are replaced with config-driven prompt instructions generated by buildChainInstruction() — each agent only sees chain commands relevant to its role, including condition descriptions for conditional actions. Agent definition body text is adapted to replace hook chain references with manual commands, and the send policy is bypassed so non-hook agents can actually send chain messages. Wake-up notifications inject message content directly into the TUI input via send-keys. This same graceful degradation applies to all non-hook providers (OpenCode, Codex CLI, local LLM).

Limitations

FeatureBehavior with OpenCode
Build/test/review chainsRole-specific prompt instructions + adapted body text + send policy bypass (best-effort) instead of hook-driven (deterministic)
Edit guardDisabled — relies on OpenCode's native permission blocks
Workflow state transitionsSkipped for non-hook agents
Idle detectionNot supported — agent always treated as "active"
Wake-upMessage content injected via send-keys into TUI input
CompactNo-op from muxcode — OpenCode auto-compacts at 95% context

Codex CLI agents

Any agent role can run via Codex CLI instead of Claude Code. Codex CLI is OpenAI's open-source coding agent that runs in your terminal with access to OpenAI models (GPT-4.1, o3, o4-mini, etc.).

Setup

  1. Install Codex CLI:

    npm install -g @openai/codex
    
  2. Set per-role overrides in .muxcode/config:

    MUXCODE_ANALYZE_CLI=codex     # analyze agent uses Codex CLI
    

    Or set the session-wide default:

    MUXCODE_AGENT_CLI=codex       # all agents use Codex CLI
    MUXCODE_EDIT_CLI=claude       # except edit — keep Claude Code for hooks
    
  3. Launch MuxCode normally — configured roles launch codex -a never --no-alt-screen, others use their default provider.

How it works

Codex CLI agents run with automatic approval (-a never) without the alternate screen buffer (--no-alt-screen) so tmux pane capture works for idle detection and task completion. MuxCode generates a shared agent definition at .codex/AGENTS.md with tool permissions and bus instructions. Wake-up notifications inject message content directly via send-keys.

Since Codex CLI has no hook system, the same three-layer graceful degradation used by OpenCode applies: role-specific prompt instructions, agent body adaptation, and send policy bypass.

Limitations

FeatureBehavior with Codex CLI
SandboxAll filesystem writes sandboxed, outbound network blocked — do not use for commit, deploy, or any role that writes to .git or pushes to remotes
Build/test/review chainsRole-specific prompt instructions + send policy bypass (best-effort) instead of hook-driven (deterministic)
Edit guardDisabled — relies on Codex's native sandbox
Workflow state transitionsSkipped for non-hook agents
Idle detectionHeuristic — detects > prompt or "Summarize" text
Wake-upMessage content injected via send-keys with payload
CompactNo-op from muxcode
Agent configShared .codex/AGENTS.md file (not per-role)

Local LLM agents

Any agent role can run via a local LLM (Ollama) instead of Claude Code. This is useful for roles that primarily execute structured commands — git operations, builds, log monitoring — where a small model is sufficient and API costs add up.

Setup

  1. Install and start Ollama:

    brew install ollama
    ollama serve
    ollama pull qwen2.5-coder:7b
    
  2. Set per-role overrides in .muxcode/config:

    MUXCODE_COMMIT_CLI=local    # commit agent uses local LLM
    MUXCODE_BUILD_CLI=local     # build agent uses local LLM
    
  3. Launch MuxCode normally — configured roles run via Ollama, others use Claude Code. If Ollama is unreachable at launch, the agent falls back to Claude Code automatically.

Configuration

VariableDefaultDescription
MUXCODE_{ROLE}_CLI(unset)Set to local to use Ollama (e.g. MUXCODE_COMMIT_CLI=local)
MUXCODE_OLLAMA_MODELqwen2.5-coder:7bOllama model name
MUXCODE_OLLAMA_URLhttp://localhost:11434Ollama server URL

Recommended models

ModelSizeBest forNotes
qwen2.5-coder:7b4.7 GBBuild, test, git, general agent tasksDefault model — strong code understanding at low resource cost
qwen2.5-coder:14b9.0 GBReview, analysis, docsBetter reasoning for tasks that need more nuance
deepseek-coder-v2:16b8.9 GBReview, analysis, complex code tasksStrong at code review and multi-file reasoning
codellama:7b3.8 GBBuild, test, gitLightweight alternative to Qwen for structured commands
llama3.1:8b4.7 GBGeneral-purpose agent tasksGood all-rounder when code specialization isn't critical

For most setups, qwen2.5-coder:7b is sufficient for command-execution roles (build, test, git, watch). Upgrade to a 14b+ model for roles that reason about code (review, analyze, docs).

Health monitoring

The bus daemon monitors Ollama inference health (not just process liveness) and auto-restarts both Ollama and affected agents when inference hangs. Up to 3 automatic restarts per session, then periodic alerts for manual intervention.

LLM harness

For smaller models that struggle with structured tool calling, the standalone muxcode-llm-harness binary provides guardrails: tool call filtering, loop prevention, structured task formatting, corrective feedback, and single-shot auto-complete for build/test roles. The harness includes a Dracula-themed TUI with a live activity log showing Ollama calls, tool executions with output previews, and a status bar. The launcher prefers the harness when available.

Harness-specific agent definitions in agents/harness/ provide simplified instructions tailored for local LLMs — shorter, more directive prompts that avoid confusing smaller models with bus messaging or multi-step discovery sequences.

See Agents for the full reference.

Skills

Skills are reusable instruction sets defined as markdown files with YAML frontmatter. They auto-inject into agent prompts based on role, giving agents domain-specific knowledge without editing agent definitions.

Built-in skills

SkillRolesDescription
git-commit-conventionscommit, editCommit message format and git workflow conventions
go-testingtest, buildGo testing patterns and conventions
code-review-checklistreviewCode review quality checklist
github-pr-commentcommitPost threaded replies to Copilot review comments on PRs and summary comments addressing all feedback
jira-pr-commentcommitPost PR details as a comment on the corresponding Jira issue
jira-manage-issuescommit, editFull Jira issue lifecycle — read, update, search (JQL), transition status, link dependencies, read/post comments, create subtasks
confluence-update-pagecommit, editRead and update Confluence pages with ADF content
docs-managementplan, editDocumentation lifecycle — move specs, update status, check off phases, cross-reference verification
agent-debugeditDiagnostic procedures for inspecting agent state, checking idle/active status, and troubleshooting stuck agents

Resolution order

  1. .muxcode/skills/ — project-local (highest priority, shadows by name)
  2. ~/.config/muxcode/skills/ — user global
  3. skills/ — installed defaults

Creating skills

muxcode skill create my-skill "Description" --roles build,test --tags ci,workflow "Skill body here"

Or drop a markdown file in .muxcode/skills/:

---
name: my-skill
description: What the skill does
roles: [build, test]
tags: [ci, workflow]
---

Instructions for the agent...

Atlassian integration

Three skills integrate with Atlassian Cloud via the REST API:

  • jira-pr-comment — The git-manager agent posts a comment on the Jira issue when a PR is created, including the PR link with diff stats. Extracts the Jira key from the branch name (e.g. DATA-456-add-validation → DATA-456).
  • jira-manage-issues — Full Jira issue lifecycle: read (with links/subtasks), update descriptions, search via JQL, transition status, link dependencies, read/post comments, create subtasks. Available to the commit and edit roles.
  • confluence-update-page — Reads and updates Confluence pages using ADF. Pages identified by page ID, Confluence URL, or space key + title. Supports full replacement, append mode, and CQL search. Available to the git and edit roles.

Add to .muxcode/config or ~/.config/muxcode/config:

JIRA_BASE_URL="https://your-org.atlassian.net"
JIRA_USER_EMAIL="you@example.com"
JIRA_API_TOKEN="your-atlassian-api-token"

# Optional: override base URL for Confluence (defaults to JIRA_BASE_URL)
# CONFLUENCE_BASE_URL="https://your-org.atlassian.net"

If the env vars are missing, all Atlassian skills skip silently. Jira skills also skip if the branch name doesn't start with a Jira key.

Tmux tips

Useful keybindings for navigating your MuxCode session:

KeybindingAction
F1–F10Switch between agent windows (plan, edit, build, test, serve, review, deploy, run, watch, commit)
F2 (on edit window)Cycle agent mode (edit → agent → edit)
Prefix + aCycle edit-window agents from any window
Prefix + ROpen provider selector (hot reload)
Prefix + iOpen API testing modal
Prefix + bOpen MuxCode quick menu
Prefix + CNew MuxCode session (project picker)
Prefix + zZoom current pane to full screen
Prefix + [Enter scroll/copy mode
Prefix + dDetach from session
Ctrl + h/j/k/lSwitch panes (vim-style, works across nvim and tmux)
Prefix + cNew tmux window
Prefix + n / Prefix + pNext / previous window
Prefix + wWindow list
Prefix + sSession list
Prefix + xClose current pane
Prefix + %Split pane horizontally
Prefix + "Split pane vertically
Prefix + :Tmux command prompt
Prefix + ?List all keybindings

Documentation

  • Architecture — System design, data flow, and hook chains
  • Agent Bus — CLI reference for muxcode
  • Agents — Role descriptions and customization
  • Hooks — Hook system details
  • Configuration — Config file and environment variable reference

License

MIT

Ver o original no GitHub

Bom para

Relacionados