Agent-readable docs index: /llms.txt. Full docs in one file: /llms-full.txt. Download /docs.zip to grep all markdown files locally.

Worktrees

Worktrees let a session work in an isolated folder so it never touches your main checkout. Start with an idea in a thread, then move it into a worktree once you realize it should not change your main files. Merge the commits back later with one command.

The typical flow

  thread: redesign sidebar
       │ /new-worktree
       ▼
  ┌──────────────────┐     work in worktree
  │worktree: opencode│──────▶ commits accumulate
  │kimaki-redesign   │
  └────┬─────────────┘
       │ /merge-worktree
       ▼
  rebase onto target
       ├──▶ keep commits ──▶ fast-forward ──▶ done
       └──▶ squash ──▶ one commit ──▶ fast-forward ──▶ done

Creating a worktree

Run /new-worktree:
  • From a project channel, pass a name. Kimaki creates a thread immediately (so you can start typing) and builds the worktree in the background. The branch is named opencode/kimaki-<name> and the thread is prefixed with ⬦ worktree:.
  • From an existing thread, the name is optional; Kimaki derives it from the thread name.
  • base-branch is optional and defaults to HEAD (your current local HEAD), so you can branch from unpushed commits.
Long auto-derived names get shortened by stripping vowels (e.g. configurable-sidebar-width becomes cnfgrbl-sdbr-wdth). Names you pass explicitly are kept as-is.

Why isolate work in a worktree

  • Protect your main checkout. Experimental or risky changes stay in a separate folder.
  • Run things in parallel. Different threads can each have their own worktree and branch.
  • Keep a clean default branch until you decide the work is good.

Merging back

When the worktree work is ready, run /merge-worktree. The strategy select has two choices, and target-branch optionally overrides the project's default branch:
  • Keep commits (rebase) is the default. It rebases the worktree commits onto the target and preserves every commit.
  • Squash into one commit rebases the same changes, then creates one commit on the target named Merge worktree <branch>.
  • The worktree and target must have no uncommitted changes.
  • On success the ⬦ worktree: prefix is removed from the thread title and Kimaki reports the source commit count.

Conflict resolution by the agent

If the rebase hits conflicts, Kimaki does not give up. It asks the AI model in the thread to resolve them: understand both sides, edit the conflicted files, git add, and git rebase --continue, repeating until the rebase finishes. The agent then runs kimaki merge-worktree itself with the same strategy and target branch. If the target changed and the automatic retry fails, run /merge-worktree again later.
  /merge-worktree ──▶ rebase ──▶ conflict?
                                 │ yes
                                 ▼
                      agent resolves ──▶ CLI retries merge ──▶ done
                                              └──▶ failure ──▶ retry later

Listing worktrees and auto-worktrees

Run /worktrees to see every worktree for the channel's project (Kimaki, OpenCode, or manual). The same view has a Turn on / Turn off button for automatic worktree creation on new sessions in that channel.
Worktrees created by Kimaki, by OpenCode, or manually all show up in /worktrees for the channel's project.