Warning
Maestro is under active development. Features may be heavily modified or removed without notice, and the UI changes frequently between releases.
Drop tasks onto a Kanban board and give each one its own coding agent and terminal. With Git enabled, tasks can also run in isolated worktrees so agents work in parallel without clobbering each other's changes. When an agent finishes, review the diff hunk by hunk and commit what you want — all without leaving the app.
Maestro keeps the full agent workflow in one place:
- Plan — turn work into focused tasks on the Kanban board
- Run in parallel — give every task an agent and an isolated git worktree
- Stay informed — follow terminal output, agent activity, and changed files live
- Review precisely — inspect and stage changes at hunk level
- Ship deliberately — commit only the changes you approve
| Platform | Download |
|---|---|
| macOS — Apple Silicon (M1/M2/M3/M4) | Maestro_macos_aarch64.dmg |
| Linux — x86_64 | Maestro_linux_x86_64.AppImage ✓ recommended |
| Linux — x86_64 (no auto-update) | Maestro_linux_x86_64.deb |
| Linux — arm64 | Maestro_linux_aarch64.AppImage |
| Windows — x86_64 | Maestro_windows_x86_64-setup.exe ✓ recommended |
| Windows — x86_64 (MSI) | Maestro_windows_x86_64.msi |
The .dmg, .AppImage, and .exe installers include automatic in-app updates. The .deb package does not — Maestro will prompt you to download the new version when one is available.
No Maestro account is required. Install the app and use it directly — there is no Maestro service to register for or sign in to.
Maestro orchestrates coding agents but does not provide an agent account or model access. Install and authenticate the agent of your choice before using it with Maestro. Supported agents include Claude Code, Codex, OpenCode, Gemini CLI, Goose, Cline, and other Agent Client Protocol (ACP) agents.
Some agents are launched through npx or uvx rather than a standalone executable. Depending on your chosen agent, you may also need:
Agent authentication, subscriptions, model availability, and usage charges are managed by the agent's provider, not by Maestro.
Maestro's picker lists agents from a registry bundled in the app. To add one it does not ship — a local model served through Ollama or another Anthropic-compatible gateway, an in-house ACP adapter, or a second profile of a listed agent pointed at a different endpoint — put your own entries in ~/.maestro/custom-agents.json (%USERPROFILE%\.maestro\custom-agents.json on Windows).
With an agent. Run /maestro-custom-agents in any agent session — inside Maestro or in a terminal. Maestro installs that skill on every machine it connects to, so the agent knows the format: it asks what you want to add and writes the file for you. It is a slash command, so it never fires on its own.
By hand. One entry per agent, each with an id, a name and exactly one launch method:
{
"agents": [
{
"id": "ollama-claude-acp",
"name": "Claude Code (Ollama)",
"distribution": {
"npx": {
"package": "@agentclientprotocol/claude-agent-acp@0.64.0",
"env": {
"ANTHROPIC_BASE_URL": "http://localhost:11434",
"ANTHROPIC_AUTH_TOKEN": "ollama",
"CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY": "1"
}
}
}
}
]
}That example is worth reading even if your agent is a different one: it adds nothing new to your machine. It is the same Claude Code ACP package Maestro already ships, launched with a different environment — Ollama's endpoint instead of Anthropic's, and gateway model discovery on so Maestro's model selector lists the models you have pulled locally. Your normal Claude Code entry keeps working alongside it.
The other launch methods are "uvx": { "package": "..." } and "binary": { "<platform>": { "cmd": "..." } }, where <platform> is one of darwin-aarch64, darwin-x86_64, linux-aarch64, linux-x86_64, windows-x86_64, windows-aarch64 and cmd is a name on your PATH or an absolute path. All three accept optional args. Only npx accepts env — under uvx and binary it is ignored, so an agent that needs environment variables either goes through npx or reads them from a wrapper script named as cmd.
A few things to know:
- The file belongs to the machine that runs the agent. For a project on an SSH host, in WSL, or in a container, write it in that machine's home directory, not on your laptop.
- Custom agents are additive. An
idthat collides with a bundled agent is ignored rather than replacing it. - Maestro trusts that a custom agent is installed, so a wrong package or command shows up as a failure when you start a session with it, not as a missing entry in the picker.
- A new entry reaches the picker within about five minutes, or immediately if you restart Maestro.
- The file is plain text in your home directory. Treat any API key you put in
envaccordingly.
Maestro can run agents in a regular folder without Git. For the complete workflow, use a Git repository: Git enables isolated worktrees, parallel agents without overlapping changes, inline diff review, hunk-level staging, and commits from Maestro.
Without Git, agents work directly in the selected folder and completed tasks move directly to Done instead of Review.
Maestro does not store remote connection or tool integration credentials in its SQLite database. When you choose to save them, SSH passwords, SSH key passphrases, and integration credentials are stored in your operating system's keychain. Coding-agent credentials remain managed by the agent itself.
If the OS keychain is unavailable, Maestro can store integration credentials in an encrypted local file and displays a warning. SSH secrets are not persisted through this fallback.
- Install and authenticate your preferred coding agent
- Open Maestro and select a local folder or Git repository
- Create a task on the Kanban board — add a title and instructions
- Pick an agent and model, then click Run
- Watch the live terminal and activity feed as it works
- In a Git repository, review the diff, stage what you want, and commit in one click
In a Git repository, each task can run in its own worktree. Agents work independently — no branch conflicts and no clobbering each other's changes. Run multiple agents concurrently, limited by your machine, remote host, and provider limits.
Live terminal output, a structured activity feed, and a file tree — all updating in real time. You see exactly what every agent is doing at every step.
When an agent finishes in a Git repository, you get an inline diff viewer with hunk-level staging. Accept what you want, revert what you don't, commit in one click.
Connect Maestro to a remote Linux server over SSH, or to a WSL distro on Windows. Agents execute on the remote machine while you work locally. Password, key, and passphrase auth all supported.
Sync tasks directly from GitHub Issues or Jira. Import a ticket, add instructions, hand it to an agent.
Use your preferred ACP-compatible coding agent and pick the model per task. Configure MCP allowlists while agent authentication and billing stay with the provider. Maestro stays out of the way. Agents it does not ship — a local model behind Ollama, an in-house adapter — go in custom-agents.json.
See CONTRIBUTING.md for setup, branch conventions, and PR guidelines.
For README screenshots and the short product demo, follow the presentation asset guide.
| Layer | Technology |
|---|---|
| Frontend | React 19, TypeScript, Vite, Tailwind CSS 4, shadcn/ui |
| State | Zustand + Immer, TanStack Query |
| Terminal | xterm.js |
| Desktop | Tauri 2 (Rust) |
| Database | SQLite (rusqlite) |
| SSH | russh |
| Protocol | ACP (Agent Client Protocol) via maestro-server sidecar |
| Type gen | ts-rs + tauri-specta |
# Frontend
bun dev # Vite dev server only (localhost:5173)
bun build # TypeScript check + production build
bun lint # oxlint
bun lint:fix # Auto-fix lint issues
bun format # Check formatting (oxfmt)
bun format:fix # Fix formatting
# Testing
bun test # Vitest unit tests
bun test <pattern> # Single test file
# Rust backend
cd src-tauri && cargo build
cd src-tauri && cargo test
cd src-tauri && cargo check
# Tauri
bun tauri:dev # Full dev mode (Tauri + Vite)
bun tauri:gen # Regenerate TypeScript bindings from Rust models
bun tauri build # Production bundle
# Cross-compile for Windows from Linux
bun tauri build --debug --runner cargo-xwin --target x86_64-pc-windows-msvcThree Rust crates in a Cargo workspace:
src-tauri— Tauri backend: IPC command handlers, SQLite DB, SSH tunneling, PTY management, ACP session coordination.maestro-server— Agent runtime sidecar, automatically deployed at runtime.maestro-protocol— Shared ACP protocol types.
See AGENTS.md for a full architecture walkthrough.
Apache-2.0