forktree helps coding agents and automation create, manage, and clean up Git worktrees with safety checks and predictable shell output.
Install & Download
1. ClawHub CLI
The fastest way to install a skill directly from the registry.
npx clawhub@latest install forktree
2. Manual Installation
Copy the skill folder to one of these locations
~/.openclaw/skills/ <project>/skills/ Priority: Workspace > Local > Bundled
3. Prompt Installation
Copy this prompt to OpenClaw to install it automatically.
Help me install forktree using Clawhub. If Clawhub is not installed, install it first (npm i -g clawhub).
Prefer to download?
Get the raw skill files in a ZIP archive.
What is forktree?
forktree is a stdlib-only Python 3.11+ CLI that wraps Git worktree operations for shell pipelines, CI jobs, and unattended coding agents. Its create command runs seven safety pre-flights before adding a worktree, while other commands support listing, removal, garbage collection, configuration initialization, and diagnostics.
For Openclaw Skills users, the key benefit is automation-friendly behavior: data goes to stdout, diagnostics go to stderr, and defined exit codes let scripts respond reliably to success, safety refusals, Git failures, and strict configuration errors. The tool has no third-party Python dependencies.
forktree Use Cases
- Create an isolated worktree for an agent task after safety pre-flights pass.
- Capture a new worktree's absolute path in a shell variable without mixing in progress messages.
- List project worktrees as JSON or header-free TSV for scripts and downstream tools.
- Remove a specific worktree or identify stale worktrees for age- and merge-aware cleanup.
- Check installation and environment diagnostics with
forktree doctor. - Apply consistent project or user-level TOML configuration in local development and CI.
How forktree Works
- Resolve settings from CLI flags, project
.forktree.toml,~/.config/forktree/config.toml, then built-in defaults. - For
create, run seven safety pre-flights before asking Git to create the worktree; a refused operation exits non-zero and does not create it. - Send machine-readable results to stdout, such as the new absolute path, JSON or TSV worktree listings, or sorted garbage-collection candidates.
- Send warnings, errors, verbose progress, and
doctordiagnostics to stderr; format errors asforktree: <subcommand>: <one-line reason>. - Return an exit code that scripts can use to distinguish success, pre-flight refusal, Git/setup/usage failure, and strict configuration errors.
- Use
removefor a specific worktree, orgcto evaluate stale worktrees by idle age and merge status; preview cleanup withgc --dry-run.
forktree Setup
Install the forktree CLI using the project's documented installation method, then ensure the forktree executable is on PATH and the package is importable with Python 3.11 or later. This skill file does not specify an installation command or package-manager procedure.
Verify the installation:
command -v forktree
python3 -c "import forktree"
forktree --help
forktree doctor
Create a project configuration containing the effective resolved settings:
forktree init
Configuration is resolved in this order: CLI flags, project .forktree.toml, user ~/.config/forktree/config.toml, and built-in defaults. Set FORKTREE_STRICT=1 to enable strict configuration handling for every subcommand, or use NO_COLOR=1 to disable ANSI color in human output. Under strict mode, malformed TOML exits with code 3.
Example agent-safe invocation:
wt=$(forktree create "$project_path" "$slug" 2>/tmp/forktree.err) || {
cat /tmp/forktree.err
exit 1
}
cd "$wt"
Check the exit status and read stderr before proceeding: a failed create means no worktree was created. Use forktree <subcommand> --help for command-specific flags.
forktree Data Schema & Taxonomy
forktree uses TOML for configuration and keeps command output suitable for shell automation.
| Data or output | Format and behavior |
|---|---|
| Project configuration | .forktree.toml in the project directory |
| User configuration | ~/.config/forktree/config.toml |
| Configuration precedence | CLI flags > project config > user config > built-in defaults |
create stdout |
One line containing the new worktree's absolute path |
list --porcelain stdout |
One header-free TSV line per worktree |
list --json stdout |
JSON array of objects; compact in a pipe and pretty-printed in a TTY |
gc --dry-run stdout |
Sorted worktree slugs, one per line |
| Diagnostics | Warnings, errors, verbose progress, and doctor report on stderr |
The skill file does not enumerate the full TOML schema; consult the project README for supported configuration fields. Errors use the format forktree: <subcommand>: <one-line reason>. Exit codes are 0 for success, 1 for a pre-flight refusal, 2 for a Git operation, setup hook, or usage failure, and 3 for a strict configuration error.
forktree Advanced Features
- Seven safety pre-flights protect worktree creation and make a non-zero
createresult an explicit signal not to proceed. - Pipeline-safe stdout/stderr separation supports command substitution and tools such as
jqwithout diagnostic text contaminating data. listsupports both machine-readable JSON and porcelain TSV output.gcevaluates stale worktrees by idle age and merge status;gc --dry-runpreviews sorted cleanup candidates before action.- TOML configuration supports CLI, project, and user-level settings, with optional strict error handling through
--strictorFORKTREE_STRICT=1. - The optional
[worktree].setup_scripthook runs during worktree setup; it is opt-in, and a non-zero hook exit removes the worktree. doctorprovides diagnostics and always exits with code0; review its stderr output for findings.- The CLI requires Python 3.11+ and uses only the standard library, with no third-party dependencies.
SKILL.md
Loading
Related Openclaw Skills
Medical Device Registration Dossier Assistant
A regulatory writing assistant that organizes medical device evidence into market-specific, submission-ready registration dossiers.
Cue Equity Incentive Research
A Cue-powered research skill for querying, comparing, and analyzing publicly disclosed A-share equity incentive plans and share buybacks.
Market & Customer Insight
A structured market and customer insight workflow that combines ST, APPEALS, and KANO analysis to identify high-value segments, unmet needs, and blue-ocean opportunities.
Xiaoyunque Short Drama Creator
An Openclaw Skills workflow for submitting, monitoring, and downloading AI-generated short drama projects through Pippit Tool CLI.
Marketing Engineer
Marketing Engineer turns marketing operations into an evidence-based, auditable workflow with structured workspaces, content tickets, GEO/SEO playbooks, and a live dashboard.
Learning5D Agent Safety Check and Enrolment
Learning5D helps agents assess safety risks, review skills before installation, and optionally study consent-first relational safety.
Featured*
