Skip to content

Finish Tutti trust and activation sprint #130

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wren-nutthouse wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Finish Tutti trust and activation sprint #130

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
0b71b64
Ship Tutti trust and activation sprint slice
wren-nutthouse May 5, 2026
35ed773
Add Tutti sprint review and prioritization docs
wren-nutthouse May 5, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
20 changes: 17 additions & 3 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
# tutti

**Multi-agent orchestration for AI coding tools. Coordinate Claude Code, Codex, and Aider agents as a team — with a real-time web dashboard, automated SDLC workflows, and per-agent git worktree isolation.**
**Tutti is the operator layer for multi-agent coding workflows.** It runs Claude Code, Codex, and Aider as a coordinated team, gives each agent its own git worktree, and shows you what’s happening in real time.

```bash
cargo install tutti
```

Tutti spawns multiple AI coding agents in tmux sessions, gives each one its own git worktree, and orchestrates them through configurable workflows — plan, implement, test, review, ship. A web dashboard shows every agent's status in real time. Click any agent to see its live terminal output, token usage, and code changes.
Use Tutti when one agent is no longer the bottleneck, but unmanaged parallelism is. It handles session orchestration, workflow dispatch, and operator visibility so you stop doing the routing, tracking, and merge management by hand.

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

Expand All @@ -29,6 +29,19 @@ tt run sdlc-auto # run a full plan→implement→test→review→ship

**Prerequisites:** Rust toolchain, tmux, and at least one AI coding CLI installed (Claude Code, Codex, or Aider).

## Why Tutti exists

If you already use coding agents, the pain is rarely “the model is bad.”
It’s usually one of these:

- you are manually routing work between multiple agent sessions
- you lose track of which agent is doing what
- agents step on each other’s changes
- review, test, and handoff loops are inconsistent
- parallel work creates more supervision overhead than it saves

Tutti fixes that layer.

## What Tutti Does

- **Spawns and manages** multiple AI coding agent sessions (Claude Code, Codex, Aider) in tmux
Expand Down Expand Up @@ -85,7 +98,7 @@ wait_for_idle = true

Version it. Share it. Fork someone else's.

## Quick Start
## Install from source

