Build your agent team in pi with one command.

Features

Bundled Workflows

Tamandua ships with 21 bundled workflows organized into five families. Use tamandua workflow list to see available workflows, and tamandua workflow install <id> to install one.

Worktree variants (*-worktree, *-merge-worktree) run in a detached git worktree created from your origin repository. Your main working copy stays untouched until the workflow completes. This gives you full isolation — continue working while agents iterate — and a clean abort path: delete the worktree and nothing in your origin repo has changed.

Rugpull Handling

When a merge workflow (-merge, -merge-worktree) fails at the finalize_merge step and the base branch tip has moved since the run started, Tamandua automatically launches a fresh replacement run with the same parameters. This "rugpull" detection runs after the final merge failure — if the base branch stayed put, no replacement is triggered. Pass --no-relaunch-upon-rugpull to workflow run to suppress the automatic replacement.

Feature Development

Story-based feature development. The planner decomposes your task into ordered user stories. Each story goes through implement → verify → test before the next one starts.

Bug Fix

Bug triage and fix. The triager reproduces the bug, the investigator finds the root cause, the fixer patches it, and the verifier confirms the fix against acceptance criteria.

Security Audit

Vulnerability scanning and patching. Scans for vulnerabilities, ranks by severity, patches each one, re-audits after all fixes are applied, and runs regression tests.

Quarantine Broken Tests

Detect failing tests, disable them minimally, and iterate until the full test suite passes. Useful for establishing a clean baseline on a branch with known test failures.

Quick Tasks

Single-agent workflows for quick one-off tasks and workflow auto-selection.

Install all bundled workflows at once with:

$ tamandua workflow install --all

Installation

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

git clone https://github.com/igorhvr/tamandua.git
cd tamandua
./build-and-install

./build        # npm install + tsc
./install      # symlink into ~/.local/bin

Why It Works

1. Deterministic workflows

   Same workflow, same steps, same order. Not "hopefully the agent remembers to test."

2. Agents verify each other

   The developer doesn't mark their own homework. A separate verifier checks every story against acceptance criteria.

3. Fresh context, every step

   Each agent gets a clean session. No context window bloat. No hallucinated state from 50 messages ago.

4. Retry and escalate

   Failed steps retry automatically. If retries exhaust, it escalates to you. Nothing fails silently.

How It Works

Minimal by Design

YAML + SQLite + polling. That's it. No Redis, no Kafka, no container orchestrator. Tamandua is a TypeScript CLI with zero external dependencies. It runs wherever pi runs.

Quick Example

$ tamandua workflow install feature-dev

# Or install all bundled workflows at once
$ tamandua workflow install --all
✓ Installed workflow: feature-dev

$ tamandua workflow run feature-dev "Add user authentication with OAuth"
Run: a1fdf573
Workflow: feature-dev
Status: running

$ tamandua workflow status "OAuth"
Run: a1fdf573
Workflow: feature-dev
Steps:
  [done   ] plan (planner)
  [done   ] setup (setup)
  [running] implement (developer)  Stories: 3/7 done
  [pending] verify (verifier)
  [pending] test (tester)

Dashboard & Kanban

When you start the management dashboard (tamandua dashboard), Tamandua automatically starts the remote MCP server too.

• Dashboard: http://localhost:3334
• MCP endpoint: http://localhost:3338/mcp (fixed port)

Use tamandua dashboard status to verify both endpoints are up.

Each run also has a swim-lane Kanban view at http://localhost:3334/runs/<run-id>/kanban. Lanes are derived dynamically from the workflow's steps. Single steps render one card per lane; loop steps render one card per story. Cards are colour-coded by status (todo / running / done / failed).

Build Your Own

The bundled workflows are starting points. Define your own agents, steps, retry logic, and verification gates in plain YAML and Markdown. If you can write a prompt, you can build a workflow.

Full guide.

Skill included. The tamandua-agents skill is bundled and is excellent at allowing your agents to build-and-forget with tamandua. The CLI itself is also designed in a way that is easy for agents in general to grasp. Remote MCP tools are exposed so agents can query runs, start workflows, and check status autonomously.

Remote MCP Tools

The remote MCP endpoint exposes 9 tools at http://localhost:3338/mcp:

Run Management

Events & Metadata

Security

You're installing agent teams that run code on your machine. We take that seriously.

• Curated repo only — Tamandua only installs workflows from the official repository. No arbitrary remote sources.
• Reviewed for prompt injection — Every workflow is reviewed for prompt injection attacks and malicious agent files before merging.
• Community contributions welcome — Want to add a workflow? Submit a PR. All submissions go through careful security review before they ship.
• Transparent by default — Every workflow is plain YAML and Markdown. You can read exactly what each agent will do before you install it.