cluttry

Worktrees for coding agents. Safe by default.

CLI command: cry

60-Second Quickstart

``bash


Install

npm install -g cluttry

Initialize in your repo

cd your-repo
cry init

One command: create worktree → launch Claude → auto-finish when done

cry feat-login claude --auto
`

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 claude

Explicit

cry spawn feat-auth --new --agent claude

Full autopilot: agent exits → commit → PR → cleanup

cry feat-auth claude --auto

Interactive 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 state

Run 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 prompt

Non-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.fish

Bash

cry completions bash >> ~/.bashrc

Zsh

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-copy

Preview 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-feat

Globally 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" >> .gitignore

If 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-code

Or 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
``

License

MIT