makifbaysal/tasktrooper: local-first agent platform for software teams of one

Website: tasktrooper.ai · Docs: tasktrooper.ai/docs · Download: Releases

A local-first agent platform for software teams of one. A board of tasks, a set of role agents (product manager, architect, backend, frontend, QA), and a runtime that hands each task to an agent CLI on your own machine — Claude Code, Cursor, Antigravity or OpenCode — or to a model API you bring a key for: clone, plan, implement, test, open the PR, while you watch the run.

Everything runs on your Mac: the desktop app starts an embedded Postgres and the Go backend, serves the UI, and runs the agent sessions locally. No account, no cloud, no login.

You don't drive the agents, the board does. Put a task on the board and the agent that owns its column picks it up on its own, does the work and hands the task on to the next column, where the next agent takes over. Nobody has to press run.

A usage limit doesn't lose work. When an agent CLI runs out of its usage limit in the middle of a task, the agent stops and the task waits on Blocked instead of failing. Once the limit resets, TaskTrooper picks the task back up by itself; on a CLI that can resume a session, such as Claude Code, the agent carries on from where it stopped instead of starting over.

Features

Board

• A Kanban board with thirteen columns out of the box, from Backlog to Released, including analysis review, code review, QA, PM UAT and human UAT. The columns, and which agents pick up work in each, are configurable.
• Agents take tasks by themselves. A task that lands in a column is dispatched to that column's agent automatically and moves on when the agent is done.
• Tasks carry acceptance criteria. A task cannot move forward out of a review column until every criterion has a verdict.
• Tasks can block each other; a blocked task waits until its blocker is done.
• Every task gets its own branch and pull request. Code review reads the PR; once it is signed off, a dedicated release engineer merges it, ships it per the component's delivery profile, verifies production afterward, and finishes or rolls back the release — never on a green deploy alone.
• When an agent CLI hits its usage limit, the task is parked on Blocked until the limit resets, and other runs on the same CLI are held instead of hitting the same wall. Then the task continues by itself. Claude Code resumes the parked session (--resume), so the agent keeps what it already read and wrote.

Role agents

Seven role agents ship with a catalog-driven library of skills, rules and tool policies — the repo's catalog/ directory is the source of truth and the backend syncs it into the database at boot and on an interval. They run on the connected agent CLI (Claude Code, Cursor, Antigravity or OpenCode) or on a configured API provider, each taking that runtime's default model unless an agent is given its own.

Every agent is editable: provider and model, tool policy, effort, skills, rules, the columns it works, and its memory. You can chat with any agent directly, or about a specific task.

• Your own agents. Create an agent from a template or from scratch with its own prompt, skills, rules, tool policy, columns and memory, and save any agent as a template for the next one.
• One board, several CLIs. The runtime is chosen per agent, not per install. A developer on Claude Code, a reviewer on the Cursor CLI, a QA agent on OpenCode and an API-only agent on Gemini can all work the same board, each in its own session.

Self-evolution

Agents rewrite their own playbooks from how their work actually went.

• Reflection. On a schedule, whenever a task is sent back to Need Revision, or on demand, an agent reviews everything since its last reflection: its runs, chat messages, revision comments, scores, KPI results and its current skills, rules and memories. It proposes changes to all three. Skill and rule changes are applied only for agents with self-evolution turned on.
• Golden gate. With the gate enabled, a golden task suite runs before and after a proposed change, and an independent judge model decides whether to keep it. If the pass rate drops, the whole change set is reverted automatically.
• Impact tracking. Each applied change is later classified as effective, regressed or neutral by comparing scores before and after it. Regressions are put in front of the agent's next reflection, which decides whether to revert.
• Budgets and history. Skills and rules are capped per agent (25 and 15 by default), so an agent merges and updates instead of piling up. Every write to a skill or rule is versioned with its source (you, self-evolution or the upstream catalog) and any version can be restored.
• KPIs. Each agent has targets such as tasks completed, first-pass rate, revisions received, UAT failures, failed runs and time spent per column, measured per day, week or month. The targets are part of the agent's prompt, and the Performance page shows how it is doing.

Memory and code understanding

