# tutti

Adopt this skill: https://proskills.md/skills/other/nutthouse-tutti-clawhub-tutti

Page: https://proskills.md/skills/other/nutthouse-tutti-clawhub-tutti
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: clawhub/tutti/SKILL.md
size: 7560
sha: 89d2b2dab81dcfc50b96178aeca8f5d696fbfca0
upstream: https://github.com/nutthouse/tutti/blob/main/clawhub/tutti/SKILL.md

````text
---
name: tutti
description: Orchestrate multiple AI coding agents (Claude Code, Codex, Aider) from a single config — launch teams, run workflows, track capacity, and manage handoffs.
version: 1.1.0
metadata:
  openclaw:
    requires:
      bins:
        - tt
        - tmux
        - python3
    emoji: "\U0001F3B6"
    homepage: https://github.com/nutthouse/tutti
---

# Tutti — Multi-Agent Orchestration

Orchestrate a team of AI coding agents from a declarative `tutti.toml` config. Launch agents in isolated git worktrees, run verification workflows, track token usage, and manage context handoffs — all through a single CLI.

## When to use this skill

Use when the user asks you to:
- Launch, monitor, or stop a team of AI coding agents
- Run or verify automated workflows across agents
- Dispatch prompts to agents with auto-start and output capture
- Land agent work back to the main branch or open PRs
- Check agent status, health, or capacity usage
- Generate or apply context handoff packets
- Coordinate multi-agent development workflows

## Prerequisites

