Why Natamux
Coding agents are good at one job at a time. Run five of them and you start to juggle:
- Terminal tabs, and no way to tell which agent works, which is stuck and which finished an hour ago.
- Two agents in one checkout, editing the same files.
- A question or a permission prompt that waits where nobody sees it.
- Work that nobody checked before it reaches a pull request.
- A team where each person runs agents their own way, with no shared process.
Natamux puts each task in its own worktree, so agents never share a checkout. It shows every agent's state on one dashboard and brings questions and permission prompts to you. It runs a review stage before the pull request, and it keeps the process in one file the team commits. You step in only where that workflow asks for you.
Features
- Agents that check each other. Work is checked twice before it reaches you. In the default workflow, one agent writes test cases from the spec without reading the code while another writes the code, and a third agent reviews the diff in a fresh session and sends the task back to Implement when it finds problems.
- A worktree, a branch and a terminal per task. Each task works in its own folder on a branch such as
natamux/t-0001-fix-login, so agents never edit the same checkout. Its shells keep running when you close the dashboard and come back with their screen.
- One place for what needs you. The title bar counts the tasks that wait for you: a question, a stage ready for review, a failure, or an agent quiet for 10 minutes. A question becomes a sidebar card with Answer. Turn on Notify me for system notifications.
- One workflow for the whole team. It lives in
.natamux.json, so you commit it like code. Pick stages from a catalog of 28, choose which ones wait for your approval, run 2 to 4 stages side by side, split the pipeline into paths with a condition, and check a stage on CI.
- An agent per stage. Give each stage its own agent and model: Claude Code to implement, Cursor to review, Copilot to watch CI, each in its own shell.
- Every task at a glance. Switch between Table, Board and Progress views, open Agents for a grid of up to six live terminals, or press Cmd+K (Ctrl+K outside a terminal) or F1 to find any task or command.
- Review and ship from the task. Read side-by-side or inline diffs, including image diffs. Send a line comment to the agent, let the agent draft the commit message, then commit, push and open a pull request. A merged pull request finishes the task.
- Fits the project you already have. A
.natamux-setup script (.natamux-setup.ps1 on Windows) prepares each new worktree. Each task gets ten ports, the first in $PORT, so dev servers do not clash.
How it works
Build the workflow in Project settings → Stages, or edit .natamux.json directly. Below, three tasks run the workflow of a sample project: a bug takes the Bug fix path, two agents work side by side, Codex reviews and sends one task back, and the last word is yours.
The animation shows a custom workflow. With no .natamux.json, a task runs the default stages: Context → Spec → Plan → [ Test spec ‖ Implement ] → Automated tests → Review → Release.
- You approve the spec and the plan that the task's agent writes.
- Test spec and Implement start together, each in its own shell. You approve the test spec.
- Automated tests adds a test for each case and runs all tests.
- The Review agent writes
review.md. With findings, it sends the task back to Implement, at most two times; then it asks you.
- Release waits for your pull request. The merge finishes the task.
A workflow branch takes the first path whose condition holds (File has text or Command succeeds), and a red CI run goes back to the agent with the end of the failed log. Start from a recipe, Solo or Team, in Build a workflow. See also the review loop and stages.
Works with your agents
Natamux starts the agent CLIs you already have and adds hooks, so the dashboard knows when an agent works, asks or finishes.
| Agent | Command | How Natamux follows it |
|---|
| Claude Code | claude | Hooks in a settings file passed with --settings for that run. The only agent that can run a stage as a workflow. |
| Codex | codex | Hooks passed on the command line for that run. |
| Gemini CLI | gemini | Hooks in a system settings file that Natamux points it to. |
| GitHub Copilot CLI | copilot | Hooks in the worktree, kept out of git. |
| Cursor | cursor-agent | Hooks in the worktree, kept out of git. |
| Any other terminal agent | yours | The terminal bell, plus natamux ask and natamux done. |
See Mix agents in one task and Agents and hooks.
Install
Download the file for your system from the latest release:
[!NOTE]
The apps are not signed with an Apple or Windows certificate yet, so the system asks once. macOS: System Settings → Privacy & Security → Open Anyway. Windows: SmartScreen More info → Run anyway. Linux: chmod +x the AppImage first. Check any file against the signed SHA256SUMS.txt of the release.
Desktop releases support macOS on Apple silicon and Intel, Windows 10 (1809 or later) and 11 on x64, and Linux on x64. The macOS app (installed in Applications), the AppImage and the .deb can update themselves; the Windows installer and the .tar.gz open the release page of the new version. The update check is off until you turn it on.
For real work, you need git and an installed, logged-in coding agent: Claude Code, Codex, Gemini CLI, GitHub Copilot CLI or Cursor. The GitHub CLI (gh) is optional, for pull requests, issues and CI. The install guide has every step.
Quick start
- Add a project. Choose File → Add Project… and pick a git repository.
- Start a task. Press
c, type a title and notes, pick the agent, and click Start task. Natamux makes a worktree and a branch and starts the agent in the task's terminal.
- Approve the spec, the plan and the test spec when the task asks. The rest runs by itself.
- Read the changes in the Changes tab, click Generate for a commit message, then Commit all, Push and Create PR.
The quick start walks through it with screenshots.
Try the demo in Codespaces
No install needed. Open this repository in GitHub Codespaces, then run:
scripts/e2e.sh build
E2E_LOCAL=1 scripts/e2e.sh up
Open forwarded port 8080 and sign in with the token e2e-token. The demo includes tasks, workspaces, commits and changes to inspect.
The demo starts fake agents through scripts/fake-agent.sh; the images do not include a real coding agent. Run scripts/e2e.sh down to stop it. See Docker setup for details.
Command line
natamux, short name nmx, works in every task terminal and from your own shell.
| Command | What it does |
|---|
nmx task create "Fix the login" --label bug | Add a task to the backlog |
nmx agent start T-0001 --agent codex | Start an agent in the task's own worktree |
nmx stage approve T-0001 | Approve the stage that waits |
nmx stage back T-0001 --reason "..." | Send the task back to an earlier stage |
natamux ask "Which API?" / natamux done | What agents run to ask you, or to finish a stage |
See the CLI reference and Rust CLI.
Security and privacy
- No account or telemetry. Natamux has no server of its own. Tasks and their history stay in the
.natamux/ folder of each repository.
- Local daemon. It listens on 127.0.0.1 and wants a token on every request. In Docker it listens inside the container, and the production compose file publishes the port to loopback only.
- Your services, your sign-in. Coding agents send your prompts and code to their own providers. Pull requests, issues and CI use your own
git and gh login.
- Checked updates. The update check is off by default. Before it installs an update, the app checks the minisign signature of the release's
SHA256SUMS.txt and the SHA-256 of the download.
[!IMPORTANT]
Natamux does not sandbox agents: an agent has your user's rights. By default Natamux starts each agent with its flag for fewer prompts: Claude Code in auto mode, which checks each action, and the other agents with prompts off (Codex stays in its workspace-write sandbox). Set "agents": { "permissionMode": "ask" } in .natamux.json to turn the flags off.
Read Privacy for what stays on your machine and what leaves it, and Security for protection details and private vulnerability reporting.
Repository guide
The documentation site covers tasks, stages, agents, the dashboard, the desktop app and every setting. To run the daemon and dashboard on a server, see Docker setup.
Contributing
Natamux is young and moves fast. Issues and pull requests are welcome.
- Set up with the contributor setup. Development runs in a GitHub codespace.
- Rust CI checks formatting, Clippy, tests, layers, startup, and the required E2E groups. Web and core CI checks Biome, types, and tests. Release CI packages and checks the native app on macOS, Windows, and Linux.
- Report a vulnerability privately, as Security describes. Do not open a public issue for it.
License
Natamux is free software under the GNU General Public License, version 3 or later (GPL-3.0-or-later).
Copyright (c) 2026 lenhatthanh20 and the Natamux contributors.
Releases before the move to Rust were published under the MIT License.
