🌱 Plantas CLI

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.5.0 🚀

• plantas sync: Auto-stashes coordination files before git pull in the main worktree — no more merge blocks from hook-updated files.
• plantas merge: Handles symlinked .claude/ in session worktrees so git merge works cleanly.
• Multiple Issues: Associate sessions with multiple GitHub issues via --issue 31 --issue 32.
• List Filtering: Use plantas list --active, --closed, or --recent 5 to filter session output.
• Auto Symlink: Share .env, .gemini, and other persistent files automatically via .plantas.config.json.
• Multi-Agent Support: AI_GUIDE.md with instructions for Claude, Gemini, and more.

Installation

Via npm (recommended)

npm install -g plantas-cli

Manual installation

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

Quick Start

1. Initialize Plantas in your project:

cd your-project
plantas init

2. Start your first session:

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:

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

4. List active sessions:

plantas list

5. End the session when done:

plantas end A

This automatically removes the worktree and archives the session.

Documentation

📚 Complete Guides:

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

Quick Links:

• Installation • Commands • Configuration
• Use Cases • Seiva Integration
• 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:

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:

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

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

Examples:

plantas list
plantas list --active
plantas list --recent 5

plantas status

Show current Plantas status and configuration.

Example:

plantas status

plantas doctor

Check installation and dependencies.

Example:

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:

# 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/context.md, .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:

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

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

{
  "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:

{
  "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:

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

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

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

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):

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

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:

• Shared context via .claude/context.md - Project state, tech stack, patterns
• AI coordination - All sessions read the same context (2k tokens vs 30-50k)
• Git hooks - Automatic context updates on commit
• Intelligent analysis - Auto-populates context.md from project files and git history
• Token efficiency - 94% reduction in AI context loading costs

To install with Seiva:

plantas init --seiva

This:

• Uses .claude/ directory for compatibility
• Installs context.md template and git hooks
• Installs intelligent analyzer (seiva-analyze.js)
• Enables AI-assisted parallel development

Intelligent Context Population (v1.8.0+)

The Seiva analyzer automatically populates context.md sections by analyzing your project:

| Section | Source | |---------|--------| | Tech Stack | package.json, requirements.txt, go.mod, Cargo.toml, Gemfile | | Key Files | Files modified 2+ times in recent commits | | What's Being Built | Conventional commit messages (feat/fix/refactor) | | Active Patterns | File change patterns (tests, CI/CD, migrations, API) |

Example auto-generated sections:

## Tech Stack
- **Runtime:** Node.js
- **Framework:** Express 4.18.0, React 18.2.0
- **Database:** PostgreSQL
- **Testing:** Jest

## Key Files to Know
- `src/index.ts` - Entry point (modified 5x recently)
- `src/api/routes.ts` - Routes/Controllers (modified 3x recently)

## What's Being Built
- **Features in progress:** User authentication (+2 more)
- **Bug fixes:** Fix payment validation

Safe by design:

• Only updates placeholder sections (won't overwrite your custom content)
• Runs on every commit and during plantas rebuild
• Fails silently - never breaks your commits

Git Workflow & Merge Strategy (v2.0.0+)

Important: Seiva files are committed to git and use union merge strategy:

.claude/context.md merge=union
.claude/sessions.json merge=union

How it works:

• Each session commits updates to context.md and sessions.json
• When merging branches, git combines ALL changes (no conflicts)
• All sessions contribute additively - no work is lost
• This enables true cross-session coordination

What's committed:

• ✅ context.md - Shared context (union merge)
• ✅ sessions.json - Session tracking (union merge)
• ✅ AI_GUIDE.md - Workflow documentation for AI agents (Claude, Gemini, etc.)
• ✅ seiva-analyze.js - Analyzer tool
• ✅ .plantas.config.json - Team configuration
• ❌ 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:

plantas doctor

Upgrade to v2.0.0 🚀

v2.0.0 fixes the fundamental git workflow flaw that caused data corruption!

| Version | Issue | Status | |---------|-------|--------| | v2.0.0 | Union merge workflow - fixes data corruption | ✅ Latest | | v1.x | Data corruption during git operations | ⚠️ Deprecated | | v1.2.1 | Post-commit hook infinite loop | ❌ Critical bug | | v1.2.0 | --force wipes sessions.json | ❌ Critical bug |

To upgrade:

npm install -g @joaodotwork/plantas-cli@latest
cd your-project
plantas init --seiva --force
git add .gitignore .gitattributes .claude/ .plantas.config.json
git commit -m "chore: Migrate to Plantas 2.0"

See MIGRATION.md for detailed upgrade instructions and recovery steps.

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/context.md, .claude/sessions.json) have uncommitted changes from hooks. Use plantas sync instead of git pull:

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:

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:

git init

"Neither jq nor python3 found"

Install jq (recommended):

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

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

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
• Issue Tracker

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