🌱 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
• 🔁 Cross-Session Awareness - Optional realtime channel so parallel Claude Code sessions see each other's activity (--cross-session)

What's New in v2.10.1

Added

• Release-sync tooling (#55): scripts/sync-readme.js + scripts/check-release-sync.js keep the README "What's New", the vX.Y.Z git tag, and the published npm version 1:1. Wired into the version/postversion/prepublishOnly lifecycle so a bump auto-syncs the README and a drifted publish is refused. See RELEASING.md.
• demo/ (#56): a reproducible VHS terminal demo that drives the real cli through the parallel-sessions and cross-session-awareness flow (start ×2 → list --table → cross-session digest → /plantas:tail). Renders to mp4/gif and doubles as an end-to-end smoke test.

Notes

• No runtime or library changes. demo/ and scripts/ are outside the package files allowlist, so this release only refreshes the shipped README.md — it's a docs/tooling marker version.

• v2.10.0 — 2026-06-30
• v2.9.0 — 2026-06-30
• v2.8.1 — 2026-06-13
• v2.8.0 — 2026-05-27
• v2.6.0 — 2026-04-04
• v2.5.1 — 2026-03-13

Full history in CHANGELOG.md.

Installation

Via npm (recommended)

npm install -g @joaodotwork/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 • Cross-Session Awareness
• Troubleshooting

Commands

plantas init

Initialize Plantas in the current git repository.

Options:

• --seiva - Use .claude/ directory and install Seiva context management
• --cross-session - Install Claude Code hooks + slash commands for realtime cross-session awareness (requires --seiva)
• --force - Overwrite existing configuration

Example:

plantas init
plantas init --seiva                  # Install with Seiva context integration
plantas init --seiva --cross-session  # ...plus realtime cross-session awareness

--cross-session is fully opt-in and additive — it only installs hooks/commands under .claude/. Re-running with --force is safe and idempotent (it merges into settings.local.json without duplicating entries). See Cross-Session Awareness below.

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
• --no-commit - Don't auto-commit the sessions.json registration

Auto-commit: start commits the new sessions.json entry in the main repo as a single-file commit (it never sweeps in your other staged work). This keeps the tracked copy from drifting behind the live, shared, symlinked file. Pass --no-commit to skip.

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
• --no-commit - Don't auto-commit the sessions.json close

Auto-commit: like start, end commits the sessions.json change (the session moving to closed) in the main repo as a single-file commit, so the tracked copy stays in sync. Pass --no-commit to skip.

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
• -t, --table - Compact table output (one line per session)
• --json - Machine-readable JSON output

Examples:

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:

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

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:

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

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

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:

# 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 (JSON-aware plantas-sessions merge driver)
• ✅ 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.

Cross-Session Awareness (Optional)

Seiva's context.md/sessions.json are the git-layer coordination channel — they surface work across commits, branches, and days. --cross-session adds a complementary conversation-layer channel: a realtime view of what every parallel Claude Code session is currently prompting and touching, surfaced to the others within the hour.

plantas init --seiva --cross-session

This installs (all under .claude/):

• Two hooks — UserPromptSubmit appends each prompt to a shared cross-session.log and injects a digest of the other sessions' last-hour activity into the prompt context; Stop records which files the turn touched.
• Three slash commands that read across the whole worktree fleet:
  • /plantas:tail [N] — last N cross-session log entries (default 20)
  • /plantas:status [recent_N] — plantas sessions mapped to their Claude session IDs
  • /plantas:search <term> — grep transcripts across all worktrees + plantas-tracked closed sessions
• CROSS_SESSION.md — a design doc covering the log format, components, and the $CLAUDE_PROJECT_DIR anchoring rationale.

Hook commands are anchored via $CLAUDE_PROJECT_DIR (not relative paths), so they survive any cd inside a turn. The wiring in settings.local.json is merged additively — existing permissions and hooks are preserved — and re-running with --force is idempotent.

Requires --seiva (Claude Code reads hooks and slash commands from .claude/). Passing --cross-session alone prints a warning and skips the install. The whole feature rides on plantas start symlinking .claude/ across worktrees, so every session writes to one shared log at <repo>/.claude/cross-session.log (gitignored).

| Layer | Mechanism | Surfaced when | |---|---|---| | git-layer (Seiva) | sessions.json + context.md under union merge | Across commits, branches, days | | conversation-layer (--cross-session) | cross-session.log JSONL + prompt-context injection | Within the hour, between live sessions |

Requirements

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

Check your installation:

plantas doctor

Upgrading

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

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

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