Tendril

Tendril is an agentic orchestration tool that parallelizes software development across multiple AI agents. It uses git worktrees to create isolated working directories — each on its own branch with Claude Code ready to go — so you can run multiple AI-assisted dev tasks simultaneously without leaving your host machine.

Instead of running one agent on one branch, Tendril lets you orchestrate many agents at once: open a terminal, run tndrl start, and fire off a task. Open another terminal, do it again. Each agent works independently in its own worktree, on its own branch, with full repo access and all your existing dev tools.

For workloads that need full isolation, Tendril also supports Docker containers via the --container flag.

Prerequisites

• macOS (v1 target platform)
• Rust 1.85+ (uses edition 2024)
• Git with an origin remote configured
• Claude Code CLI installed (npm install -g @anthropic-ai/claude-code)
• Docker (optional, only needed for --container mode) — any of these work:
  • Docker Desktop
  • OrbStack (recommended, lighter weight)
  • Colima

Install

git clone <this-repo>
cd tendril
cargo build --release

The binary is at target/release/tndrl. Add it to your PATH or use cargo install --path ..

Usage

Start a new session (worktree — default)

tndrl start

This will:

1. Detect your repo's git remote URL from the current directory
2. Prompt you for a branch name
3. Create a git worktree at ~/.tendril/worktrees/<session-id> (creates the branch if it doesn't exist)
4. Launch Claude Code directly in the worktree directory

After launching, you'll land in a Claude Code session inside the worktree. Open another terminal and run tndrl start again to spin up a parallel session on a different branch.

You can also pass the branch name directly:

tndrl start --branch feature/my-task

Start a container session (optional)

tndrl start --container

This uses Docker to spin up an isolated Linux container with your repo cloned inside. Useful when you need a clean environment or specific runtime dependencies. See Container mode below for details.

List active sessions

tndrl list

Displays a table of all sessions with their status, branch/container info, repository, and start time.

+----------+---------+--------------------+----------------------------------+------------------------+
| ID       | Status  | Branch / Container | Repository                       | Started At             |
+----------+---------+--------------------+----------------------------------+------------------------+
| a1b2c3d4 | Running | feature/auth       | git@github.com:user/repo.git     | 2026-02-13 15:30:00 UTC|
| e5f6g7h8 | Stopped | feature/api        | git@github.com:user/repo.git     | 2026-02-13 14:00:00 UTC|
| i9j0k1l2 | Running | 3a4b5c6d7e8f       | git@github.com:user/repo.git     | 2026-02-13 16:00:00 UTC|
+----------+---------+--------------------+----------------------------------+------------------------+

How it works

Worktree sessions (default)

Git worktrees let you check out multiple branches of the same repository simultaneously in separate directories. Tendril leverages this to create isolated workspaces without any virtualization overhead.

Each worktree session:

• Creates a new directory at ~/.tendril/worktrees/<session-id>
• Checks out the specified branch (or creates it if it doesn't exist)
• Inherits your host's SSH keys, git config, dev tools, and environment
• Runs Claude Code natively — no Docker, no containers, no overhead
• Tracks session state in ~/.tendril/sessions.json

This is fast, lightweight, and leverages everything already installed on your machine.

Container mode

When you need full isolation, pass --container to use Docker instead:

tndrl start --container

On first run, Tendril builds a tendril-dev:latest Docker image with:

• Ubuntu 22.04
• git, curl, wget, build-essential, ca-certificates, openssh-client
• sudo, vim, jq, python3, python3-pip
• Node.js 20.x
• Claude Code CLI (@anthropic-ai/claude-code)
• A non-root dev user with passwordless sudo

Each container gets:

• ~/.ssh mounted read-only (for git clone access)
• ~/.gitconfig mounted read-only (for git identity)
• Your repo cloned from its remote into /workspace/repo
• Docker labels tracking the session ID and repo URL

Containers are named tendril-<session-id> for easy identification in docker ps.

Session tracking

Session metadata is persisted to ~/.tendril/sessions.json. The list command reads this file and reconciles with the actual state — checking worktree directory existence or Docker container status.

Project structure

src/
  main.rs      -- CLI parsing, start/list command orchestration
  worktree.rs  -- Git worktree creation, branch detection, Claude launch
  docker.rs    -- Docker connection, container lifecycle, repo cloning, terminal attach
  image.rs     -- Embedded Dockerfile, image build/cache via bollard
  session.rs   -- Session persistence to ~/.tendril/sessions.json
  types.rs     -- Session, SessionBackend, ContainerType, SessionStatus types

Current limitations

• No tndrl stop command — worktrees persist until manually cleaned up; stop containers with docker stop tendril-<id>
• Claude Code auth — in container mode, you'll need to run claude login or set ANTHROPIC_API_KEY
• SSH remotes preferred — HTTPS remotes with credential helpers aren't handled yet
• No session cleanup — stopped sessions accumulate in the JSON file
• Linux containers only — container mode only supports Linux; macOS and Windows containers planned
• Branch switching in worktrees is not tracked — Tendril assumes a 1:1:1 mapping between session, worktree, and branch. If you switch branches inside a worktree (e.g. git checkout -b new-branch), session metadata becomes stale: tndrl list will show the old branch, and tndrl start --branch new-branch will fail because git only allows a branch to be checked out in one worktree at a time. Avoid switching branches inside a Tendril worktree — start a new session instead.
• Prune doesn't check for active use — tndrl prune will remove worktree directories for stopped sessions even if your shell is still in that directory or you've started new work there. Make sure you've exited the worktree before pruning.

Tech stack

• Rust (edition 2024)
• clap — CLI argument parsing
• tokio — async runtime
• dialoguer — interactive terminal prompts
• comfy-table — formatted table output
• serde/serde_json — session serialization
• chrono — timestamps
• uuid — session IDs
• dirs — home directory resolution
• bollard — Docker API client (for container mode)
• colored — terminal colors

Roadmap

• tndrl stop command with worktree cleanup
• Session descriptions and filtering
• Claude Code credential forwarding for container mode
• macOS container support via Tart (Apple Virtualization.framework)
• Windows container support
• Custom Dockerfile support per project
• Reconcile worktree branch state on list and prune (detect branch drift via git branch --show-current)
• Guard prune against active worktree usage (check for running processes before removing)
• Warn when running tndrl start from inside an existing Tendril worktree