Build your agent team in pi with one command.

Features

Bundled Workflows

Tamandua ships with 23 bundled workflows organized into six 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.

Maintenance & Audits

Workflows for auditing and validating the project itself.

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).

Native AutoResearch

Tamandua includes native AutoResearch primitives for measurable optimization loops. Unlike a normal workflow, AutoResearch stores durable project-local state so an agent can resume after restarts, learn from each measured run, and choose the next experiment from evidence.

Use AutoResearch when the task has a reliable numeric metric and the agent should run a sequence of experiments instead of one batch of edits — raising test coverage, reducing validation loss, improving latency, or lowering cost while preserving correctness.

tamandua autoresearch init \
  --goal "reduce validation loss" \
  --metric val_bpb \
  --direction lower \
  --command "uv run train.py"

tamandua autoresearch run-experiment
tamandua autoresearch log-experiment --status auto \
  --description "try lower learning rate" \
  --hypothesis "smaller LR improves stability" \
  --learned "validation improved but training slowed" \
  --next-focus "test warmup schedule"
tamandua autoresearch next

The core loop is init → run-experiment → log-experiment → next. log --status auto classifies a run as baseline, keep, discard, crash, or checks_failed by comparing the latest metric with prior accepted results. The next prompt carries the ratchet: it restates the goal, best result, last learning, and next focus before the agent starts another experiment.

Project Files

The dashboard's AutoResearch panel reads the run's harness working directory, discovers the nearest autoresearch.config.json / autoresearch.jsonl, and renders the experiment trace — gray points are attempted experiments; green points and the green line are the kept best-so-far frontier. A SQLite session registry makes every AutoResearch project discoverable from the dashboard, and tamandua autoresearch prune cleans up stale registry entries without touching project files.

Commands & Harness Selection

Everyday Commands

Harness Selection

By default, Tamandua uses pi (pi --print) as its agent harness. Override it per run with mutually exclusive flags on tamandua workflow run:

To use a custom Hermes binary, set TAMANDUA_HERMES_BINARY; otherwise Tamandua searches for hermes on your PATH. Harness validation runs at scheduling time — a missing or non-executable binary fails the run immediately with a clear error.

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.

id: my-workflow
name: My Custom Workflow
agents:
  - id: researcher
    name: Researcher
    workspace:
      files:
        AGENTS.md: agents/researcher/AGENTS.md

steps:
  - id: research
    agent: researcher
    input: |
      Research {{task}} and report findings.
      Reply with STATUS: done and FINDINGS: ...
    expects: "STATUS: done"

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 14 tools at http://localhost:3338/mcp:

Run Management

tamandua.run.start parameters

workingDirectoryForHarness and worktreeOriginRepository are mutually exclusive: direct workflows require the former, worktree workflows require the latter.

Events & Metadata

AutoResearch

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.