• Agents save and search memories in four scopes: personal or team-wide, for one repository or for every repository. Notes about a single run are refused, and a near-duplicate is not saved twice.
• Repositories are parsed with tree-sitter and embedded on your machine with the bundled nomic-embed-text-v1.5 model, so agents search code semantically and see uncommitted edits without a re-index.
• Skills are loaded on demand, so a long skill list does not fill the prompt.
• Files uploaded to a workspace are available to agents through retrieval.

Runtimes, models and tools

• Agent CLIs run as local, headless processes: Claude Code, Cursor, Antigravity and OpenCode. Every session gets TaskTrooper's board tools over MCP with a per-run token that is revoked when the run ends.
• API providers for agents that do not use a CLI: OpenAI, Anthropic, Google Gemini, Groq, or any OpenAI-compatible endpoint such as LM Studio, Ollama or vLLM.
• Connect your own MCP servers.
• Built-in tools: terminal, file editing, web search with no API key, page fetch, headless-browser QA, and a boilerplate catalog to start new projects from.
• A repository's own version pins (.tool-versions, go.mod, .nvmrc and others) are honoured in the agent session.

Integrations and operations

• GitHub: clone, branches, pull requests, review comments, merge, and CI status from GitHub Actions.
• Deploys: a recipe catalog for Google Cloud Run and GKE, AWS ECS and Lambda, Vercel and Fly, rendered into a workflow per environment with a health check, plus a deployment matrix. A Vercel account can be connected to bind existing projects.
• Production incidents: alerts from Alertmanager, Sentry, Cloud Monitoring or any JSON webhook, together with a health monitor, fold into deduplicated incidents with a suggested remedy: a rollback, a config, dependency or capacity fix, or a code defect. Per repository you choose whether an incident is only recorded, becomes a diagnosis task, or is fixed through the board.
• Mobile releases: connect App Store Connect and Google Play and promote builds through internal, external and production channels. QA can drive iOS simulators and Android emulators on this Mac through Appium.
• Usage: token usage per model and per day.

First run

A guided setup checks this Mac (git, the agent CLIs you have, and optionally Chrome, Xcode, Appium and the Android SDK), lets you connect any agent CLI you have (Claude Code, Cursor, Antigravity, OpenCode) or an API provider with your own key, then connects GitHub and imports your first project.

Install

curl -fsSL https://raw.githubusercontent.com/makifbaysal/tasktrooper/main/scripts/install.sh | bash

It downloads the latest release's universal .dmg, copies TaskTrooper into /Applications, and prints the commands for anything else you need. Pass -y to replace an existing install without being asked.

With Homebrew once this repository is public; the repository is its own tap:

brew tap makifbaysal/tasktrooper https://github.com/makifbaysal/tasktrooper
brew install --cask tasktrooper

The app is ad-hoc signed and not notarized yet, so a copy you install by hand may need right-click → Open the first time; the install script and the cask both clear the quarantine flag for you.

First launch downloads two things into the app's data directory: the Postgres binaries (30 MB) and the embedding model (140 MB). You need git and at least one way to run agents: an agent CLI (Claude Code, Cursor, Antigravity or OpenCode), or an API key for a model provider. The app checks what is installed and shows the exact command for anything missing.

Or grab the .dmg from Releases and drag TaskTrooper to Applications.

On Windows, download TaskTrooper-<version>-setup.exe from Releases and run it. On Linux, use TaskTrooper-<version>-x86_64.AppImage (chmod +x, then run it) or install the .deb. Neither is code-signed yet, so Windows SmartScreen asks you to confirm the first time. The install script and Homebrew are macOS-only.

Run from source

make setup      # go mod download + npm ci (desktop, desktop/ui)
make desktop    # Electron app in dev mode
make dev        # or: backend + UI dev server, open http://localhost:3200
make package    # build the installer for this OS into desktop/release

Layout

server/       Go backend — API, board, agent loop, tools, embedded Postgres
desktop/      Electron shell — supervises the backend + embedder, serves the UI
desktop/ui/   React UI — bundled into the app; runs in a browser for development
docs/         user docs (rendered at tasktrooper.ai/docs) — start with docs/README.md

Each directory has its own README.md and CLAUDE.md.

Architecture

One machine, three processes, one window. Nothing is hosted.

