From parallel tasks
to one verified result.

How Muxtra works

Muxtra gives each coding agent an isolated Git worktree, launches it with the repository’s operating rules, and only combines work that has passed your project checks.

Install Muxtra

Muxtra is currently in public beta and requires Node.js 20 or newer and Git. Install the beta CLI with npm:

npm install --global muxtra@beta
muxtra --version

Beta releases use npm's beta tag. Because this is Muxtra's first npm release, npm also resolves the untagged package name to this build until a stable release exists. Use muxtra@beta to stay on the intended prerelease channel.

Update an npm installation to the newest beta release at any time:

muxtra update

Then open the Git project you want to use and confirm that Muxtra can safely operate it:

cd your-project
muxtra setup
muxtra doctor

Your first parallel run

Open an existing Git project with at least one commit. Prepare it once, then give the task a short tracking title:

cd your-project
muxtra setup
muxtra start "Build the dashboard navigation" --agent codex

Setup creates and commits .muxtra/project.yaml so every isolated agent sees the same workflow. Muxtra detects common package checks automatically and stops with clear instructions if your project still needs checks configured.

The quoted title names the workspace, branch, and status entry; it is not sent as the agent's first user prompt. Give the full request in the native agent session, or use --prompt when you deliberately want to send it immediately:

muxtra start "Dashboard navigation" --agent codex --prompt "Implement responsive dashboard navigation using the existing design system."

In another terminal, open a separate task with a different provider:

muxtra start "Add dashboard search" --agent claude
muxtra status

Give each responsibility the right model

The design lane owns UI, frontend implementation, responsive behavior, and accessibility. The code lane owns backend logic, state, data, integrations, architecture, and tests. Each lane can use a different CLI provider and an exact model—or rely on that provider’s default model.

muxtra lanes set design --agent claude --model <claude-model>
muxtra lanes set code --agent codex --model <codex-model>
muxtra lanes

muxtra team "Build account settings"

muxtra team creates two linked, isolated workspaces and prints one muxtra launch command for each native CLI. After both agents commit and finish verification, run the exact two-task muxtra combine command shown in the output. The team title is tracking metadata; each agent waits for its own detailed request after launching.

Finish, verify, and combine

When an agent has committed its changes, it runs muxtra finish. Muxtra requires a clean workspace, verifies that it is ahead of and fresh against its recorded base, runs configured checks, records the exact verified commit, and releases the agent’s active claims.

muxtra finish dashboard-navigation
muxtra finish dashboard-search
muxtra combine

muxtra combine creates a temporary composition, merges the selected verified tasks, runs the project checks again, and only then advances the primary project. If a merge or combined-only check fails, your main checkout remains untouched.

Use the agent that fits the task

Muxtra can directly launch Codex CLI and Claude Code. The workspace and committed project workflow are supplied automatically, and the agent keeps its complete native interface for reasoning, tool calls, approvals, and conversation.

muxtra start "Fix the checkout" --agent codex
muxtra launch checkout-polish --agent claude --model <model> --prompt "Polish the final UI"

For ChatGPT or another client Muxtra cannot launch directly, generate a portable handoff and paste it into that client:

muxtra instructions checkout-polish --agent chatgpt

One committed source of truth

muxtra init creates .muxtra/project.yaml. Commit it so every person and agent receives the same install command, development command, healthcheck, checks, branch policy, and production rules.

version: 1
project:
  name: example-app
runtime:
  install: pnpm install
  development: pnpm dev
  healthcheck: /
  port_env: PORT
checks:
  - pnpm typecheck
  - pnpm test
  - pnpm build
lanes:
  design:
    agent: claude
  code:
    agent: codex
git:
  branch_prefix: agent
  direct_push_to_main: false
  force_push: false

The contract contains commands and policy—not credentials. Machine-local task state is stored in the repository’s shared Git directory; managed worktrees and logs live under ~/.muxtra/ by default.

Development servers per workspace

Start, inspect, and stop the configured development server without guessing ports or log locations:

muxtra dev dashboard-navigation
muxtra status
muxtra logs dashboard-navigation
muxtra stop dashboard-navigation

Muxtra allocates a port, records the process and log, and waits for the configured health URL. From inside a registered worktree, the workspace name is inferred.

Command reference

Muxtra is designed for agents to use, too

Launch instructions tell agents to inspect project context, claim paths before editing, use the managed development lifecycle, commit their work, and finish verification. Add the protocol to AGENTS.md only when you want it committed to the repository:

muxtra agent-guide
muxtra install-guide
# or during initialization
muxtra init --install-guide

Claims are advisory leases, not locks. They reveal overlapping intent without preventing legitimate collaboration, and they expire when an agent stops sending heartbeats.

When something is not ready