```bash
# Install from crates.io
Expand Down Expand Up @@ -307,6 +320,7 @@ Reusable prompt components and skills are **phrases**. A phrase might be a CLAUD

### Automation (Built)
- `tt run` / `tt verify` reusable workflow execution with persisted run records
- `tt runs activation` reports whether a workspace has reached its first successful workflow run
- Run checkpoints persisted at `.tutti/state/workflow-checkpoints/<run_id>.json` + `tt run --resume <run_id>`
- Workflow step types: `prompt`, `command`, `ensure_running`, `workflow` (nested), `review`, `land`
- Workflow `review`/`land` steps auto-start required sessions when they are not already running
Expand Down
62 changes: 62 additions & 0 deletions docs/tutti-activation-telemetry-plan-2026-05-05.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,62 @@
# Tutti Activation Telemetry Plan — 2026-05-05

## Goal
Define the minimum activation signal for Tutti without adding analytics bloat.

## Recommendation
Use the existing control-plane event stream and run ledger.

Do not build a separate telemetry system for this sprint.

## Activation definition
A workspace is **activated** when it reaches its **first successful orchestrated workflow run**.

Recommended exact signal:
- first `workflow.completed` event where:
- the run belongs to a real workspace
- the workflow is user-triggered or first-run guided
- the run result is successful
Comment on lines +14 to +18

@coderabbitai coderabbitai Bot May 5, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Description: Check if workflow events contain trigger/source metadata

# Look for workflow.completed event structure in the codebase
rg -n "workflow\.completed" -A 5 -B 5 --type=rust

# Check ControlEvent enum definition for available fields
ast-grep --pattern 'enum ControlEvent {
  $$$
}'

Repository: nutthouse/tutti

Length of output: 3294

🏁 Script executed:

#!/bin/bash
# Find ControlEvent struct/enum definition
rg -n "struct ControlEvent|enum ControlEvent" -A 10 --type=rust

# Look for where workflow trigger type might be stored
rg -n "trigger|first-run|guided" --type=rust -i | head -30

# Check the workflow completion logic for trigger info
rg -n "fn.*workflow.*complete|workflow_trigger|trigger_type" --type=rust -i

Repository: nutthouse/tutti

Length of output: 3161

🏁 Script executed:

#!/bin/bash
# Find WorkflowCompletePayload struct definition
rg -n "struct WorkflowCompletePayload|WorkflowCompletePayload" -A 10 --type=rust | head -40

# Check how workflow.completed events are created and what data is included
rg -n "append_control_event.*workflow.completed" -B 5 -A 5 --type=rust

# Look at the activation logic in runs.rs more closely
sed -n '280,310p' src/cli/runs.rs

# Check if trigger source is captured anywhere in workflow complete
rg -n "success.*trigger|trigger.*source|user.triggered|first.run" --type=rust -i | head -20

Repository: nutthouse/tutti

Length of output: 3523

🏁 Script executed:

#!/bin/bash
# Find HookWorkflowSource enum definition
rg -n "enum HookWorkflowSource" -A 10 --type=rust

# Check how workflow_source from WorkflowCompletePayload flows into event data
rg -n "append_control_event" -B 10 -A 3 --type=rust | grep -A 13 "workflow.completed"

# Look for where workflow.completed event is created with data
rg -n "workflow.completed.*data|workflow.completed.*json|append_control_event.*success" -B 5 -A 5 --type=rust

# Check for workspace validation or real workspace determination
rg -n "real.workspace|test.workspace|workspace.*validation" --type=rust -i

Repository: nutthouse/tutti

Length of output: 1206

🏁 Script executed:

#!/bin/bash
# Get the complete workflow.completed event creation
sed -n '4160,4195p' src/automation/mod.rs

# Also check what data is included - look for the complete append_control_event call
sed -n '4172,4190p' src/automation/mod.rs

Repository: nutthouse/tutti

Length of output: 1855

🏁 Script executed:

#!/bin/bash
# Check the plan document itself
cat docs/tutti-activation-telemetry-plan-2026-05-05.md | head -50

# Find ExecutionOrigin enum
rg -n "enum ExecutionOrigin" -A 15 --type=rust

# Search for first-run or guided setup
rg -n "first.run|guided|onboarding" --type=rust -i | head -20

Repository: nutthouse/tutti

Length of output: 2615

🏁 Script executed:

#!/bin/bash
# Check for TODOs or FIXMEs around activation logic
rg -n "TODO|FIXME|XXX" src/cli/runs.rs

# Check if there's any filtering logic planned or mentioned in comments
rg -n "real.workspace|first.run|activation.*filter|first.*successful" --type=rust -i

# Verify the full activation logic once more
sed -n '275,310p' src/cli/runs.rs

Repository: nutthouse/tutti

Length of output: 1475

Activation criteria are not currently enforced; "first-run guided" tracking is missing.

The plan specifies three criteria for the activation signal, but the current implementation (src/cli/runs.rs:275-290) only checks for workflow.completed event existence without validating:

  • success status (event data has "success" field but it's not filtered)
  • user-triggered vs automated runs (event data has "origin" field that could distinguish ExecutionOrigin::Run from system-triggered workflows, but filtering is not implemented)
  • "first-run guided" status (this metadata is not tracked anywhere in the codebase)
  • real workspace vs test workspace (no validation exists)

The critical gap is that "first-run guided" has no mechanism to be captured or identified. Before this sprint, clarify whether:

  1. All completed workflows should count as activation (ignore the criteria for now)
  2. Only ExecutionOrigin::Run workflows count as "user-triggered" (feasible with current origin field)
  3. "First-run guided" should be added as a tracked field or deferred to a future sprint
🤖 Prompt for AI Agents 
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/tutti-activation-telemetry-plan-2026-05-05.md` around lines 14 - 18, The
current workflow.completed handler in src/cli/runs.rs (around the code handling
the event at lines ~275-290) only checks for event existence and must be
tightened: update the handler that processes workflow.completed events to (1)
verify the run result by checking event.data.success == true, (2) filter by
origin by requiring event.data.origin == ExecutionOrigin::Run (use the
ExecutionOrigin enum), (3) exclude test/workspace runs by checking the workspace
record (e.g., workspace.is_test or workspace.metadata indicating a real
workspace) and (4) add a way to capture "first-run guided" (either by adding a
first_run_guided boolean to the Run/Workflow metadata and persisting it when the
guided flow triggers, or defer and flag it as out-of-scope and only count
user-triggered runs for now). Modify the workflow.completed processing function
to return early if any of these checks fail and ensure logs reflect which check
caused the drop so telemetry only records the exact activation signal.


