tndrl 0.2.0

Parallel AI dev sessions via git worktrees
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133

# 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.

## 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`)

## 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

```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
```

### List active sessions

```bash
tndrl list
```

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

```
+----------+---------+----------------+----------------------------------+------------------------+
| ID       | Status  | Branch         | 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|
+----------+---------+----------------+----------------------------------+------------------------+
```

### Watch mode

```bash
tndrl list --watch
```

Continuously monitors session state and updates the table in real time.

### Prune stopped sessions

```bash
tndrl prune
```

Removes stopped and failed sessions, cleaning up their worktree directories.

## How it works

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 overhead
- Tracks session state in `~/.tendril/sessions.json`

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

### Session tracking

Session metadata is persisted to `~/.tendril/sessions.json`. The `list` command reads this file and reconciles with the actual state by checking worktree directory existence.

## Project structure

```
src/
  main.rs      -- CLI parsing, start/list/prune command orchestration
  worktree.rs  -- Git worktree creation, branch detection, repo URL, Claude launch
  session.rs   -- Session persistence to ~/.tendril/sessions.json
  types.rs     -- Session, SessionStatus types
```

## Current limitations

- **No `tndrl stop` command** — worktrees persist until manually cleaned up
- **SSH remotes preferred** — HTTPS remotes with credential helpers aren't handled yet
- **No session cleanup** — stopped sessions accumulate in the JSON file until pruned
- **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
- **colored** — terminal colors

## Roadmap

- `tndrl stop` command with worktree cleanup
- Session descriptions and filtering
- 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