flowchart LR
  subgraph app["TaskTrooper.app (Electron)"]
    ui["React UI<br/>app://tasktrooper"]
    sup["Supervisor<br/>spawns + watches children"]
  end

  subgraph server["agent-server (Go, hexagonal)"]
    api["HTTP API<br/>127.0.0.1:&lt;port&gt; · one bearer token"]
    board["Board + dispatcher<br/>columns → owners, gates, sweepers"]
    runtime["Agent runtime<br/>headless CLI sessions, tool registry"]
    mcp["/mcp<br/>board tools served back to sessions"]
    ctx["Code understanding<br/>tree-sitter parse · local embeddings · dependency graph"]
  end

  pg[("Embedded Postgres 17<br/>tasks, runs, memories, vectors")]
  emb["Embedder<br/>nomic-embed-text-v1.5, local"]
  ws[("Workspaces<br/>one git checkout per task")]

  subgraph agents["Agent sessions (local processes)"]
    cc["claude -p"]
    cur["cursor agent"]
    oc["opencode run"]
    ag["antigravity"]
  end

  ext["Outside the machine, only when you connect it:<br/>model APIs · GitHub · Vercel · App Store / Play · your MCP servers"]

  ui -- fetch --> api
  sup -- PORT=0, LISTENING --> api
  sup --> emb
  api --> board --> runtime
  runtime --> cc & cur & oc & ag
  cc & cur & oc & ag -- per-run token --> mcp
  mcp --> board
  runtime --> ws
  ctx --> emb
  board & runtime & ctx --> pg
  runtime -.-> ext

• Local only. The desktop generates one bearer token, passes it to the server as SERVER_API_KEY and to the page; the listener binds 127.0.0.1.
• The desktop is the backend's supervisor. It spawns agent-server with PORT=0, reads the LISTENING line, polls /health, then opens the window.
• The server owns its database. Empty DATABASE_URL means it starts its own Postgres from the bundled binaries under the data directory.
• Agents are child processes, not a service. Each task run is one headless CLI session with a per-run MCP token, on whichever CLI that agent is set to.
• Code understanding stays on the machine. Repositories are parsed with tree-sitter and embedded with the bundled model; the vectors live in the same Postgres.

The long version: docs/architecture.md.

How a task runs

1. You put a card on the board (or a product-manager agent drafts it).
2. The backend prepares a git workspace under the data directory and starts a headless session on the agent's runtime (claude -p, cursor-agent -p, agy -p or opencode run, or an API model) with the agent's prompt, skills and a per-run MCP token that lets the session update acceptance criteria and move the card.
3. The session's output streams to the card. When it finishes, QA agents run the test round; CI status is polled from GitHub Actions.
4. The card moves through the columns you configured; a PR is opened on the task branch.

Configuration

The desktop app needs none. For make dev, scripts/dev.sh writes server/.env.local on first run; see server/README.md for every variable.

How it compares

Local-first peers

Open-source projects that also put coding agents to work on your own machine. The short version: they give you a tracker, a queue or a session manager that you drive; TaskTrooper is the whole loop in one desktop app, and the board drives it.

Hosted and single-agent tools

The agent products most people already use. Several of these are what TaskTrooper runs underneath rather than rivals: it runs on an agent CLI you already have (Claude Code, Cursor, Antigravity or OpenCode) or on a plain API key, and it reads the PRs and CI these tools produce.

Per-project write-ups, same content as tasktrooper.ai/compare:

• TaskTrooper vs Claude Code — A terminal agent, and one of the CLIs TaskTrooper runs underneath.
• TaskTrooper vs Cursor Cloud Agents — Parallel agents in cloud VMs that open merge-ready PRs.
• TaskTrooper vs Devin — A cloud AI engineer you assign tickets to from Slack, Linear or Jira.
• TaskTrooper vs GitHub Copilot coding agent — Assign an issue to Copilot and get a PR from a GitHub Actions runner.
• TaskTrooper vs OpenHands — A self-hosted control center for coding agents and automations.
• TaskTrooper vs Xirp — An agent grounded in your organisation's services, docs and architecture decisions.
• TaskTrooper vs Beads — A git-embedded, dependency-aware issue tracker and memory for coding agents.
• TaskTrooper vs Beadhive and Gas City — A CLI software factory on top of Beads, with role agents and human gates.
• TaskTrooper vs Vibe Kanban — A kanban board where each task gets a branch, a terminal and a dev server.
• TaskTrooper vs Claude Squad — A terminal UI that runs many agent sessions in tmux and git worktrees.