## Activation funnel for this sprint
Track only these milestones:
1. `tt init` completed
2. `tt up` succeeded
3. first workflow started (`workflow.started`)
4. first workflow completed successfully (`workflow.completed`)

That is enough to answer:
- are installs reaching first value?
- where are they dropping?
- is onboarding improving activation?

## What already exists
Current Tutti already has:
- persisted control events in `.tutti/state/events.jsonl`
- workflow lifecycle events including `workflow.started` and `workflow.completed`
- run records and local API endpoints for runs/events
- SSE/event stream exposure via `/v1/events` and `/v1/events/stream`

## Sprint scope for #25
For this sprint, keep it narrow:
- document the activation definition
- ensure the docs point to the existing event sources
- if needed later, add one lightweight helper command or doc example for querying first successful run

## Explicit non-goals
Not this sprint:
- third-party product analytics
- cohort dashboards
- hosted telemetry backend
- deep retention instrumentation
- broad event schema redesign

## Suggested next implementation slice
If we want one concrete engineering follow-up after this doc:
- add a small operator-facing command or example script that answers:
- "Has this workspace activated yet?"
- "When was the first successful workflow run?"

## Why this is the right cut
Tutti already emits the important events.
The problem is not missing telemetry plumbing.
The problem is missing activation definition and operator-facing usage of the data already there.
232 changes: 232 additions & 0 deletions docs/tutti-gstack-review-2026-05-05.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,232 @@
# Tutti — GStack-style Product Review

Date: 2026-05-05
Reviewer: Wren
Method: local OpenClaw GStack scaffold (`office-hours` + `ceo-review` style synthesis)

## Bottom line

**Recommendation: Accelerate, but narrow.**

Tutti has crossed the line from "clever internal tool" to **real emerging product signal**. The stars, forks, merged PR cadence, green Actions, and issue depth mean this is no longer just a private toy. But the risk now is classic founder overreach: building the whole future of agent operations before nailing the one thing that makes people trust it.

The right move is **not** to broaden the roadmap. The right move is to make Tutti feel undeniably reliable for the operator managing multi-agent coding work.

---

## 1) User problem

Tutti solves a very real and increasingly painful problem:

> Once you have more than one coding agent, coordination becomes the bottleneck.

The pain is not "I need a smarter model."
It is:
- routing work across agents
- keeping worktrees isolated
- seeing what each agent is doing
- recovering from stalls, auth failures, and provider weirdness
- turning ad hoc multi-agent chaos into repeatable workflows

This is a sharp problem. It exists today. And it gets worse as more people try to orchestrate Claude Code, Codex, Aider, and OpenClaw together.

---

## 2) Target user

Primary user:
- technical power user
- founder/operator/dev who already lives in terminals and repos
- already using multiple agents or clearly about to
- feels the pain of manual coordination, not just model quality

Not the primary user right now:
- average solo dev with one agent
- enterprise buyer wanting polished compliance theater first
- anyone who still needs to be convinced that agent-based coding is worth doing

This is a product for **people already over the threshold**.

---

## 3) Why now

Because multi-agent coding just became legible enough to hurt.

A year ago, this would have been too early and too weird.
Now the ingredients exist:
- agent CLIs are real
- people are running multiple sessions
- providers fail in annoying, visible ways
- orchestration and observability are the missing layer

The repo traction matters because it suggests this pain is not private. **32 stars and 2 forks for a niche agent-ops tool is non-trivial**, especially with recent PR flow and active issue evolution.

This is still early, but the timing is good.

---

## 4) Differentiation

Tutti's differentiation is strongest when positioned as:

> **The operator layer for multi-agent coding workflows**

Not another agent.
Not a general AI platform.
Not an LLM wrapper.

The strongest differentiators visible right now are:
- orchestration across existing agent CLIs
- per-agent worktree isolation
- workflow automation for SDLC paths
- real-time operator visibility / dashboard
- resilience and recovery posture
- issue-claim and multi-step automation framing

That is a coherent wedge.

