# 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](https://www.docker.com/products/docker-desktop/)
- [OrbStack](https://orbstack.dev/) (recommended, lighter weight)
- [Colima](https://github.com/abiosoft/colima)
## Install
```bash
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)
```bash
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:
```bash
tndrl start --branch feature/my-task
```
### Start a container session (optional)
```bash
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](#container-mode) below for details.
### List active sessions
```bash
tndrl list
```
Displays a table of all sessions with their status, branch/container info, repository, and start time.
```
+----------+---------+--------------------+----------------------------------+------------------------+
| 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:
```bash
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](https://tart.run/) (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