Agent skill

Worktree

Create an isolated git worktree + branch + port for this session so concurrent kube-coder sessions and builds don't conflict.

MITAuto-check: notesDevelopment

Install Worktree

skills CLI

$ npx skills add imran31415/kube-coder --skill worktree -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI

$ gh skill install imran31415/kube-coder worktree --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy

$ git clone --depth 1 https://github.com/imran31415/kube-coder.git skills-src && mkdir -p .claude/skills && cp -r skills-src/.claude/skills/worktree .claude/skills/worktree && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Paste into Claude Code

Install the "worktree" agent skill from https://github.com/imran31415/kube-coder/tree/main/.claude/skills/worktree into .claude/skills/worktree/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "worktree", then confirm the skill loads.

Claude Code copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

$skill-installer

$skill-installer install https://github.com/imran31415/kube-coder/tree/main/.claude/skills/worktree

Type this inside Codex. $skill-installer <name> installs a curated skill from openai/skills. The installer writes to $CODEX_HOME/skills (default ~/.codex/skills). Restart Codex if the skill does not show up.

skills CLI

$ npx skills add imran31415/kube-coder --skill worktree -a codex

Project install goes to .agents/skills/; add -g for ~/.codex/skills/.

GitHub CLI

$ gh skill install imran31415/kube-coder worktree --agent codex

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/imran31415/kube-coder.git skills-src && mkdir -p .agents/skills && cp -r skills-src/.claude/skills/worktree .agents/skills/worktree && rm -rf skills-src

Use ~/.agents/skills/ instead of .agents/skills for a personal install.

Codex skills documentation · loads skills from .agents/skills/

Paste into Codex

Install the "worktree" agent skill from https://github.com/imran31415/kube-coder/tree/main/.claude/skills/worktree into .agents/skills/worktree/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "worktree", then confirm the skill loads.

Codex copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add imran31415/kube-coder --skill worktree -a cursor

Project install goes to .agents/skills/; add -g for ~/.cursor/skills/.

GitHub CLI

$ gh skill install imran31415/kube-coder worktree --agent cursor

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/imran31415/kube-coder.git skills-src && mkdir -p .cursor/skills && cp -r skills-src/.claude/skills/worktree .cursor/skills/worktree && rm -rf skills-src

Use ~/.cursor/skills/ instead of .cursor/skills for a personal install.

Cursor skills documentation · loads skills from .cursor/skills/, .agents/skills/, .claude/skills/, .codex/skills/

Paste into Cursor

Install the "worktree" agent skill from https://github.com/imran31415/kube-coder/tree/main/.claude/skills/worktree into .cursor/skills/worktree/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "worktree", then confirm the skill loads.

Cursor copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

gemini skills install

$ gemini skills install https://github.com/imran31415/kube-coder.git --path .claude/skills/worktree

--scope user (default) or --scope workspace; --path is the subfolder of the repo that holds the skill; --consent skips the security confirmation prompt.

skills CLI

$ npx skills add imran31415/kube-coder --skill worktree -a gemini-cli

Project install goes to .agents/skills/; add -g for ~/.gemini/skills/.

GitHub CLI

$ gh skill install imran31415/kube-coder worktree --agent gemini-cli

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/imran31415/kube-coder.git skills-src && mkdir -p .gemini/skills && cp -r skills-src/.claude/skills/worktree .gemini/skills/worktree && rm -rf skills-src

Use ~/.gemini/skills/ instead of .gemini/skills for a personal install, then run /skills reload.

Gemini CLI skills documentation · loads skills from .gemini/skills/, .agents/skills/

Paste into Gemini CLI

Install the "worktree" agent skill from https://github.com/imran31415/kube-coder/tree/main/.claude/skills/worktree into .gemini/skills/worktree/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "worktree", then confirm the skill loads.

Gemini CLI copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

GitHub CLI

$ gh skill install imran31415/kube-coder worktree

Installs for Copilot at project scope by default; add --scope user for a personal install. Preview a skill first with gh skill preview. Needs GitHub CLI 2.90.0 or later (public preview).

skills CLI

$ npx skills add imran31415/kube-coder --skill worktree -a github-copilot

Project install goes to .agents/skills/; add -g for ~/.copilot/skills/.

