Natamux
Download
New in 0.1.38: see which path each task took

Write your workflow once.Every task runs it, with the agents you pick.

Stages, approvals, branches and send backs live in one committed file, .natamux.json. Each task gets its own worktree and terminals, and each stage can use a different agent: Claude Code, Codex, Gemini CLI, Copilot or Cursor. You step in only where the workflow asks for you.

Download for macOSBuild a workflow

Version 0.1.38 for Apple silicon. Other systems. MIT licensed, no account.

Three tasks run the workflow of storefront

.natamux.jsonshortened

{  "stages": [    { "id": "context", "kind": "context" },    { "id": "spec", "gate": "manual" },    { "id": "triage", "name": "Bug or feature",      "paths": [        { "id": "bugfix", "name": "Bug fix",          "when": { "type": "command",            "run": "grep -qi bug .natamux-task/context.md" },          "stages": [            { "id": "reproduce", "agent": "cursor" }          ] },        { "id": "feature", "name": "Feature",          "stages": [            { "id": "plan", "gate": "manual" }          ] }      ] },    { "id": "build", "parallel": [      { "id": "test-spec", "agent": "gemini" },      { "id": "implement" }    ] },    { "id": "agent-review", "name": "Review",      "agent": "codex" },    { "id": "security", "agent": "copilot" },    { "id": "review", "name": "Manual review",      "gate": "manual" },    { "id": "release", "gate": "manual" }  ]}
  • An agent works
  • Waits for you
  • Passed, or the path taken
  • Sent back

An animated graph of the storefront workflow. Its stages: Context; Spec, which waits for your approval; an If node, Bug or feature, with two paths: Bug fix, where Cursor reproduces the bug, and the Otherwise path, Feature, where Plan waits for your approval; then Test spec with Gemini CLI and Implement with Claude Code, side by side; Review with Codex, which can send the task back to Implement at most twice; Security review with Copilot; Manual review by you; and Release. Three tasks run it. T-0011 takes the Bug fix path, because grep -qi bug context.md exited 0. Review sends it back once: a coupon larger than the total makes it negative. Implement runs a second time, the review passes, and T-0011 waits at Manual review until you click Approve. T-0012 takes the Feature path and waits for you at Plan. T-0014 runs Test spec and Implement at the same time. Next to the graph is the shortened .natamux.json file of this workflow.

Works with

  • Claude Code
  • Codex
  • Gemini CLI
  • Copilot CLI
  • Cursor CLI
  • any terminal agent

One task, from bug report to your approval

A bug task in the storefront project, start to finish: the branch picks Bug fix, Gemini CLI and Claude Code work side by side, Codex sends the task back once, and you approve it.

Recorded on the real Natamux dashboard. The agents in it are stand-in scripts, so their terminal text is short.

Six building blocks for any process

Each block is a few lines in .natamux.json, or a few clicks in Project settings → Stages. Put them in any order your team works in.

A task whose Spec waits. The banner Ready for review: Spec has Approve and Send back, and the Spec card in the right panel has Approve.A task whose Spec waits. The banner Ready for review: Spec has Approve and Send back, and the Spec card in the right panel has Approve.
Ready for review: Spec in the workspace, and Approve on the stage card.

Stages and gates

A stage is one step of the work, such as Spec, Implement or Review. Natamux starts it, checks the result and goes on. A stage with Wait for my approval stops until you click Approve, so nothing gets built from a spec you did not read.

More in the docs: Gates

SpecApproveImplement

.natamux.json

{ "id": "spec", "gate": "manual" }
The Terminal tab of a task. Claude Code works on Implement in Shell 1 and Gemini CLI writes the test spec in its own shell. The right panel shows the side by side group.The Terminal tab of a task. Claude Code works on Implement in Shell 1 and Gemini CLI writes the test spec in its own shell. The right panel shows the side by side group.
Claude Code and Gemini CLI on one task, each in its own shell.

Side by side

A group holds 2 to 4 stages that work at the same time, each in its own shell. Here Test spec writes the cases from the spec alone while Implement builds. The group is done when every stage in it is done.

More in the docs: Stages that run side by side

Side by sidePlanTest specImplementReview

.natamux.json

{ "id": "build", "parallel": [
  { "id": "test-spec", "agent": "gemini" },
  { "id": "implement" }
] }
A branch in Project settings → Stages, with its condition and both paths. Real dashboard, stand-in agents.

Branches

A branch splits the pipeline into 2 to 4 paths. When a task gets there, Natamux checks the conditions in order, and the task takes the first path that holds. A condition is File has text or Command succeeds (the command exits with 0). The last path can be the Otherwise path. The Progress tab then says Took Bug fix and folds the other paths into Not taken.

More in the docs: Paths with a condition