1. `tt` binary installed and on PATH (install from https://github.com/nutthouse/tutti)
2. `tmux` installed
3. `python3` available
4. A `tutti.toml` config file in the workspace root

Always run preflight checks before starting a workflow:
```bash
python3 tutti_openclaw.py doctor_check
```

## Actions

All actions go through the wrapper script. Every action returns a consistent JSON envelope:

```json
{
  "ok": true,
  "action": "action_name",
  "command": ["tt", "..."],
  "exit_code": 0,
  "data": {},
  "stdout": "",
  "stderr": ""
}
```

### Lifecycle

| Action | Command | Purpose |
|--------|---------|---------|
| `doctor_check` | `python3 tutti_openclaw.py doctor_check` | Preflight: verify tools, config, and environment |
| `launch_team` | `python3 tutti_openclaw.py launch_team` | Launch all agents defined in tutti.toml |
| `launch_agent` | `python3 tutti_openclaw.py launch_agent <name>` | Launch a single agent |
| `send_prompt` | `python3 tutti_openclaw.py send_prompt <agent> <prompt...> [--auto-up] [--wait] [--output]` | Send a prompt to an agent with optional auto-start, wait-for-idle, and output capture |
| `team_status` | `python3 tutti_openclaw.py team_status` | Read agent states from .tutti/state/ |
| `agent_output` | `python3 tutti_openclaw.py agent_output <name> --lines 50` | Peek at an agent's terminal output |
| `stop_agent` | `python3 tutti_openclaw.py stop_agent <name>` | Stop a single agent |
| `stop_team` | `python3 tutti_openclaw.py stop_team` | Stop all agents |

### Workflows

| Action | Command | Purpose |
|--------|---------|---------|
| `list_workflows` | `python3 tutti_openclaw.py list_workflows` | Discover available workflows |
| `plan_workflow` | `python3 tutti_openclaw.py plan_workflow <name> [--strict]` | Dry-run a workflow |
| `run_workflow` | `python3 tutti_openclaw.py run_workflow <name> [--agent <a>] [--strict]` | Execute a workflow |
| `verify_team` | `python3 tutti_openclaw.py verify_team [--workflow <w>] [--strict]` | Run verification workflow |
| `read_verify_status` | `python3 tutti_openclaw.py read_verify_status` | Read last verification result |

### Git Operations

| Action | Command | Purpose |
|--------|---------|---------|
| `land_agent` | `python3 tutti_openclaw.py land_agent <agent> [--pr] [--force]` | Land an agent's branch back to current branch, or open a PR |

### Handoffs

| Action | Command | Purpose |
|--------|---------|---------|
| `generate_handoff` | `python3 tutti_openclaw.py generate_handoff <agent> [--reason <r>]` | Capture agent context to a packet |
| `apply_handoff` | `python3 tutti_openclaw.py apply_handoff <agent> [--packet <path>]` | Inject a handoff packet into an agent |
| `list_handoffs` | `python3 tutti_openclaw.py list_handoffs [--agent <a>] [--limit 20]` | List available handoff packets |

### Permissions

| Action | Command | Purpose |
|--------|---------|---------|
| `permissions_check` | `python3 tutti_openclaw.py permissions_check <cmd...>` | Check if a command is allowed by policy |

## Workflow step types

Workflows in `tutti.toml` support these step types:

| Type | Purpose | Key fields |
|------|---------|------------|
| `prompt` | Send text to an agent session | `agent`, `text`, `inject_files`, `wait_for_idle`, `wait_timeout_secs` |
| `command` | Execute a shell command | `run`, `cwd`, `timeout_secs`, `fail_mode` |
| `ensure_running` | Start an agent if not already running | `agent`, `fail_mode` |
| `workflow` | Execute another workflow as a nested step | `workflow`, `agent`, `strict`, `fail_mode` |
| `land` | Land an agent's branch | `agent`, `pr`, `force`, `fail_mode` |
| `review` | Send an agent's diff to a reviewer | `agent`, `reviewer`, `fail_mode` |

Prompt steps support `inject_files` — an array of workspace-relative file paths that are copied into the agent's worktree before the prompt is sent. This enables stateful context passing between agents (e.g., injecting a snapshot JSON produced by another agent).

Nested `workflow` steps enable composition: observe → dispatch → fix → verify → land as a chain of workflow invocations.

## Execution pattern

Follow this sequence for orchestrating a workspace:

1. **Preflight** — `doctor_check`. Stop and report if non-zero.
2. **Launch** — `launch_team` or `launch_agent <name>`.
3. **Monitor** — `team_status` and `agent_output <name>` to observe progress.
4. **Dispatch** — `send_prompt <agent> "do something" --auto-up --wait --output` to dispatch work and capture results.
5. **Workflow** — `list_workflows` to discover, then `run_workflow <name>`.
6. **Verify** — `verify_team --strict` for gate-style quality checks.
7. **Land** — `land_agent <agent>` to cherry-pick work, or `land_agent <agent> --pr` to open a PR.
8. **Handoff** — `generate_handoff <agent>` when context is high, `apply_handoff <agent>` to resume.
9. **Stop** — `stop_team` or `stop_agent <name>` when done.

## Failure handling

- **Non-zero exit**: Surface the `action`, `command`, and `stderr` from the JSON envelope. Do not retry blindly.
- **Verify warnings (non-strict)**: Report as warning. Include data from `read_verify_status`.
- **Missing state files**: Treat as transient — retry up to 3 times with short delays. If still missing, the workspace may not have been launched.
- **Auth failures**: If `stderr` contains auth errors, stop and escalate to the user. Do not retry auth failures.
- **Agent not running**: Use `--auto-up` on `send_prompt` to automatically start agents on demand rather than failing.

## Configuration override

If `tt` is not on PATH or you need a specific version:

```bash
python3 tutti_openclaw.py --tt-bin /path/to/tt doctor_check
# or via environment variable
TUTTI_BIN=/path/to/tt python3 tutti_openclaw.py doctor_check
```

## Rules

- Always run `doctor_check` before any launch or workflow operation.
- Never retry auth failures — escalate to the user immediately.
- Prefer `team_status` (reads state files directly) over `agent_output` for status checks.
- Use `--strict` flag on `verify_team` and `run_workflow` when results gate further actions.
- Use `--auto-up` on `send_prompt` when the target agent may not be running.
- Use `--output` on `send_prompt` to capture the agent's response for programmatic verification.
- Use `--json` output from `tt` commands when you need structured data (the wrapper handles this automatically).
- Do not parse `stdout` text output — always use the `data` field from the JSON envelope.
````

## File: clawhub/tutti/action-contract.json
size: 3214
sha: 01c021d79e10dc21fb4ad7b2e50fd77a94c824d4
upstream: https://github.com/nutthouse/tutti/blob/main/clawhub/tutti/action-contract.json

```text
{
  "name": "tutti-openclaw",
  "version": "1.1.0",
  "description": "Action contract for using Tutti from OpenClaw via tutti_openclaw.py",
  "entrypoint": "tutti_openclaw.py",
  "global_args": {
    "--tt-bin": "Override the Tutti CLI command/prefix (defaults to `tt`, or TUTTI_BIN env var)"
  },
  "output_envelope": {
    "ok": "boolean",
    "action": "string",
    "command": "array<string>|null",
    "exit_code": "number",
    "data": "any",
    "stdout": "string",
    "stderr": "string",
    "parse_error": "string|null",
    "note": "string|null"
  },
  "actions": [
    {
      "name": "doctor_check",
      "args": [],
      "description": "Run tt doctor --json"
    },
    {
      "name": "permissions_check",
      "args": ["<command...>"],
      "description": "Run tt permissions check <command...> --json"
    },
    {
      "name": "launch_team",
      "args": [],
      "description": "Run tt up"
    },
    {
      "name": "launch_agent",
      "args": ["<agent>"],
      "description": "Run tt up <agent>"
    },
    {
      "name": "send_prompt",
      "args": ["<agent>", "[--auto-up]", "[--wait]", "[--output]", "[--timeout-secs <n>]", "[--idle-stable-secs <n>]", "[--output-lines <n>]", "<prompt...>"],
      "description": "Send a prompt to an agent with optional auto-start, wait-for-idle, and output capture"
    },
    {
      "name": "list_workflows",
      "args": [],
      "description": "Run tt run --list --json"
    },
    {
      "name": "plan_workflow",
      "args": ["<workflow>", "[--agent <agent>]", "[--strict]"],
      "description": "Run tt run <workflow> --dry-run --json"
    },
    {
      "name": "run_workflow",
      "args": ["<workflow>", "[--agent <agent>]", "[--strict]"],
      "description": "Run tt run <workflow> --json"
    },
    {
      "name": "verify_team",
      "args": ["[--workflow <name>]", "[--agent <agent>]", "[--strict]"],
      "description": "Run tt verify --json"
    },
    {
      "name": "read_verify_status",
      "args": [],
      "description": "Run tt verify --last --json"
    },
    {
      "name": "land_agent",
      "args": ["<agent>", "[--pr]", "[--force]"],
      "description": "Land an agent's branch back to current branch, or push and open PR with --pr"
    },
    {
      "name": "generate_handoff",
      "args": ["<agent>", "[--reason <reason>]", "[--ctx <pct>]"],
      "description": "Run tt handoff generate <agent> --json"
    },
    {
      "name": "apply_handoff",
      "args": ["<agent>", "[--packet <path>]"],
      "description": "Run tt handoff apply <agent>"
    },
    {
      "name": "list_handoffs",
      "args": ["[--agent <agent>]", "[--limit <n>]"],
      "description": "Run tt handoff list --json"
    },
    {
      "name": "team_status",
      "args": [],
      "description": "Read .tutti/state/*.json and return agent status payload"
    },
    {
      "name": "agent_output",
      "args": ["<agent>", "[--lines <n>]"],
      "description": "Run tt peek <agent> --lines <n>"
    },
    {
      "name": "stop_agent",
      "args": ["<agent>"],
      "description": "Run tt down <agent>"
    },
    {
      "name": "stop_team",
      "args": [],
      "description": "Run tt down"
    }
  ]
}
```

## File: clawhub/tutti/CHANGELOG.md
size: 843
sha: d683baccccebcff765b0fd7c6a7e294b16229740
upstream: https://github.com/nutthouse/tutti/blob/main/clawhub/tutti/CHANGELOG.md

```text
# Changelog

## 1.1.0 (2026-03-14)

- Add `send_prompt` action with `--auto-up`, `--wait`, and `--output` flags
- Add `land_agent` action wrapping `tt land` with `--pr` and `--force` support
- Document 5 new workflow step types: `ensure_running`, `workflow` (nested), `land`, `review`, and `inject_files` on prompt steps
- Document workflow composition patterns for autonomous fix loops
- 18 total actions (up from 16)

## 1.0.0 (2026-03-14)

Initial release.

- 16 actions covering the full Tutti agent lifecycle
- JSON envelope on all outputs for reliable machine parsing
- Direct state file reads for status (no output parsing)
- Workflow discovery, planning (dry-run), and execution
- Handoff packet generation, application, and listing
- Permission policy checks
- Configurable `tt` binary path via `--tt-bin` flag or `TUTTI_BIN` env var
```

## File: clawhub/tutti/tutti_openclaw.py
size: 13079
sha: 5e309b33f896719bbf3755c99ccdd2bca4cc43bf
upstream: https://github.com/nutthouse/tutti/blob/main/clawhub/tutti/tutti_openclaw.py

```text
#!/usr/bin/env python3
"""
OpenClaw <-> Tutti action wrapper.

This script provides a stable JSON envelope around Tutti commands so an external
agent can call one binary/script entrypoint and always get machine-readable
results.
"""

from __future__ import annotations

import argparse
import json
import os
import shlex
import subprocess
import sys
from dataclasses import dataclass
from pathlib import Path
from typing import Any

@dataclass
class CommandResult:
    ok: bool
    action: str
    command: list[str] | None
    exit_code: int
    data: Any
    stdout: str
    stderr: str
    parse_error: str | None = None
    note: str | None = None

    def to_dict(self) -> dict[str, Any]:
        out: dict[str, Any] = {
            "ok": self.ok,
            "action": self.action,
            "command": self.command,
            "exit_code": self.exit_code,
            "data": self.data,
            "stdout": self.stdout,
            "stderr": self.stderr,
        }
        if self.parse_error:
            out["parse_error"] = self.parse_error
        if self.note:
            out["note"] = self.note
        return out

def _run_tt(action: str, tt_bin: list[str], args: list[str], expect_json: bool) -> CommandResult:
    cmd = [*tt_bin, *args]
    try:
        proc = subprocess.run(cmd, text=True, capture_output=True, check=False)
    except FileNotFoundError:
        return CommandResult(
            ok=False,
            action=action,
            command=cmd,
            exit_code=127,
            data=None,
            stdout="",
            stderr="tt command not found on PATH",
        )

    data: Any = None
    parse_error: str | None = None
    if expect_json:
        payload = proc.stdout.strip()
        if payload:
            try:
                data = json.loads(payload)
            except json.JSONDecodeError as exc:
                parse_error = f"failed to parse command JSON output: {exc}"

    ok = proc.returncode == 0 and (parse_error is None or not expect_json)
    return CommandResult(
        ok=ok,
        action=action,
        command=cmd,
        exit_code=proc.returncode,
        data=data,
        stdout=proc.stdout,
        stderr=proc.stderr,
        parse_error=parse_error,
    )

def _team_status(action: str) -> CommandResult:
    state_dir = Path(".tutti") / "state"
    if not state_dir.exists():
        return CommandResult(
            ok=True,
            action=action,
            command=None,
            exit_code=0,
            data={"agents": [], "count": 0, "state_dir": str(state_dir), "exists": False},
            stdout="",
            stderr="",
            note="state directory not found",
        )

    agents: list[dict[str, Any]] = []
    parse_errors: list[str] = []
    for path in sorted(state_dir.glob("*.json")):
        # ignore non-agent state files
        if path.name in {"verify-last.json"}:
            continue
        try:
            payload = json.loads(path.read_text())
        except Exception as exc:  # pylint: disable=broad-except
            parse_errors.append(f"{path.name}: {exc}")
            continue
        if not isinstance(payload, dict):
            continue
        required = {"name", "runtime", "session_name", "status", "started_at"}
        if required.issubset(payload.keys()):
            agents.append(payload)

    return CommandResult(
        ok=True,
        action=action,
        command=None,
        exit_code=0,
        data={
            "agents": agents,
            "count": len(agents),
            "state_dir": str(state_dir),
            "exists": True,
            "parse_errors": parse_errors,
        },
        stdout="",
        stderr="",
    )

def _agent_output(action: str, tt_bin: list[str], agent: str, lines: int) -> CommandResult:
    result = _run_tt(action, tt_bin, ["peek", agent, "--lines", str(lines)], expect_json=False)
    result.data = {
        "agent": agent,
        "lines": lines,
        "output_lines": result.stdout.splitlines(),
    }
    return result

def _print_and_exit(result: CommandResult) -> None:
    print(json.dumps(result.to_dict(), indent=2))
    raise SystemExit(result.exit_code if result.exit_code >= 0 else 1)

def _build_parser() -> argparse.ArgumentParser:
    parser = argparse.ArgumentParser(
        prog="tutti_openclaw.py",
        description="OpenClaw wrapper for Tutti actions",
    )
    parser.add_argument(
        "--tt-bin",
        default=os.environ.get("TUTTI_BIN", "tt"),
        help="Tutti CLI command/prefix to execute (default: tt, or TUTTI_BIN env var)",
    )
    sub = parser.add_subparsers(dest="action", required=True)

    sub.add_parser("doctor_check", help="Run tt doctor --json")
    p_perm = sub.add_parser("permissions_check", help="Run tt permissions check ... --json")
    p_perm.add_argument("command", nargs=argparse.REMAINDER, help="Command to evaluate")

    sub.add_parser("launch_team", help="Run tt up")
    p_launch = sub.add_parser("launch_agent", help="Run tt up <agent>")
    p_launch.add_argument("agent")

    sub.add_parser("list_workflows", help="Run tt run --list --json")
    p_plan = sub.add_parser("plan_workflow", help="Run tt run <workflow> --dry-run --json")
    p_plan.add_argument("workflow")
    p_plan.add_argument("--agent")
    p_plan.add_argument("--strict", action="store_true")

    p_run = sub.add_parser("run_workflow", help="Run tt run <workflow> --json")
    p_run.add_argument("workflow")
    p_run.add_argument("--agent")
    p_run.add_argument("--strict", action="store_true")

    p_verify = sub.add_parser("verify_team", help="Run tt verify --json")
    p_verify.add_argument("--workflow")
    p_verify.add_argument("--agent")
    p_verify.add_argument("--strict", action="store_true")

    sub.add_parser("read_verify_status", help="Run tt verify --last --json")
    p_gen_handoff = sub.add_parser("generate_handoff", help="Run tt handoff generate <agent> --json")
    p_gen_handoff.add_argument("agent")
    p_gen_handoff.add_argument("--reason")
    p_gen_handoff.add_argument("--ctx", type=int)
    p_apply_handoff = sub.add_parser("apply_handoff", help="Run tt handoff apply <agent>")
    p_apply_handoff.add_argument("agent")
    p_apply_handoff.add_argument("--packet")
    p_list_handoffs = sub.add_parser("list_handoffs", help="Run tt handoff list --json")
    p_list_handoffs.add_argument("--agent")
    p_list_handoffs.add_argument("--limit", type=int, default=20)
    sub.add_parser("team_status", help="Read .tutti/state/*.json")

    p_output = sub.add_parser("agent_output", help="Run tt peek <agent> --lines N")
    p_output.add_argument("agent")
    p_output.add_argument("--lines", type=int, default=100)

    p_send = sub.add_parser("send_prompt", help="Send prompt to agent with auto-up/wait/output")
    p_send.add_argument("agent")
    p_send.add_argument("prompt", nargs=argparse.REMAINDER, help="Prompt text")
    p_send.add_argument("--auto-up", action="store_true", help="Start agent if not running")
    p_send.add_argument("--wait", action="store_true", help="Wait for agent to finish")
    p_send.add_argument("--output", action="store_true", help="Capture agent response")
    p_send.add_argument("--timeout-secs", type=int, default=900)
    p_send.add_argument("--idle-stable-secs", type=int, default=5)
    p_send.add_argument("--output-lines", type=int, default=200)

    p_land = sub.add_parser("land_agent", help="Run tt land <agent>")
    p_land.add_argument("agent")
    p_land.add_argument("--pr", action="store_true", help="Push branch and open PR")
    p_land.add_argument("--force", action="store_true", help="Force land")

    p_stop = sub.add_parser("stop_agent", help="Run tt down <agent>")
    p_stop.add_argument("agent")
    sub.add_parser("stop_team", help="Run tt down")
    return parser

def main() -> None:
    parser = _build_parser()
    args = parser.parse_args()
    action = args.action
    tt_bin = shlex.split(args.tt_bin)
    if not tt_bin:
        result = CommandResult(
            ok=False,
            action=action,
            command=None,
            exit_code=2,
            data=None,
            stdout="",
            stderr="--tt-bin resolved to empty command",
        )
        _print_and_exit(result)

    if action == "doctor_check":
        _print_and_exit(_run_tt(action, tt_bin, ["doctor", "--json"], expect_json=True))

    if action == "permissions_check":
        if not args.command:
            result = CommandResult(
                ok=False,
                action=action,
                command=None,
                exit_code=2,
                data=None,
                stdout="",
                stderr="permissions_check requires a command payload",
            )
            _print_and_exit(result)
        _print_and_exit(
            _run_tt(
                action,
                tt_bin,
                ["permissions", "check", *args.command, "--json"],
                expect_json=True,
            )
        )

    if action == "launch_team":
        _print_and_exit(_run_tt(action, tt_bin, ["up"], expect_json=False))
    if action == "launch_agent":
        _print_and_exit(_run_tt(action, tt_bin, ["up", args.agent], expect_json=False))
    if action == "list_workflows":
        _print_and_exit(_run_tt(action, tt_bin, ["run", "--list", "--json"], expect_json=True))
    if action == "plan_workflow":
        cmd = ["run", args.workflow, "--dry-run", "--json"]
        if args.agent:
            cmd.extend(["--agent", args.agent])
        if args.strict:
            cmd.append("--strict")
        _print_and_exit(_run_tt(action, tt_bin, cmd, expect_json=True))
    if action == "run_workflow":
        cmd = ["run", args.workflow, "--json"]
        if args.agent:
            cmd.extend(["--agent", args.agent])
        if args.strict:
            cmd.append("--strict")
        _print_and_exit(_run_tt(action, tt_bin, cmd, expect_json=True))
    if action == "verify_team":
        cmd = ["verify", "--json"]
        if args.workflow:
            cmd.extend(["--workflow", args.workflow])
        if args.agent:
            cmd.extend(["--agent", args.agent])
        if args.strict:
            cmd.append("--strict")
        _print_and_exit(_run_tt(action, tt_bin, cmd, expect_json=True))
    if action == "read_verify_status":
        _print_and_exit(
            _run_tt(action, tt_bin, ["verify", "--last", "--json"], expect_json=True)
        )
    if action == "generate_handoff":
        cmd = ["handoff", "generate", args.agent, "--json"]
        if args.reason:
            cmd.extend(["--reason", args.reason])
        if args.ctx is not None:
            cmd.extend(["--ctx", str(args.ctx)])
        _print_and_exit(_run_tt(action, tt_bin, cmd, expect_json=True))
    if action == "apply_handoff":
        cmd = ["handoff", "apply", args.agent]
        if args.packet:
            cmd.extend(["--packet", args.packet])
        _print_and_exit(_run_tt(action, tt_bin, cmd, expect_json=False))
    if action == "list_handoffs":
        cmd = ["handoff", "list", "--json", "--limit", str(args.limit)]
        if args.agent:
            cmd.extend(["--agent", args.agent])
        _print_and_exit(_run_tt(action, tt_bin, cmd, expect_json=True))
    if action == "team_status":
        _print_and_exit(_team_status(action))
    if action == "agent_output":
        _print_and_exit(_agent_output(action, tt_bin, args.agent, args.lines))
    if action == "send_prompt":
        if not args.prompt:
            result = CommandResult(
                ok=False,
                action=action,
                command=None,
                exit_code=2,
                data=None,
                stdout="",
                stderr="send_prompt requires a prompt",
            )
            _print_and_exit(result)
        cmd = ["send", args.agent]
        if args.auto_up:
            cmd.append("--auto-up")
        if args.wait:
            cmd.append("--wait")
            cmd.extend(["--timeout-secs", str(args.timeout_secs)])
            cmd.extend(["--idle-stable-secs", str(args.idle_stable_secs)])
        if args.output:
            cmd.append("--output")
            cmd.extend(["--output-lines", str(args.output_lines)])
        cmd.extend(args.prompt)
        _print_and_exit(_run_tt(action, tt_bin, cmd, expect_json=False))
    if action == "land_agent":
        cmd = ["land", args.agent]
        if args.pr:
            cmd.append("--pr")
        if args.force:
            cmd.append("--force")
        _print_and_exit(_run_tt(action, tt_bin, cmd, expect_json=False))
    if action == "stop_agent":
        _print_and_exit(_run_tt(action, tt_bin, ["down", args.agent], expect_json=False))
    if action == "stop_team":
        _print_and_exit(_run_tt(action, tt_bin, ["down"], expect_json=False))

    result = CommandResult(
        ok=False,
        action=action,
        command=None,
        exit_code=2,
        data=None,
        stdout="",
        stderr=f"unsupported action: {action}",
    )
    _print_and_exit(result)

if __name__ == "__main__":
    main()
```

## File: README.md
upstream: https://github.com/nutthouse/tutti/blob/main/README.md

````text
# tutti

**Terraform-style agent operations for AI coding tools. Define your agent team, run repeatable workflows, track every artifact and gate, and move from messy terminal sessions to versioned engineering operations.**

```bash
cargo install tutti
```

Tutti is the operations layer above Claude Code, Codex, Aider, OpenClaw, and API-direct agents. It gives each agent a role, worktree, workflow, audit trail, and dashboard so issue intake, implementation, review, CI, and merge gates happen as repeatable "org code" in `tutti.toml`.

Agent SDKs help you build agents. Tutti helps you **run agent work**.

![Factory floor — 5 agents working through an SDLC pipeline](docs/images/factory-floor.png)

*Factory floor: 3 agents working simultaneously, work-item dots flowing through the pipeline, dispatch panel to trigger runs from the browser.*

![Agent Focus Mode — live terminal, usage stats, git diff](docs/images/agent-focus.png)

*Agent Focus Mode: live terminal output, token usage stats (985K input, 41.6M cache read), prompt bar to send instructions.*

## Quick Start

```bash
cargo install tutti        # install the CLI (requires Rust)
cd your-project
tt init --template rust-cli # generate a Rust CLI agent-ops config
tt run --list              # see workflows generated for this repo
tt run verify --strict     # first successful workflow: cargo test + clippy
tt up                      # launch your persistent agent team
tt serve --port 4040       # inspect runs, agents, logs, and handoffs
```

Or pick a template explicitly:

```bash
tt init --template gstack-startup   # 5-agent interactive SDLC team
tt init --template rust-cli         # 3-agent Rust project team
tt init --template minimal          # 2-agent starter
```

**Prerequisites:** Rust toolchain, tmux, and at least one AI coding CLI installed for agent sessions (Claude Code, Codex, or Aider). Command-only workflows such as the Rust template's `verify` can run before you launch agents. For non-Rust repos, start with `tt init` or `tt init --template minimal`, then add the smallest verification command your project already trusts.

## The Agent Ops Loop

Tutti models the engineering loop as pluggable operational stages:

1. **Intake**: GitHub issue, Linear ticket, Jira ticket, local queue, or webhook event.
2. **Execution**: Claude Code, Codex, Aider, OpenClaw, or API-direct model providers.
3. **Review**: CodeRabbit, Claude/Codex reviewer packets, human approval, CI, or policy checks.
4. **Gate**: required checks, resolved review threads, approval state, cost/policy limits.
5. **Record**: run ledger, artifacts, logs, dashboard events, and replayable state.

The built-in Tutti-for-Tutti workflow uses GitHub issue intake and CodeRabbit review because that is the first concrete adapter pair. It is not the product boundary. The product boundary is the loop.

## What Tutti Does

- **Defines agent operations as code** in `tutti.toml`: roles, runtimes, workflows, hooks, gates, and policies
- **Spawns and manages** multiple AI coding agent sessions (Claude Code, Codex, Aider) in tmux
- **Isolates each agent** in its own git worktree to prevent merge conflicts
- **Orchestrates workflows** — chain prompt steps, shell commands, and agent coordination into repeatable pipelines defined in `tutti.toml`
- **Web dashboard** at `:4040` — factory-floor view of all agents with real-time SSE updates, state-driven visuals (working/idle/stopped/blocked), and workflow run tracking
- **Agent Focus Mode** — click any agent to zoom into full-screen view with live terminal output, token usage, git diff, context health, and a prompt input bar
- **Automated SDLC** — claim work, plan, implement, test, open PRs, collect reviews, resolve feedback, and enforce merge gates
- **API-direct agent loop** — optional ModelProvider path with built-in tools, policy gates, SQLite event log, and cost tracking
- **Resilience** — detects auth failures, rate limits, and provider outages; auto-recovers sessions based on configured strategies
- **Issue claim leases** — exclusive locks on GitHub issues for autonomous workflow runs

## What Tutti Does Not Do

- **Not another generic agent framework.** Tutti is the operations layer around agent work: lifecycle, workflow, state, review, policy, and observability.
- **Not tied to one provider.** It can orchestrate terminal agents and, where configured, run API-direct model providers through the same operational controls.
- **No API keys required for CLI-agent mode.** Existing Claude Code, Codex, Aider, or OpenClaw authentication keeps working. API-direct runs opt into provider credentials explicitly.
- **No vendor lock-in.** Your agent operations live in a versioned `tutti.toml` file you can review, fork, and move.

## When To Use Tutti

Tutti is strongest when **coordination is the bottleneck**, not raw model quality:

- You already run multiple agent sessions and the human is doing the routing, tracking, and merge management by hand
- Work splits cleanly into separable lanes: implementation, testing, docs, review
- You want persistent specialists working through a backlog, not five agents crowding one change
- The work contains waiting states that parallel agents can hide: test runs, review loops, CI, retries

A single agent is often the better choice when the repo is small, the task is tightly coupled, or the coordination tax would outweigh any throughput gain.

## Configuration

Your agent team topology is defined in `tutti.toml` — who does what, which runtime, what workflows:

```toml
[workspace]
name = "my-project"

[roles]
implementer = "claude-code"
tester = "claude-code"
reviewer = "codex"

[[agent]]
name = "implementer"
role = "implementer"

[[agent]]
name = "tester"
role = "tester"

[[workflow]]
name = "verify"
[[workflow.step]]
type = "prompt"
agent = "tester"
text = "Run the test suite and report results."
wait_for_idle = true
```

Swap `claude-code` for `codex` in `[roles]` and every agent using that role switches runtime — no per-agent edits. Version it. Share it. Fork someone else's.

## Alternative Installation

```bash
# Install from crates.io
cargo install tutti

# Or install from source
git clone https://github.com/nutthouse/tutti.git
cd tutti
cargo install --path . --locked

# Initialize in your project
cd your-project
tt init

# Edit your team config
$EDITOR tutti.toml

# Launch
tt up
```

If `tt` is not found after install, add Cargo bin to your shell PATH:

```bash
echo 'export PATH="$HOME/.cargo/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc
```

## Project Status (v0.10.0+ — May 2026)

### Built and usable now
- Core CLI commands: `init`, `up`, `down`, `status`, `voices`, `watch`, `switch`, `diff`, `detect`, `land`, `review`, `send`, `handoff`, `attach`, `peek`, `logs`, `usage`, `run`, `verify`, `doctor`, `permissions`, `workspaces`, `issue-claim`
- Runtime adapters: Claude Code, Codex CLI, Aider, OpenClaw
- API-direct spine: `ModelProvider`, OpenAI-compatible provider, tool execution loop, policy gate, SQLite event log
- Template packs: `tt init --template gstack-startup` generates a fully configured team from built-in or custom templates, with repo auto-detection
- Role mapping: `[roles]` table maps logical roles to runtimes — swap providers without editing every agent
- Artifact pipeline: prompt steps capture and pass typed artifacts between workflow stages via `artifact_glob`/`artifact_name`
- Artifact-polling mode: interactive skills (e.g. `/office-hours`) wait for artifact files instead of idle detection, enabling human-in-the-loop workflows
- Dependency-aware startup order (`depends_on`)
- Per-agent git worktree isolation
- Cross-workspace registry (`tt workspaces`, `tt up --all`, `tt down --all`)
- Token/capacity reporting via `tt usage` for API profiles (`plan = "api"`) from local Claude Code + Codex session logs
- `max_concurrent` launch guardrails per profile (`tt up` refuses launches above limit)
- Workspace `[[tool_pack]]` declarations + `tt doctor` prerequisite checks (
````