Manual copy

$ git clone --depth 1 https://github.com/imran31415/kube-coder.git skills-src && mkdir -p .github/skills && cp -r skills-src/.claude/skills/worktree .github/skills/worktree && rm -rf skills-src

Use ~/.copilot/skills/ instead of .github/skills for a personal install. Commit .github/skills so cloud agent and code review can use it.

GitHub Copilot skills documentation · loads skills from .github/skills/, .claude/skills/, .agents/skills/

Paste into GitHub Copilot

Install the "worktree" agent skill from https://github.com/imran31415/kube-coder/tree/main/.claude/skills/worktree into .github/skills/worktree/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "worktree", then confirm the skill loads.

GitHub Copilot copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

skills CLI

$ npx skills add imran31415/kube-coder --skill worktree -a opencode

OpenCode documents no install command of its own. Project install goes to .agents/skills/; add -g for ~/.config/opencode/skills/.

GitHub CLI

$ gh skill install imran31415/kube-coder worktree --agent opencode

Project scope by default (.agents/skills/); add --scope user for a personal install.

Manual copy

$ git clone --depth 1 https://github.com/imran31415/kube-coder.git skills-src && mkdir -p .opencode/skills && cp -r skills-src/.claude/skills/worktree .opencode/skills/worktree && rm -rf skills-src

Use ~/.config/opencode/skills/ instead of .opencode/skills for a personal install.

OpenCode skills documentation · loads skills from .opencode/skills/, .claude/skills/, .agents/skills/

Paste into OpenCode

Install the "worktree" agent skill from https://github.com/imran31415/kube-coder/tree/main/.claude/skills/worktree into .opencode/skills/worktree/ in this project. Copy the whole folder (SKILL.md and every file beside it), keep the folder name "worktree", then confirm the skill loads.

OpenCode copies the folder itself, the same result as the manual copy. Check what it changed before you commit it.

Facts

Skill name: worktree
GitHub stars: 388
Token cost: ~1.6k tokens
SKILL.md length: 751 words
Files: 2
Skills in repo: 8
Repo updated: Oct 3, 2026
First seen: Oct 7, 2026
Licence: MIT

At a glance

Create an isolated git worktree + branch + port for this session so concurrent kube-coder sessions and builds don't conflict.

