6 min read Intermediate

How to Run Parallel Agents with Tendril

The power of Tendril isn't a single AI assistant answering questions — it's a master agent that breaks your work into parallel tracks and runs them simultaneously. This guide shows you how to decompose a task, launch sub-agents, and review their output before anything merges.

How Decomposition Works

You start by writing a task in plain language — the same way you'd write a ticket or a Slack message to a senior developer. For example:

Example task

"Add a dark-mode toggle to the settings page. It should persist the user's choice in localStorage and respect their OS preference on first load."

Tendril's master agent reads this description alongside your project context and identifies the independent units of work that can run in parallel without conflicting. For the example above, it might produce:

  • Subtask 1 — Add useColorScheme hook with localStorage persistence
  • Subtask 2 — Add OS preference detection via prefers-color-scheme media query
  • Subtask 3 — Wire toggle UI component to the hook in SettingsPage.tsx
  • Subtask 4 — Add CSS variables for dark mode to global.css

Subtasks 1, 2, and 4 can run concurrently. Subtask 3 depends on Subtask 1 completing first, so the master agent schedules it to start as soon as that dependency resolves.

Reviewing the Plan Before Launch

Tendril does not immediately launch agents. After decomposition, it presents the full subtask plan in a Review Plan modal before anything starts. You can:

  • Edit a subtask's description to give the agent more specific instructions
  • Merge two subtasks together if the separation feels too granular
  • Remove a subtask you want to handle manually
  • Add a custom subtask the master agent didn't generate automatically

Once you click Launch Run, the plan is locked and agents begin working. You can always stop a run mid-flight, but any completed subtasks will still require review.

How the Master Agent Assigns Sub-Agents

The master agent acts as a coordinator, not a worker. Its job is to:

  • Assign each subtask to a dedicated sub-agent with the relevant project context prepended
  • Enforce dependency ordering — sub-agents waiting on another subtask's output are held in a Blocked state
  • Pass the output of completed subtasks as input context to dependent sub-agents
  • Surface any detected conflicts (e.g., two agents editing the same file) as warnings before they run

Sub-agents are stateless — each one receives a complete context packet from the master agent and produces a complete output (code diff + explanation). They don't share state between each other directly; the master agent mediates all handoffs.

Reading the Kanban in Real Time

While a run is active, the Kanban board in your Tendril dashboard updates live. Cards move through four columns:

To Do

Subtasks queued but not yet assigned. If you're on Free, only 1 card moves to In Progress at a time.

In Progress

An agent is actively working. You can expand the card to see a live thought-process stream.

Review

The agent finished. The card shows a diff summary and waits for your approval before anything is committed.

Done

You approved the output. The changes are queued for the merge PR Tendril will open on your behalf.

Blocked cards appear with an orange border and show which dependency they're waiting on. If an agent encounters an unexpected error, the card moves to a Failed state with an explanation you can use to retry or edit the subtask.

Review and Approve Agent Output

Every completed subtask lands in the Review column as a diff — additions in green, removals in red, identical to a GitHub pull request diff. The review screen shows:

  • Files changed, lines added/removed
  • The agent's explanation of why it made each change
  • A link to the relevant subtask description for context

Approval options

  • Approve — accepts the diff and moves the card to Done
  • Request changes — sends the agent a follow-up instruction to revise its output; the card returns to In Progress
  • Reject — discards the subtask output entirely; you can rewrite the subtask and re-run

After all subtasks are approved, Tendril opens a single pull request on GitHub containing all the changes. The PR description is auto-generated by the master agent and lists every subtask and its approval status.

How Tendril sizes concurrency

Tendril does not impose its own concurrency cap. You run as many parallel sub-agents as your hardware and your AI provider's rate limits allow. Set the concurrency you want in Settings → Pipeline → Max concurrent sub-agents.

If your daily or monthly token cap exhausts mid-run, every actively-running project pauses cleanly and surfaces a Resume banner you click after the cap window resets. You decide which paused project gets the new headroom — Tendril does not auto-resume.

Next Steps