Cluttry - Git worktree management for parallel AI-agent sessions
npm install cluttryWorktrees for coding agents. Safe by default.
CLI command: cry
``bashInstall
npm install -g cluttry
That's it. When Claude exits, cry automatically commits, creates a PR, and cleans up.
The Lifecycle
Every AI coding session follows four phases:
`
┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐
│ START │ → │ WORK │ → │ FINISH │ → │ CLEANUP │
└─────────┘ └─────────┘ └─────────┘ └─────────┘
cry spawn (agent works) cry finish (automatic)
`$3
Create an isolated worktree with secrets copied:
`bash
Shorthand (recommended)
cry feat-auth claudeExplicit
cry spawn feat-auth --new --agent claudeFull autopilot: agent exits → commit → PR → cleanup
cry feat-auth claude --autoInteractive finish menu when agent exits
cry feat-auth claude --finish-on-exit
`$3
Your AI agent works in the isolated worktree. Each worktree has:
- Its own branch
- Copy of your
.env and secret files (or injected env vars)
- Independent git stateRun multiple sessions in parallel—each in its own terminal.
$3
From inside the worktree:
`bash
cry finish
`Interactive flow:
1. Runs
preFinish hooks (tests, lint, etc.)
2. Shows session summary (branch, commits, diff stats)
3. If dirty: offers to commit (with suggested message from branch name)
4. Pushes branch and creates PR via gh CLI
5. Offers merge options (PR only, local merge, or gh merge)
6. Runs postFinish hooks
7. Offers cleanup promptNon-interactive:
`bash
cry finish -m "Add user authentication" --cleanup
`$3
Handled automatically by
cry finish, or manually:`bash
cry rm feat-auth --with-branch
`Installation
`bash
npm install -g cluttry
or
bun add -g cluttry
`Requirements: Node.js 18+ or Bun 1.0+, Git 2.5+
$3
`bash
Fish
cry completions fish > ~/.config/fish/completions/cry.fishBash
cry completions bash >> ~/.bashrcZsh
cry completions zsh > ~/.zsh/completions/_cry
`Configuration
After
cry init, edit .cry.json:`json
{
"include": [".env", ".env.*", "config/secrets.json"],
"defaultMode": "copy",
"hooks": {
"postCreate": ["npm install"],
"preFinish": ["npm test", "npm run lint"],
"postFinish": ["echo 'PR created!'"],
"preMerge": ["npm run build"]
},
"agentCommand": "claude"
}
`| Key | Description |
|-----|-------------|
|
include | Glob patterns for files to copy/inject to worktrees |
| defaultMode | copy, symlink, inject, or none |
| hooks.postCreate | Commands to run after spawn |
| hooks.preFinish | Commands to run before finish (tests, lint) |
| hooks.postFinish | Commands to run after PR creation |
| hooks.preMerge | Commands to run before merge attempts |
| agentCommand | Agent CLI command (default: claude) |
| editorCommand | Editor command (default: code) |
| injectNonEnv | For inject mode: skip or symlink non-dotenv files |
| agents | Agent presets (see below) |Machine-specific overrides go in
.cry.local.json (gitignored).$3
Configure per-agent behavior:
`json
{
"agents": {
"claude": {
"command": "claude",
"deny": [".env", ".env.*"],
"finishOnExitDefault": true
},
"cursor": {
"command": "cursor",
"args": ["."],
"finishOnExitDefault": false
}
}
}
`Built-in presets for
claude and cursor are provided. Override or add your own.Security Model
Tracked files are never copied. This is enforced, not optional.
For a file to be copied to a worktree, it must pass both checks:
1. Not tracked by git (
git ls-files returns nothing)
2. Ignored by git (listed in .gitignore)This means:
- Your
.env files copy automatically (they're gitignored)
- Your source code stays in git (tracked files can't be copied)
- Accidentally tracked secrets won't propagate$3
`bash
See exactly what will be copied
cry explain-copyPreview spawn without changes
cry spawn feat-test --new --dry-run
`$3
| Mode | Behavior |
|------|----------|
|
copy | Independent copies. Safe default. |
| symlink | Linked to original. Changes sync everywhere. |
| inject | No files copied. Env vars injected into commands. Safest for AI agents. |
| none | Nothing copied. Set up secrets manually. |Inject mode is recommended when running AI agents:
- Parses
.env files and injects variables into hooks and agent commands
- No secret files exist in the worktree for the agent to read
- Non-dotenv files are skipped (or optionally symlinked via injectNonEnv: "symlink")Commands
$3
| Command | Purpose |
|---------|---------|
|
cry spawn | Create worktree |
| cry finish | Commit → PR → cleanup |
| cry rm | Remove worktree |$3
| Command | Purpose |
|---------|---------|
|
cry list | List all worktrees |
| cry open | Open in agent/editor |
| cry resume | Resume session |$3
| Command | Purpose |
|---------|---------|
|
cry gc | Clean stale sessions |
| cry prune | Clean git worktree refs |
| cry doctor | Check configuration |Key Flags
$3
`
-n, --new Create new branch
-a, --agent Launch agent (claude, cursor, or custom preset)
--finish-on-exit Show finish menu when agent exits
--auto Autopilot: auto-commit, PR, cleanup when agent exits
--auto-merge With --auto: also merge PR via gh
--auto-commit-message With --auto: custom commit message
--base-branch PR target branch
-m, --mode Secret handling (copy, symlink, inject, none)
-r, --run Run command after spawn
--dry-run Preview without creating
`$3
`
-m, --message Commit with message (non-interactive)
--skip-hooks Skip all hooks (preFinish, postFinish, preMerge)
--merge Merge locally into base branch after PR
--pr-merge Merge PR via GitHub (gh pr merge)
--no-merge Skip merge prompt (PR only)
--cleanup Auto-cleanup after PR
--skip-commit Skip commit step
--non-interactive Never prompt
--dry-run Preview without executing
`$3
`
-b, --with-branch Also delete the branch
-f, --force Force remove dirty worktree
-y, --yes Skip confirmation
`FAQ
$3
| Task | git worktree | cry |
|------|--------------|-----|
| Create worktree |
git worktree add -b feat ../feat | cry feat |
| Copy secrets | Manual copy | Automatic |
| Run setup | cd ../feat && npm install | --run "npm install" |
| Launch agent | cd ../feat && claude | --agent claude |
| Create PR | Switch context, push, open browser | cry finish |
| Cleanup | git worktree remove, git branch -d | cry rm --with-branch |cry handles the lifecycle. git worktree is just step 1.
$3
Yes. Skip
--agent and use worktrees for any parallel work:`bash
cry hotfix-123
... work manually ...
cry finish
`$3
cry finish prints manual PR instructions and exits cleanly (exit 0). Install gh for automatic PR creation:`bash
brew install gh && gh auth login
`$3
Best option: Use inject mode (no files copied to worktree):
`bash
cry spawn feat-auth --new --agent claude --mode inject
`Or configure it as default in
.cry.json:
`json
{ "defaultMode": "inject" }
`For Claude Code specifically, you can also add to
.clauderc:
`json
{ "deny": [".env", ".env.*"] }
`$3
Default is
.worktrees/ in your repo. Override:`bash
Per-spawn
cry spawn feat --path ~/worktrees/myrepo-featGlobally in .cry.local.json
{ "worktreeBaseDir": "/home/user/worktrees" }
`Troubleshooting
$3
Run cry from inside a git repo.
$3
The worktree path exists. Remove it or use
--path:`bash
rm -rf .worktrees/feat-auth
or
cry spawn feat-auth --path .worktrees/feat-auth-v2
`$3
Remove the existing worktree first:
`bash
cry rm feat-auth
`$3
Files in
include must be gitignored and untracked:`bash
Add to .gitignore
echo "secrets.json" >> .gitignoreIf already tracked, untrack it
git rm --cached secrets.json
`$3
Commit or discard changes before removing:
`bash
cry rm feat-auth --force # discards changes
`$3
Install the agent CLI:
`bash
Claude
npm install -g @anthropic-ai/claude-codeOr set custom command
echo '{"agentCommand": "your-agent"}' > .cry.local.json
`$3
Check GitHub CLI auth:
`bash
gh auth status
gh auth login # if needed
`Development
`bash
npm install
npm run build
npm test
``MIT