Works in 5 steps: Uncommitted work stays behind. A… → cd persists, env does not. In this… → Disk. Worktrees share .git, but a fresh… → …
Tasks that involve Git worktrees
SKILL.md covers Start an isolated session (the…, Running a dev server / preview, Builds and List / tear down, plus 2 more sections
Runs Shell scripts from its folder; calls bash, git and jq

What it does

Worktree is an agent skill from imran31415/kube-coder. Create an isolated git worktree + branch + port for this session so concurrent kube-coder sessions and builds don't conflict. Use at the START of any change you want isolated, when two sessions touch the same repo, or before running a dev server/build that would collide on ports or output dirs. Also lists and tears down worktrees.

Its SKILL.md is about 1.6k tokens, which your agent loads only when the skill is triggered. The skill folder holds 1 other file (for example `worktree.sh`).

It sits in Development, covering Git worktrees. It works with Git. The repository describes itself as: helm chart for a isolated dev coding environment pod in kubernetes. The licence is MIT.

When your agent uses it

Tasks that involve Git worktrees

Example prompts

“/worktree”

Requirements

Python 3
A Bash shell
Docker
Pre-approved tools (allowed-tools): Bash, Read

Workflow steps

5 steps, taken from the first numbered list in SKILL.md.

Uncommitted work stays behind. A worktree branches from HEAD (the
cd persists, env does not. In this harness the working directory
Disk. Worktrees share .git, but a fresh node_modules / .venv /
One repo, one clone. All worktrees for a repo register under that clone's
Not for the boot-time kube-coder pull. start.sh does

What it can do on your machine

Read from SKILL.md and the folder at commit f5da764. It shows what the files ask for, not the result of running them.

Tool permissions
Pre-approves these tools, so the agent can use them without asking each time:
- Bash
- Read
From allowed-tools in the SKILL.md frontmatter.
Runs code
Ships script files (Shell), which the agent can run.
Shell commands in SKILL.md call:
- bash
- git
- jq
- npm
- python3
From the folder's file list and the shell code blocks in SKILL.md.
Network
No URLs in SKILL.md. Its commands use git and npm, which can reach the network depending on how they are called.
From URLs in SKILL.md, links to its own repository left out.
Credentials
Names no API keys, tokens, secrets or passwords.
From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Worktree loads about 1.6k tokens when it runs. Until then it costs about 85 tokens; SKILL.md has 751 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it: ~85
When it runs · the whole SKILL.md, loaded when a task matches: ~1.6k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check: notes

The automated check noted patterns worth knowing about, such as sudo or a known installer.

NotePre-approves every shell command (allowed-tools: Bash)SKILL.md
```
allowed-tools: Bash, Read
```

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from imran31415/kube-coder at commit f5da764, republished under its MIT licence (© imran31415). 751 words, ~1,630 tokens.

Download SKILL.mdSave it as .claude/skills/worktree/SKILL.md (or your agent's skills folder). This skill also uses 1 other file; get the full folder from GitHub.

name: worktree
description: Create an isolated git worktree + branch + port for this session so concurrent kube-coder sessions and builds don't conflict. Use at the START of any change you want isolated, when two sessions touch the same repo, or before running a dev server/build that would collide on ports or output dirs. Also lists and tears down worktrees.
allowed-tools: Bash, Read
user-invocable: true
argument-hint: [slug] | list | rm <slug> [--force] (default: new, slug from task id)

Per-session git worktree

kube-coder isolates sessions at the terminal level (each task gets its own tmux session + ~/.claude-tasks/<id>/) but everything still runs in the same /home/dev filesystem. So two sessions on the same repo collide three ways:

git tree — branch/checkout/index thrash, a dirty working tree
build output — both write ./dist, ./build; Kaniko reads its context from the shared path
dev-server ports — EADDRINUSE on :3000 (ports are per-pod, not per-session)

This skill fixes all three for the current session with no infra change: it gives you a dedicated git worktree (own checkout + branch) at a path outside the repo, and leases a free port for any server you start. Worktrees share the main clone's object store, so they're cheap on disk — only working files are duplicated.

The helper is worktree.sh next to this file. Invoke it as bash "$CLAUDE_SKILL_DIR/worktree.sh" … (or with its absolute path under /home/dev/kube-coder/.claude/skills/worktree/).

Start an isolated session (the common path)

Run from inside the repo you want to work on (cd there first). $ARGUMENTS is an optional human slug; if omitted it derives one from the current task id (KC_TASK_ID) or a random token, so it's always unique.

bash

WT=/home/dev/kube-coder/.claude/skills/worktree/worktree.sh
eval "$(bash "$WT" new "$ARGUMENTS")"   # creates worktree+branch+port, sets KC_WT / PORT
cd "$KC_WT"                              # <-- this cd PERSISTS across your Bash calls

After this, do all work for the change from $KC_WT. The human summary (path / branch / port / preview URL) is printed to stderr — note the port, because exported env vars do not survive between separate Bash tool calls (the cd does). The worktree also records everything in $KC_WT/.kc-worktree.json, so you can re-read the port later:

bash

jq -r .port "$KC_WT/.kc-worktree.json"   # or read .branch / .path

What you get

worktree dir: /home/dev/.worktrees/<repo>/<slug>/
branch: kc/<slug> (branched from current HEAD, or a base-ref: new <slug> <base>)
leased port in 3100–3999 (skips kube-coder's reserved ports, other leases and anything already listening)
new with a slug that already exists reuses that worktree (same path, branch and port) instead of failing

Running a dev server / preview

Bind the leased port explicitly (env doesn't persist between calls), then open it through the app-proxy — no port config in the dashboard needed:

bash

PORT=$(jq -r .port "$KC_WT/.kc-worktree.json")
cd "$KC_WT" && PORT=$PORT npm run dev      # or: python -m http.server "$PORT", etc.
# preview at:  /api/app-proxy/<port>/

Builds

Because the worktree is its own path, docker-build (Kaniko) and local build output (./dist, ./build) no longer collide with other sessions. Run builds with the worktree as context — e.g. docker-build -t img:tag "$KC_WT".

List / tear down

bash

bash "$WT" list                 # worktrees + leased ports for the current repo
bash "$WT" rm <slug>            # remove the worktree DIR; the branch is KEPT
bash "$WT" rm <slug> --force    # also drop uncommitted changes in it

rm deliberately keeps kc/<slug> — that branch is your change. Push/PR it as usual, then delete with the git branch -D line rm prints. rm refuses to delete a dirty worktree unless you pass --force.

Show full SKILL.md (358 more words)Show less

Footguns

Uncommitted work stays behind. A worktree branches from HEAD (the committed state). Anything uncommitted on your original checkout is not carried in. Commit or stash first if you need it.
cd persists, env does not. In this harness the working directory survives between Bash calls but exported vars don't. Rely on cd "$KC_WT" and re-read the port from .kc-worktree.json when you need it; don't assume $PORT is still set in a later call.
Disk. Worktrees share .git, but a fresh node_modules / .venv / build tree per worktree is not shared and can fill the 20–50Gi PVC. Keep a handful live at once; rm ones you're done with.
One repo, one clone. All worktrees for a repo register under that clone's .git/worktrees. Don't rm -rf a worktree dir by hand — use rm (which runs git worktree remove + prune) so git's bookkeeping stays consistent.
Not for the boot-time kube-coder pull. start.sh does git pull --ff-only origin main on /home/dev/kube-coder at boot. Working in a kc/<slug> worktree keeps main clean so that pull still fast-forwards — which is the point. Don't check out main inside a worktree.

The dashboard does this too (#701)

A Build can now be launched isolated without this skill: the New Build form's Isolated worktree toggle, a Board run's Isolated worktree per item, create_task(isolate=true) from the dashboard MCP, and spawn_agent(isolate= true) for sub-agents. All of them — and this script — share one implementation, charts/workspace/worktrees.py (in the pod at /tmp/browser/worktrees.py): the same /home/dev/.worktrees/<repo>/<slug> layout, the same .kc-worktree.json manifest, the same port lease and the same lock. So a worktree made here shows up in Settings → Worktrees, counts toward KC_MAX_WORKTREES, and its port is never handed out twice.

When /tmp/browser/worktrees.py is present this script delegates to it (override with KC_WORKTREES_PY); otherwise it falls back to its own bash implementation, which takes the same flock and writes the same manifest.

A worktree you make by hand has no owning Build, so the dashboard's cleanup sweep only removes it once it is pristine (nothing committed, nothing dirty) and older than KC_WORKTREE_GC_DAYS (7). Anything with work in it is yours to remove.

Sanity-check the helper before relying on it:

bash

bash -n /home/dev/kube-coder/.claude/skills/worktree/worktree.sh
python3 /tmp/browser/worktrees.py --api-version

Files

SKILL.md and 1 other file in .claude/skills/worktree of imran31415/kube-coder.

SKILL.md
worktree.sh

Open the folder on GitHubat commit f5da764

Compare with similar skills

Worktree next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Worktree compared with similar skills
Skill	Stars	Used in	Tokens	Auto-check	Licence	Repo updated
Worktree this skillimran31415/kube-coder	388	—	~1.6k	Automated safety check: Notes	MIT	4 days ago
Finishing a Development Branchobra/superpowers	296k	5 repos	~1.9k	Automated safety check: Pass	MIT	yesterday
Finishing A Development Branchfarm-fe/farm	5.6k	33 repos	~1.8k	Automated safety check: Pass	MIT	15 days ago
Git Worktree Cleanuplobehub/lobehub	83k	—	~2.8k	Automated safety check: Pass	Custom licence	today
Pre-Release PR Triagejamiepine/voicebox	57k	—	~3.1k	Automated safety check: Pass	MIT	today
Ccmanager Configkbwo/ccmanager	1.3k	—	~1.5k	Automated safety check: Pass	MIT	10 days ago

Similar skills

Finishing a Development Branch
obra/superpowers
Walks the last step of a branch: confirm tests pass, detect the git environment, ask how to integrate, carry out your choice and clean up the worktree.
296k GitHub starsUsed in 5 repos~1.9k tokens
DevelopmentAuto-check passed
Finishing A Development Branch
farm-fe/farm
A skill your agent uses when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for…
5.6k GitHub starsUsed in 33 repos~1.8k tokens
DevelopmentAuto-check passed
Git Worktree Cleanup
lobehub/lobehub
Audits stale Git worktrees and branches with a bundled script, classifies each one, and deletes only after you approve the exact candidates.
83k GitHub stars~2.8k tokensUpdated today
DevelopmentAuto-check passed
Pre-Release PR Triage
jamiepine/voicebox
Sorts a backlog of open pull requests into must-merge, candidate, superseded and deferred, writes a triage doc and works the merge loop before a release.
57k GitHub stars~3.1k tokensUpdated today
DevelopmentAuto-check passed
Ccmanager Config
kbwo/ccmanager
Set up, review, or repair a CCManager config — .ccmanager.json at a git repository root, or the global ~/.config/ccmanager/config.json.
1.3k GitHub stars~1.5k tokensUpdated 10 days ago
DevelopmentAuto-check passed
Cap Feature Building Workflow
CapSoftware/Cap
Builds a Cap feature in an isolated Git worktree with disposable dev resources, verification, a recorded demo and a neutral pull request, started with /building.
23k GitHub stars~2.5k tokensUpdated today
DevelopmentAuto-check: warnings

Questions about Worktree

What does Worktree do?

Create an isolated git worktree + branch + port for this session so concurrent kube-coder sessions and builds don't conflict. Worktree is an agent skill from imran31415/kube-coder. Create an isolated git worktree + branch + port for this session so concurrent kube-coder sessions and builds don't conflict.

When should I use Worktree?

Worktree fits situations like: tasks that involve Git worktrees.

How do I install Worktree in Claude Code?

Run `npx skills add imran31415/kube-coder --skill worktree -a claude-code`. Or copy the skill folder (.claude/skills/worktree in imran31415/kube-coder) into .claude/skills/worktree in your project. Claude Code loads it when a task matches its description.

How do I install Worktree in Codex?

Run `npx skills add imran31415/kube-coder --skill worktree -a codex`. Or copy the skill folder (.claude/skills/worktree in imran31415/kube-coder) into .agents/skills/worktree in your project. Codex loads it when a task matches its description.

Can I use Worktree in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add imran31415/kube-coder --skill worktree -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/worktree, .gemini/skills/worktree, .github/skills/worktree and .opencode/skills/worktree in your project.

What does Worktree need to run?

Going by SKILL.md and its folder, Worktree needs a shell for the scripts in its folder and the command-line tools its instructions call (bash, git, jq, npm and python3). Our summary lists: Python 3; A Bash shell; Docker. Its frontmatter pre-approves these tools: Bash, Read.

Does Worktree access the network?

SKILL.md contains no URLs. Its commands use git and npm, which can reach the network depending on how they are called. This is read from the text; nothing was executed.

Is Worktree safe to install?

Our automated static check of SKILL.md found notes only (pre-approves every shell command (allowed-tools: bash)), nothing it rates as a warning. It is not a guarantee. Review the folder before installing.

What licence does Worktree use?

Worktree is published under the MIT licence (the repository's licence). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Worktree use?

About 1.6k tokens (SKILL.md is roughly 6.5k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Worktree?

Skills that share tags, products or a category with Worktree: Finishing a Development Branch (obra/superpowers, 296k stars), Finishing A Development Branch (farm-fe/farm, 5.6k stars), Git Worktree Cleanup (lobehub/lobehub, 83k stars) and Pre-Release PR Triage (jamiepine/voicebox, 57k stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Worktree?

imran31415 (a GitHub user) maintains it in imran31415/kube-coder, which has 388 GitHub stars. The repository holds 8 skills in this directory. The repository was last updated on October 3, 2026.

Source: imran31415/kube-coder on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.

Install Worktree

Facts

At a glance

What it does

When your agent uses it

Example prompts

Requirements

Workflow steps

What it can do on your machine

Tool permissions

Runs code

Network

Credentials

Context cost

Safety

SKILL.md

Per-session git worktree

Start an isolated session (the common path)

What you get

Running a dev server / preview

Builds

List / tear down

Footguns

The dashboard does this too (#701)

Files

Compare with similar skills

Similar skills

More from imran31415/kube-coder

Related

Questions about Worktree