npm package: @joaodotwork/plantas-cli
Description: 🌱 Plantas - Session management for parallel development with git worktrees and AI assistants
Author: joao.work
Latest version: 2.7.2

# 🌱 Plantas CLI

[![npm version](https://img.shields.io/npm/v/@joaodotwork/plantas-cli)](https://www.npmjs.com/package/@joaodotwork/plantas-cli)
[![license](https://img.shields.io/npm/l/@joaodotwork/plantas-cli)](./LICENSE)
[![node](https://img.shields.io/node/v/@joaodotwork/plantas-cli)](./package.json)

**Session management for parallel development with git worktrees**

Plantas is a powerful CLI tool that enables parallel development workflows using git worktrees. It helps developers manage multiple concurrent work sessions without the overhead of branch switching or stashing.

## Features

- 🌿 **Parallel Sessions** - Work on multiple features simultaneously using git worktrees
- 🌳 **Session Tracking** - Keep track of active and closed sessions with metadata
- 🐙 **GitHub Integration** - Associate sessions with GitHub issues for better traceability
- 🔗 **Automated Symlinking** - Automatically share persistent config files (like `.env`, `.gemini`) across sessions
- 🌱 **Zero Conflicts** - Each session has its own directory and branch; config files use union merge
- 🍃 **Easy Cleanup** - Automatic worktree management and cleanup
- 🔒 **Safety Features** - Confirmation prompts and --force flag to prevent accidents
- 🔄 **Auto Recovery** - Rebuild sessions.json from git history if corrupted
- 📅 **ISO 8601 Timestamps** - Git-native timestamp format with timezone support
- 🌊 **Seiva Compatible** - Optional integration with Seiva context management for AI coordination

## What's New in v2.7.0

- **`plantas list --table`**: Compact one-line-per-session table output. `--json` for machine-readable output.
- **Compact sessions.json**: No more pretty-printing — smaller diffs, fewer merge conflicts.
- **Worktree git exclude**: `plantas start` now excludes the config dir symlink from git tracking, preventing noise in PR diffs.
- **`plantas context`** (v2.6.0): Auto-generates `.claude/context.md` from repo state. Compressed AI format by default, `--human` for markdown.

## Installation

### Via npm (recommended)

```bash
npm install -g @joaodotwork/plantas-cli
```

### Manual installation

```bash
git clone https://github.com/joaodotwork/plantas-cli
cd plantas-cli
npm install
npm link
```

## Quick Start

1. **Initialize Plantas in your project:**

```bash
cd your-project
plantas init
```

2. **Start your first session:**

```bash
plantas start A "Admin UI improvements" feat/admin "components/Admin*"
```

This creates:
- A new git worktree at `../your-project-session-A/`
- A session entry in `.plantas/sessions.json`
- A new branch `feat/admin` (or checks out existing)

3. **Navigate to the session:**

```bash
cd ../your-project-session-A/
# Open your editor and start working
```

4. **List active sessions:**

```bash
plantas list
```

5. **End the session when done:**

```bash
plantas end A
```

This automatically removes the worktree and archives the session.

## Documentation

📚 **Complete Guides:**

- **[CHANGELOG.md](./CHANGELOG.md)** - Version history and release notes
- **[MIGRATION.md](./MIGRATION.md)** - Upgrade guide and troubleshooting
- **[ARCHITECTURE.md](./docs/ARCHITECTURE.md)** - Complete system architecture and design
- **Seiva** - Context management system for AI coordination (optional integration)

**Quick Links:**
- [Installation](#installation) • [Commands](#commands) • [Configuration](#configuration)
- [Use Cases](#use-cases) • [Seiva Integration](#seiva-integration-optional)
- [Troubleshooting](#troubleshooting)

## Commands

### `plantas init`

Initialize Plantas in the current git repository.

**Options:**
- `--seiva` - Use `.claude/` directory and install Seiva context management
- `--force` - Overwrite existing configuration

**Example:**
```bash
plantas init
plantas init --seiva  # Install with Seiva context integration
```

### `plantas start <id> <focus> [branch] [areas] [--issue <number>]`

Start a new parallel session with automatic worktree creation.

**Arguments:**
- `id` - Short identifier (e.g., A, B, feature-name)
- `focus` - Description of what you're working on
- `branch` - Git branch name (optional, defaults to current)
- `areas` - Comma-separated file patterns (optional)

**Options:**
- `-i, --issue <number>` - Associate with GitHub issue number

**Examples:**
```bash
# Basic usage - creates new branch or uses current
plantas start A "Bug fixes"

# Associate with GitHub issue
plantas start auth "Implement user authentication" --issue 123

# Attach to existing branch (automatically detected)
plantas start B "Continue feature work" feat/existing-feature

# Create new branch if it doesn't exist
plantas start C "New feature" feat/new-feature

# With file areas
plantas start D "API refactor" feat/api "src/api/*,tests/api/*"
```

**Note:** Plantas automatically detects whether the branch exists:
- ✅ If branch exists: checks it out in the worktree
- ✅ If branch doesn't exist: creates it for you

### `plantas end <id>`

End a session and cleanup its worktree.

**Options:**
- `-f, --force` - Skip confirmation prompts

**Examples:**
```bash
plantas end A              # Prompts for confirmation
plantas end A --force      # Skips confirmation (for scripts)
```

**Safety Features:**
- ⚠️ Prompts before deleting worktree
- ⚠️ Warns if uncommitted changes exist
- ⚠️ Shows what will be deleted
- ✅ Use `--force` to skip prompts for automation

### `plantas list`

List all active and recently closed sessions.

**Alias:** `plantas ls`

**Options:**
- `-a, --active` - Show only active sessions
- `-c, --closed` - Show only closed sessions
- `--all` - Show both active and closed sessions (default)
- `-r, --recent <n>` - Show active + last N closed sessions
- `-t, --table` - Compact table output (one line per session)
- `--json` - Machine-readable JSON output

**Examples:**
```bash
plantas list
plantas list --active
plantas list --recent 5
plantas list --table      # compact table view
plantas list --json       # parseable JSON
```

### `plantas status`

Show current Plantas status and configuration.

**Example:**
```bash
plantas status
```

### `plantas doctor`

Check installation and dependencies.

**Example:**
```bash
plantas doctor
```

### `plantas sync`

Pull latest changes into the main worktree, auto-stashing coordination files that would otherwise block the pull.

**Options:**
- `-r, --remote <remote>` - Remote name (default: `origin`)
- `-b, --branch <branch>` - Branch to pull (default: current branch)
- `-f, --force` - Run even from a worktree

**Example:**
```bash
# After merging a session PR on GitHub, pull into main cleanly:
plantas sync

# Pull from a specific remote/branch:
plantas sync --remote upstream --branch main
```

**Why this exists:** After merging a session PR, coordination files (`.claude/sessions.json`) often have uncommitted local changes from hooks. `git pull` aborts before the union merge strategy kicks in. `plantas sync` stashes those files first, pulls with `--no-rebase`, then pops the stash.

### `plantas merge [branch]`

Merge a branch into the current worktree, handling symlinked config directories that cause `git merge` to fail.

**Arguments:**
- `branch` - Branch to merge (default: `origin/main`)

**Examples:**
```bash
# In a session worktree, merge latest main:
plantas merge

# Merge a specific branch:
plantas merge origin/main
plantas merge feat/other-feature
```

**Why this exists:** Session worktrees have a symlinked `.claude/` (or `.plantas/`) directory. `git merge` fails because git can't stash paths beyond a symlink. `plantas merge` temporarily removes the symlink, restores real tracked files, runs the merge, then re-creates the symlink.

### `plantas context`

Generate `.claude/context.md` from project state. Derives tech stack, key files, work streams, and recent activity automatically.

**Options:**
- `--human` - Output human-readable markdown (default: compressed AI format)
- `--refresh` - Also regenerate context in all active worktrees
- `--quiet` - Suppress output (for hooks)

**Examples:**
```bash
plantas context              # Compressed AI format
plantas context --human      # Human-readable markdown
plantas context --refresh    # Update all worktrees too
```

**What it derives:**

| Data | Source |
|------|--------|
| Tech stack | `package.json`, `requirements.txt`, `go.mod`, `Cargo.toml`, `Gemfile` |
| Key files | Files modified 2+ times in recent commits |
| Work streams | Conventional commit messages (feat/fix/refactor/docs) |
| Active patterns | File change patterns (tests, CI/CD, migrations, API) |
| Sessions | `.claude/sessions.json` |
| Recent activity | Last 5 commits |

### `plantas rebuild`

Rebuild sessions.json from git worktrees and branch history. Useful for recovery from file corruption or migration scenarios.

**Options:**
- `--dry-run` - Show what would be rebuilt without writing
- `--force` - Overwrite existing sessions.json with active sessions
- `--active-only` - Only rebuild active sessions from worktrees

**Examples:**
```bash
# Basic rebuild - scans worktrees and branches
plantas rebuild

# Preview what would be rebuilt
plantas rebuild --dry-run

# Force overwrite existing file
plantas rebuild --force

# Only active sessions (faster)
plantas rebuild --active-only
```

**What Gets Reconstructed:**
- ✅ Session IDs from worktree paths
- ✅ Branch names
- ✅ Worktree paths (for active sessions)
- ✅ Creation timestamps from git branch metadata
- ✅ Focus descriptions from commit messages
- ℹ️ Areas default to "general"

**Use Cases:**
- 🔧 Recover from corrupted sessions.json
- 🔧 Accidentally deleted sessions.json
- 🔧 Migrate from manual git worktree workflow
- 🔧 Verify sessions.json integrity
- 🔧 Onboard existing project to Plantas

## Configuration

Plantas can be configured via `.plantas.config.json`:

```json
{
  "configDir": ".claude",
  "sessionsFile": ".claude/sessions.json",
  "worktreePrefix": "session-",
  "timestampFormat": "HH:mm",
  "defaultAreas": "general",
  "sessions": {
    "autoSymlink": [".env", ".gemini", ".gemini-clipboard"]
  },
  "hooks": {
    "onStart": null,
    "onEnd": null
  }
}
```

### Configuration Options

| Field | Description | Default |
|-------|-------------|---------|
| `configDir` | Directory for Plantas/Seiva files | `.plantas` |
| `sessionsFile` | Path to the sessions registry | `configDir/sessions.json` |
| `worktreePrefix` | Prefix for worktree directories | `session-` |
| `sessions.autoSymlink` | Files to automatically symlink into worktrees | `[]` |
| `hooks.onStart` | Shell command to run after starting a session | `null` |
| `hooks.onEnd` | Shell command to run after ending a session | `null` |

### Environment Variables

You can also override configuration via environment variables:

- `PLANTAS_CONFIG_DIR` - Config directory (default: `.plantas`)
- `PLANTAS_SESSIONS_FILE` - Sessions file path
- `PLANTAS_WORKTREE_PREFIX` - Worktree directory prefix

### Hooks

Plantas supports custom hooks for automation:

#### `onEnd` Hook

Runs automatically after ending a session. Perfect for syncing your main branch after merging PRs:

```json
{
  "hooks": {
    "onEnd": "git checkout main && git pull && echo '✅ Main branch synced'"
  }
}
```

Common use cases:
- **Sync main after PR merge**: `"git checkout main && git pull"`
- **Clean up feature branches**: `"git checkout main && git pull && git branch -d $BRANCH"`
- **Run cleanup scripts**: `"./scripts/cleanup.sh"`

**Example workflow:**
```bash
# Work on feature
plantas start A "Add login" feat/login

# Make changes, commit, push, merge PR on GitHub

# End session - hook automatically syncs main
plantas end A
# → Removes worktree
# → Switches to main
# → Pulls latest changes
# → ✅ Your local main is now up-to-date!
```

## Use Cases

### Parallel Feature Development

Work on multiple features simultaneously without branch switching:

```bash
# Start feature A
plantas start checkout "Checkout flow" feat/checkout "components/Checkout*"

# Start feature B (in a new terminal)
plantas start admin "Admin dashboard" feat/admin "components/Admin*"
```

Both sessions run in parallel with isolated worktrees.

### Hotfix During Feature Work

Need to fix a critical bug while working on a large feature?

```bash
# Already working on feature
plantas start hotfix "Fix payment bug" hotfix/payment "src/api/payment.ts"

# Fix the bug, commit, merge
# Then end the session
plantas end hotfix
```

### Code Review While Building

Review PRs without disrupting your current work:

```bash
plantas start review "Review PR #42" pr-42-review
# Review, test, comment
plantas end review
```

### Resume Work on Existing Branches

Attach sessions to branches that already exist (no need to recreate them):

```bash
# List your branches
git branch
# feat/authentication
# feat/checkout
# main

# Attach session to existing branch
plantas start auth "Continue auth work" feat/authentication

# The branch already has commits - no problem!
# Plantas creates a worktree and you continue where you left off
```

This is perfect for:
- Returning to paused work
- Collaborating on shared branches
- Working on long-running features across multiple sessions

### Experimentation

Try different approaches in parallel:

```bash
plantas start modal "Modal UI approach" experiment/modal
plantas start inline "Inline editing approach" experiment/inline

# Compare both, keep the best one
```

## Seiva Integration (Optional)

Plantas can optionally integrate with **Seiva** - a context management system that helps AI assistants understand your project state.

When used with Seiva:

- **Auto-generated context** via `plantas context` — derives everything from repo state
- **Token-efficient** — compressed format uses ~500 tokens vs ~2k for markdown
- **Zero merge conflicts** — `context.md` is gitignored, generated locally per worktree
- **Post-commit hook** — context regenerates automatically after each commit
- **Multi-ecosystem** — analyzes Node.js, Python, Go, Rust, and Ruby projects

To install with Seiva:

```bash
plantas init --seiva
```

This:
- Uses `.claude/` directory for compatibility
- Generates initial `context.md` from project analysis
- Installs post-commit hook for automatic regeneration
- Creates `AI_GUIDE.md` for multi-agent workflows

### How Context Generation Works (v2.6.0+)

Context is **fully derived** — no manual maintenance:

```bash
# Auto-runs after every commit via post-commit hook
# Or run manually:
plantas context              # compressed AI format
plantas context --human      # human-readable markdown
plantas context --refresh    # update all active worktrees
```

Each worktree generates its own `context.md` independently. The repo is the source of truth; `context.md` is just a cache for AI consumption.

**What's committed:**
- ✅ `sessions.json` - Session tracking (union merge)
- ✅ `AI_GUIDE.md` - Workflow documentation for AI agents
- ✅ `.plantas.config.json` - Team configuration
- ❌ `context.md` - Auto-generated, gitignored
- ❌ `settings.local.json` - Local Claude Code permissions
- ❌ `*.sh` - Generated scripts

**Without Seiva**, Plantas works standalone — you get session management and worktrees, but no automatic AI context sharing.

## Requirements

- Git (required)
- Node.js 14+ (required)
- jq or python3 (for JSON processing)
- Bash (for shell scripts)

Check your installation:

```bash
plantas doctor
```

## Upgrading

```bash
npm install -g @joaodotwork/plantas-cli@latest
cd your-project
plantas init --seiva --force
```

See [MIGRATION.md](./MIGRATION.md) for detailed upgrade instructions from v1.x.

## How It Works

Plantas uses **git worktrees** to create isolated working directories:

```
your-project/                    (main repo)
├── .plantas/
│   ├── sessions.json            (session registry)
│   ├── start-session.sh
│   ├── end-session.sh
│   └── list-sessions.sh
└── src/

../your-project-session-A/       (worktree for session A)
├── .plantas -> ../your-project/.plantas/  (symlink)
└── src/

../your-project-session-B/       (worktree for session B)
├── .plantas -> ../your-project/.plantas/  (symlink)
└── src/
```

Benefits:
- ✅ No branch switching overhead
- ✅ Run multiple dev servers simultaneously
- ✅ Isolated dependencies (node_modules, venv)
- ✅ Clean separation of concerns
- ✅ Easy cleanup

## Troubleshooting

### "Your local changes would be overwritten by merge" on pull

This happens when coordination files (`.claude/sessions.json`) have uncommitted changes from hooks. Use `plantas sync` instead of `git pull`:

```bash
plantas sync
```

### "is beyond a symbolic link" on merge in worktree

This happens because session worktrees have a symlinked `.claude/` directory and git can't stash paths beyond symlinks. Use `plantas merge` instead of `git merge`:

```bash
plantas merge              # merges origin/main
plantas merge feat/branch  # merge any branch
```

### "Not a git repository" error

Make sure you're in a git repository:

```bash
git init
```

### "Neither jq nor python3 found"

Install jq (recommended):

```bash
# macOS
brew install jq

# Ubuntu/Debian
sudo apt-get install jq

# Or use python3 as fallback
```

### Worktree already exists

If a worktree path already exists:

```bash
# Remove it manually
rm -rf ../your-project-session-A/

# Or use git worktree
git worktree remove ../your-project-session-A/
```

### Uncommitted changes warning

Before ending a session, commit or stash your changes:

```bash
cd ../your-project-session-A/
git add .
git commit -m "Save work"
# Then end the session
```

## Contributing

Contributions welcome! See the main repository for guidelines.

## License

MIT License - see LICENSE file for details.

## Links

- [GitHub Repository](https://github.com/joaodotwork/plantas-cli)
- [Issue Tracker](https://github.com/joaodotwork/plantas-cli/issues)

## Etymology

**Plantas** (Spanish/Portuguese) means:
1. 🌱 Plants - organisms that grow from roots
2. 📋 Plans - organized schemes or methods
3. 👣 Soles (of feet) - foundation for navigation

All three meanings apply to parallel session management!

---

Made with 🌱 by [joaodotwork](https://github.com/joaodotwork)