Where differentiation gets blurry:
- if the message becomes "everything for all agent workflows"
- if roadmap breadth outruns the operator-core product truth
- if it starts sounding like generic autonomy theater

---

## 5) Smallest magical product

The smallest magical version of Tutti is **not** the full roadmap.
It is this:

> A developer launches multiple agents, sees them clearly, routes work confidently, and can trust the system not to silently stall or lose the thread.

Concretely, the magical core is:
- reliable session orchestration
- operator console / dashboard visibility
- deterministic workflow execution
- strong stall/recovery detection
- confidence that a run either progresses or fails clearly

This is why issue **#122** matters so much. A spinner-detection miss sounds small, but it attacks the product's deepest promise: **can I trust the orchestration layer?**

---

## 6) Traction interpretation

Current signals checked today:
- 32 stars
- 2 forks
- recent merged PR activity
- green Actions
- no open PR backlog
- live issue queue with substantive product/system discussions

Interpretation:
- This is **real early traction**, not breakout traction.
- The most important part is not the absolute number. It is the combination of:
- external attention
- continued maintenance velocity
- evidence of product thinking in issues
- visible movement in releases and workflow polish

The forks matter because they imply at least some people want to do more than spectate.
That’s a stronger signal than passive stars.

But don’t overread it. This is a **promising wedge**, not proof of durable adoption yet.

---

## 7) Biggest failure modes

### A. Reliability gap kills trust
If orchestration says "idle" while the agent is actually working, the whole product feels flaky.
This is existentially bad for an operator tool.

### B. Roadmap sprawl
Mailbox, uploads, remote access, approvals, cost guardrails, release finalizers, RBAC, deployment story, trust pack — all sensible individually, but together they can blur the near-term product spine.

### C. Positioning drift
If Tutti is described too broadly, people will not know whether it is for:
- agent ops
- remote coding
- enterprise control
- workflow automation
- dashboarding
- autonomy infrastructure

The repo already hints at the right answer: **agent operations layer**. Stay there.

### D. Premature enterprise surface area
Identity/RBAC/compliance/deployment stories matter later, but they are not the reason current users care.

### E. Coordination tax outweighs delight
If the setup, workflow config, or mental overhead is too high, only the already-convinced will persist.

---

## 8) What to exclude for now

Deliberately de-prioritize, unless pulled by direct user demand:
- full enterprise trust/compliance packaging
- broad RBAC/org model work
- expansive platform messaging
- overbuilt remote/media bridge before core reliability is sharp
- autonomy flourish that is impressive but not trusted

This does **not** mean these are bad ideas.
It means they are not the best immediate use of scarce founder attention.

---

## 9) Recommended immediate focus

### Keep / kill / narrow / accelerate
- **Keep:** operator console, orchestration reliability, workflow repeatability
- **Kill:** any urge to market this as a broad universal AI operations platform right now
- **Narrow:** roadmap emphasis to trust + operator clarity + first-run proof of value
- **Accelerate:** the fixes and UX improvements that make real dogfooding feel solid

### Highest-leverage issue sequence
1. **#122** — spinner/activity detection reliability
2. **#24** — positioning and onboarding narrative
3. **#25** — telemetry and activation instrumentation
4. **#56** — agent mailbox for coordination
5. **#83** — context bridge / uploads to remote agents

Why this order:
- #122 protects trust
- #24 improves comprehension
- #25 makes learning measurable
- #56 deepens the core product
- #83 expands surface area after the core feels real

---

## 10) Recommended next sprint

If I were running Tutti for the next sprint, I would make it:

### Sprint theme
**"Make the operator trust it."**

### Sprint goals
- fix workflow/idle-detection reliability papercuts
- tighten the operator story in README/onboarding
- instrument the first-success path so traction becomes legible

### Success criteria
- a dogfood run no longer false-fails on visible agent activity
- a new technically literate user can explain Tutti in one sentence after the README
- you can measure whether installs reach first successful workflow run

---

## Final opinionated take

Tutti is interesting because it is **practical**, not because it is futuristic.
That’s the asset.

Do not drown it in platform ambition.
Make it the most trustworthy way to run a small team of coding agents.
If you nail that, the rest of the roadmap gets easier and the traction compounds.
If you don’t, the roadmap becomes expensive decoration.
Loading
Loading