IfBug fixTakenFeatureNot taken

.natamux.json

{ "id": "triage", "name": "Bug or feature",
  "paths": [
    { "id": "bugfix", "name": "Bug fix",
      "when": { "type": "command",
        "run": "grep -qi bug .natamux-task/context.md" },
      "stages": [{ "id": "reproduce" }] },
    { "id": "feature", "name": "Feature",
      "stages": [{ "id": "plan" }] }
  ] }
Review fails, the task is Sent back, and Implement runs again. Real dashboard, stand-in agents.

Send back

A review agent that finds a problem runs natamux stage back with the reason. The task goes back to Implement, and its agent gets the reason in its next prompt. An agent can send back at most 2 times from one stage; the third time, the task waits for you. A person can send back from any stage, any time.

More in the docs: The review loop

Implement×2ReviewSent back with the reason

The review agent runs

natamux stage back $NATAMUX_TASK_ID --to implement \
  --reason "A coupon larger than the total makes it negative"
Implementnatamux-ci/<branch>A red run sends the failed log

CI as a stage

Tick Tasks can check it on CI on a stage, and each task gets a Check on CI box. When the stage is done, Natamux pushes a snapshot of the worktree to natamux-ci/<branch> and waits for your CI. A red run goes back to the agent with the end of the failed log. After two such send backs, the next failure waits for you.

More in the docs: Check a stage on CI

.natamux.json

{ "id": "implement", "ci": true }
Project settings of storefront, Stages tab. The chart shows the If node. The Review stage is selected, with Agent set to Codex and the Arguments field.Project settings of storefront, Stages tab. The chart shows the If node. The Review stage is selected, with Agent set to Codex and the Arguments field.
The Review stage set to Codex in Project settings → Stages.

An agent per stage

A stage can start its own agent, with its own arguments such as a model. It runs in a shell of its own, so a reviewer reads the diff with fresh eyes. Set Agent and Arguments in the stage settings. They are saved in .natamux.json, so the whole team uses them.

More in the docs: Mix agents in one task

ReproduceCursorImplementClaude CodeTest specGemini CLIReviewCodex

.natamux.json

{ "id": "agent-review", "name": "Review",
  "agent": "codex", "args": "--model gpt-5" }

Start from a recipe

Two workflows from the guide, each a full file you can copy. They use your own stages, such as Watch CI and merge, next to the ones Natamux has.

Solo

One developer, one repo. You approve the spec. The rest runs without you.

  1. Context
  2. SpecYou approve
  3. At the same time:
    • Test specCopilot
    • ImplementClaude Code
  4. ReviewCursorSends back to Implement
  5. Watch CI and mergeCopilotSends back on red CI

See the file

Team

One committed file. Each task takes the path that fits where it is.

  1. Context
  2. Triage

  3. If Where is the task

    • When: Review a teammate's PR

      1. Review PRClaude Code
      2. Follow PR CI
      3. Wait for fix
      4. QA build

    • Otherwise: Develop

      1. SpecYou approve
      2. Plan
      3. Implement
      4. ReviewClaude CodeSends back to Implement
      5. Open PR
      6. Follow CICursorSends back on red CI
      7. Definition of doneCopilot
  4. Final checkYou check

See the file

Bring the agents you already use

Natamux starts five agents for you and adds hooks to each session, so the dashboard knows within a second who works, who asks and who is done. Each worktree is trusted for the agent it starts.

Five providers at once in the Agents view. Real dashboard, stand-in agents.
  • Claude CodeclaudeHooks through its settings file. The only agent that runs a stage as a workflow.
  • CodexcodexHooks passed on the command line for that run.
  • Gemini CLIgeminiHooks in a system settings file Natamux points it to.
  • GitHub CopilotcopilotHooks in the worktree, kept out of git.
  • Cursorcursor-agentHooks in the worktree, kept out of git.
  • Any other CLIyour-agentRuns in a plain shell. The terminal bell and natamux ask or done report back.

One task, one agent per stage

  1. Shell 1Claude CodeImplementBuilds. Keeps the task's session.
  2. Shell 6CopilotTest specWrites the test cases from the spec alone.
  3. Shell 7CursorReviewReads the diff with fresh eyes. Sends findings back.
  4. Shell 8CopilotWatch CIFollows the checks. A red run goes back to the agent.

Pick the agent and model per stage in Project settings → Stages. It is saved in .natamux.json, so the team shares it.

Mix agents in one taskAgents and hooks

Fits the project you already have

  • A worktree and a branch for each task, so agents never touch each other's files or your checkout
  • .natamux-setup prepares each new worktree: install, seed, copy env
  • Ten ports for each task, the first in $PORT, so dev servers do not clash
  • Checks and conditions are any shell command, so any language and build tool works
  • macOS, Windows and Linux. On Windows the script is .natamux-setup.ps1
  • Export a workflow from one project and Import... it into another. Import lists every command first

