VividKit Crystal clear AI coding
VI
Choose Your Setup Get Started with AgentKit Continue with ClaudeKit Migrate from ClaudeKit to AgentKit Clean cutover from ClaudeKit What Is AgentKit? How AgentKit Works AgentKit Kits, Skills, Agents & Hooks AgentKit Runtime Support AgentKit Desktop App AgentKit Configuration AgentKit CLI Quick Reference AgentKit Skills Cheatsheet AgentKit Workflows AgentKit Statusline Update AgentKit CLI & Kits AgentKit Helper Clean reinstall of AgentKit AgentKit Troubleshooting What is ClaudeKit? ClaudeKit CLI Guide Command Finder Commands Cheat Sheet Workflow Recipes CLI Quick Reference Claude Mechanics Permission Modes ClaudeKit Hooks Coexistence ClaudeKit x Codex CK → Other coding tools How ClaudeKit Works Inside ClaudeKit Finding Your Unknowns Session Recovery Fix from Logs UI/UX Guide Accounts Switcher IDE Config Remote Control Codex App System Diagramming UI Review Gate Promotions Support VividKit

Quick Ref / Command

Marketing Kit

/ak:worktree

Isolated Git worktrees

Create, inspect, configure, and clean isolated git worktrees for feature isolation, stale cleanup, health audits, monorepos, and submodules.

01

Inspect repo

02

Detect naming

03

Prefix and slug

04

Resolve project

Rule 01

Info first: repo type, base branch, projects, and root source drive the create command.

Rule 02

Preserve exact branch names when the user provides one; otherwise infer a boring prefix and short slug.

Rule 03

Dry-run stale cleanup before pruning metadata.

Rule 04

Host-native worktree systems are separate from ak:worktree's own root preference.

Execution Map

Core lanes from input to output, aligned with the command's real execution path.

01

Start

Input, scope, route

  1. 1 Inspect repo Run the info command and parse repoType, baseBranch, projects, worktreeRoot, dirtyState, and warnings.
  2. 2 Detect naming If the request provides an exact branch with uppercase, tracker key, slashes, or says exact name, preserve it with no prefix.
02

Work

Agent / skill execution

  1. 3 Prefix and slug Otherwise infer feat/fix/refactor/docs/test/chore/perf from the description and convert the feature to a max-50-character kebab slug.
  2. 4 Resolve project For monorepos without a specified project, ask the user to choose from detected projects.
03

Verify

Gate, review, validation

  1. 5 Create Run the create command in standalone or monorepo form, using base, submodule, worktree-root, json, dry-run, or no-prefix options only when needed.
  2. 6 Bootstrap deps Install dependencies based on lockfiles and language manifests in the new worktree.
04

Close

Report, handoff, artifact

  1. 7 Audit/clean Use list, status, prune, or remove for health checks and stale cleanup; start prune with dry-run when auditing metadata.
  2. 8 Report Return created path, branch/base info, dependency action, warnings, and any health or cleanup results.

Modes / Routes

info

Report repository type, projects, base branch, worktree root, and dirty state.

Research:
Repo metadata
Review:
Wrong root
Validate:
Info JSON
list

List known worktrees and branches before removal or reuse.

Research:
Worktree registry
Review:
Ambiguous target
Validate:
Worktree list
status

Health audit with dirty state, base branch, and ahead/behind counts.

Research:
normalized paths
Review:
dirty/detached/divergence
Validate:
status JSON
create [project] <feature> [options]

Create an isolated worktree; options include --prefix, --base, --checkout-submodules, --no-prefix, --worktree-root, --json, --dry-run, and legacy --env.

Research:
repo info + naming
Review:
root/base warnings
Validate:
worktreePath JSON
remove <name-or-path>

Force-remove one exact approved worktree and then try branch deletion.

Research:
Exact target
Review:
Uncommitted work
Validate:
Removal result
prune

Remove stale Git worktree metadata; run prune --dry-run before applying.

Research:
metadata entries
Review:
dry-run first
Validate:
entries JSON

Sample Prompt

Concrete invocations for each flag, subcommand, mode, or route available in the live workflow.

Feature worktree Recommended 
/ak:worktree create onboarding email flow
Use when:
Use before implementation that should be isolated from the current checkout.
Expected:
New worktree path with inferred branch prefix, dependency bootstrap guidance, and next safe command.
Exact branch 
/ak:worktree create --no-prefix ND-1377-cleanup-docs
Use when:
Use when the branch name must preserve tracker casing or slashes.
Expected:
Worktree created with preserved branch name semantics and clear instructions for entering the folder.
Inspect status 
/ak:worktree status
Use when:
You need worktree health, dirty state, or base-branch divergence before reuse or cleanup.
Expected:
Returns a health audit with normalized paths, dirty state, and ahead/behind counts for each worktree.

Handled Scope

  • Inspect repo
  • Detect naming
  • Prefix and slug
  • Resolve project
  • Create
  • Bootstrap deps

Artifacts Produced

Worktree result

Pattern

worktreePath • baseBranch • warnings • dependency action

JSON-backed fields make branch, path, root source, and warnings explicit.

Next