agntree

# Agntree — AI Coding Agent Session Manager for VS Code & Cursor

[![VS Code Marketplace](https://img.shields.io/visual-studio-marketplace/v/subhashkhileri.agntree?label=VS%20Code%20Marketplace&logo=visual-studio-code&color=blue)](https://marketplace.visualstudio.com/items?itemName=subhashkhileri.agntree)
[![Installs](https://img.shields.io/visual-studio-marketplace/i/subhashkhileri.agntree?label=Installs&color=green)](https://marketplace.visualstudio.com/items?itemName=subhashkhileri.agntree)
[![Rating](https://img.shields.io/visual-studio-marketplace/r/subhashkhileri.agntree?label=Rating)](https://marketplace.visualstudio.com/items?itemName=subhashkhileri.agntree)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![GitHub stars](https://img.shields.io/github/stars/subhashkhileri/agntree?style=social)](https://github.com/subhashkhileri/agntree)

> Manage AI coding agent sessions across git repositories and worktrees.
> Supports Claude Code on VS Code & Cursor. Extensible architecture — contributions for Copilot, Cline, Aider, and more are welcome.

<!-- TODO: Add hero GIF showing full workflow demo -->
<!-- ![Agntree — Managing AI coding sessions across multiple git repositories](media/hero-demo.gif) -->

## Table of Contents

- [Why Agntree?](#why-agntree)
- [Features](#features)
- [Demo](#demo)
- [Quick Start](#quick-start)
- [Installation](#installation)
- [Agntree vs Manual Workflow](#agntree-vs-manual-workflow)
- [Supported AI Coding Agents](#supported-ai-coding-agents)
- [Usage Guide](#usage-guide)
- [Settings](#settings)
- [Commands](#commands)
- [Architecture](#architecture)
- [FAQ](#faq)
- [Roadmap](#roadmap)
- [Contributing](#contributing)
- [License](#license)

## Why Agntree?

Working with AI coding agents across multiple projects and branches is painful:

- **Context switching** between AI sessions means losing track of conversations and progress
- **Parallel development** with AI assistants requires juggling multiple terminals and session IDs
- **Multi-repo AI workflows** have no unified interface — each project is isolated
- **Session forking** to explore alternatives means manually copying session files and worktrees
- **Tracking changes** across AI-assisted branches requires constant `git diff` commands

Agntree solves all of this with a single VS Code sidebar panel.

## Features

### AI Agent Session Management

Create, resume, rename, and organize AI coding sessions. Every session links to a Claude Code session ID for seamless `--resume` support. Import existing sessions from `~/.claude/projects/` with multi-select. Search all sessions across a repository's worktrees with the repository-level Search Sessions command.

### Git Worktree Integration

Automatically detects git worktrees for each repository. Create new worktrees with one click — choose an existing branch or create a new one from any base branch. Worktrees are organized in a dedicated `<repo>-worktrees/` folder.

### Session Forking — Branch Your AI Conversations

Fork an ongoing AI session to explore alternative approaches — just like branching your code. Fork within the same worktree or create a new worktree with all uncommitted changes carried over. The full conversation history is preserved so the AI can resume from the forked point.

### PR Checkout

Check out any GitHub pull request into a new worktree with one click. Works for PRs from both same-repo branches and forks — the `gh` CLI handles remote resolution automatically. Available from the repository's inline actions or context menu.

### One-Click Quick Actions

Run Claude prompts or shell commands with a single click from the sidebar. Configure custom actions in settings — use Claude's headless mode with specific tools, or run any shell command. Play/stop controls with output displayed in a dedicated channel.

### Built-in Changes Tracking

View staged and unstaged changes for the active worktree without leaving the sidebar. Inline stage, unstage, and discard actions. Click any file to open a side-by-side diff. Section headers show file count and total additions/deletions.

## Demo

<!-- TODO: Add GIF demos -->
<!-- ![Managing AI coding sessions across multiple git repositories](media/demo-sessions.gif) -->
<!-- ![Fork AI agent conversation to new git worktree](media/demo-fork.gif) -->
<!-- ![Run AI coding prompts with one click using quick actions](media/demo-quick-actions.gif) -->

## Quick Start

1. Install [Agntree](https://marketplace.visualstudio.com/items?itemName=subhashkhileri.agntree) from the VS Code Marketplace
2. Click the Agntree icon in the Activity Bar and add a repository
3. Create a session on any worktree and start coding with AI

## Installation

### From VS Code Marketplace

Install directly from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=subhashkhileri.agntree) — search for **"Agntree"** in the Extensions panel, or click the link.

Works on both **VS Code** and **Cursor** (Cursor is a VS Code fork and supports VS Code extensions).

### From VSIX

1. Download or build the `.vsix` file
2. In VS Code, open the Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`)
3. Run `Extensions: Install from VSIX...`
4. Select the `agntree-x.x.x.vsix` file

### From Source

```bash
git clone https://github.com/subhashkhileri/agntree.git
cd agntree
npm install
npm run compile
npx @vscode/vsce package
code --install-extension agntree-*.vsix
```

### Requirements

- VS Code 1.85.0+ or Cursor
- [Claude Code CLI](https://claude.ai/code) installed and configured
- Git installed and available in PATH
- [GitHub CLI (`gh`)](https://cli.github.com/) for PR checkout feature (optional)

## Agntree vs Manual Workflow

| Task | Without Agntree | With Agntree |
|------|----------------|--------------|
| Switch AI sessions | Manually find session IDs, run `claude --resume <id>` | Click a session in the sidebar |
| Parallel branches | Juggle terminals, manually create worktrees | One-click worktree creation |
| Fork a conversation | Copy session files, create worktree, set up manually | Right-click → Fork Session |
| Track changes | Run `git diff` repeatedly | Built-in changes panel with inline diffs |
| Common prompts | Retype or search history | One-click quick actions |
| Multi-repo management | Separate windows per project | All repositories in one sidebar |

## Supported AI Coding Agents

Agntree currently supports Claude Code with full session management. The architecture is open-source and extensible — contributions to add support for other AI coding agents are welcome.

| Agent | IDE Support | Session Management | Status |
|-------|-------------|-------------------|--------|
| [Claude Code](https://claude.ai/code) | VS Code, Cursor | Full support | Available |
| [GitHub Copilot](https://github.com/features/copilot) | — | — | Contributions welcome |
| [Cline](https://github.com/cline/cline) | — | — | Contributions welcome |
| [Aider](https://aider.chat) | — | — | Contributions welcome |
| [Windsurf](https://codeium.com/windsurf) | — | — | Contributions welcome |
| [Continue.dev](https://continue.dev) | — | — | Contributions welcome |

See [CONTRIBUTING.md](CONTRIBUTING.md) for a guide on adding support for new agents.

## Usage Guide

### Getting Started

1. Click the **Agntree** icon in the Activity Bar (left sidebar)
2. Click **Add Local Repository** or **Clone from GitHub** to add your first repository
3. The extension automatically detects worktrees in the repository

### Managing Repositories

| Action | How To |
|--------|--------|
| Add Local Repository | Click the folder icon in the Workspaces panel title bar |
| Clone from GitHub | Click the cloud icon in the Workspaces panel title bar |
| Create Worktree | Hover over repository → Click `+` icon, or right-click → Create Worktree |
| Remove Repository | Hover over repository → Click `×` icon, or right-click → Remove from Extension |

**Clone from GitHub**: Enter a 

[truncated…]