More in the docs: Workspaces

.natamux-setup

#!/bin/sh
pnpm install
cp ~/storefront.env .env
pnpm db:seed

See every task, and the one that needs you

The sidebar sizes each task by how much it needs you. A running task shows its stage, and finished work folds to one line. Open a task and its stages stay in sight beside the terminal.

Needs you. When an agent asks something, its card in the sidebar shows the question and Answer. The title bar counts the tasks that need you, and a system notice comes when the window is in the back. Real dashboard, stand-in agents.
The Progress tab of a bug task. The branch header says Took Bug fix with its reason, the Feature path is folded as Not taken, and Implement ran twice after 1 send back.The Progress tab of a bug task. The branch header says Took Bug fix with its reason, the Feature path is folded as Not taken, and Implement ran twice after 1 send back.
Progress. The right panel beside the terminal: one card per stage, the path a branch took and why, the other paths folded into Not taken, and Approve where a stage waits.
The Progress layout across storefront tasks in different stages, with a column for the branch.The Progress layout across storefront tasks in different stages, with a column for the branch.
Progress view. Layout: Progress puts each task in a row and each stage in a column, with the path each task took. You see at once where every task is.
The All tasks table of storefront. A task that needs input sorts first, and the title bar says how many need you.The All tasks table of storefront. A task that needs input sorts first, and the title bar says how many need you.
Table. Every task with its state, agent, branch and changes. Tasks that need you sort first, and / filters by id, title, agent, branch or label.
The command palette open over a workspace, with tasks that need you first and suggested commands.The command palette open over a workspace, with tasks that need you first and suggested commands.
Command palette. Cmd+K or Ctrl+K finds any task or command. Tasks that need you come first, and Cmd+J jumps to a workspace.

Git and GitHub without leaving the task

Every task works in its own worktree on its own branch.

  • Generate asks the task's agent for a commit message from the diff. Then Commit all.
  • Side-by-side diffs, image diffs, and a comment on any line that goes straight to the agent
  • Push, then Create PR with the GitHub CLI. The body ends with Closes #N
  • Natamux watches the PR checks; a merged PR finishes the task
  • Import issues turns open GitHub issues into tasks

More in the docs: GitHub

One command for you and your agents

natamux, or nmx for short. Agents use the same command to ask you something, say a stage is done, or send the work back.

More in the docs: CLI reference

The Changes tab: a side by side diff of the task's changes and a commit message written by Generate.The Changes tab: a side by side diff of the task's changes and a commit message written by Generate.
The Changes tab: a side by side diff, and a comment box that sends a note to the agent.
The History tab: the commit graph of the task branch next to its base branch.The History tab: the commit graph of the task branch next to its base branch.
The History tab, with the commit graph of the task branch.

Your code stays on your machine

  • No account, no telemetry. Besides the update check, it talks to GitHub only through your own git and gh, for example to follow your pull requests and CI.
  • Local daemon. It listens on 127.0.0.1 and wants a token on every request.
  • Open source. MIT licensed. Your agents and the GitHub CLI use their own sign-in.

Download Natamux 0.1.38

You need git and at least one agent, installed and signed in. The GitHub CLI adds pull requests and issues.

Download for Apple siliconDownload for Intel
  1. Open the .dmg and drag Natamux to Applications.

macOS blocks the first start

The app is not signed with an Apple certificate yet. Open System Settings → Privacy & Security and click Open Anyway. Or run:

xattr -dr com.apple.quarantine /Applications/Natamux.app
Download for Windows
  1. Run Natamux-win-x64.exe. It needs no administrator rights.
  2. Task terminals run PowerShell. For a new version, run the new installer; it keeps your data.

SmartScreen stops the first start

The installer is not signed with a Windows certificate yet. If you see Windows protected your PC, click More info, then Run anyway.

Download AppImageDownload .deb
  1. AppImage: make it executable, then start it. On Ubuntu 24.04 and later, add --no-sandbox if it does not start, or use the .deb.
  2. Debian and Ubuntu: install the .deb with apt. The app is natamux-desktop.
sudo apt install ./Natamux-linux-amd64.deb
Every file of version 0.1.38
SystemFile
macOS, Apple silicon (M1 and later)Natamux-mac-arm64.dmg
macOS, IntelNatamux-mac-x64.dmg
Windows 10 and 11, x64Natamux-win-x64.exe
Linux, any distributionNatamux-linux-x86_64.AppImage
Debian and UbuntuNatamux-linux-amd64.deb
Linux, no installNatamux-linux-x64.tar.gz
Checksums of every fileSHA256SUMS.txt