Agent-readable docs index: /llms.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 ──▶ 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 (optionally pass a target-branch; it defaults to the project's default branch):
  • It rebases the worktree commits onto the target and fast-forwards. All commits are preserved, nothing is squashed.
  • The worktree and target must have no uncommitted changes.
  • On success the ⬦ worktree: prefix is removed from the thread title and Kimaki reports the merged 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. Once the agent is done, run /merge-worktree again to complete the merge.
  /merge-worktree ──▶ rebase ──▶ conflict?
                                 │ yes
                                 ▼
                      agent resolves ──▶ run /merge-worktree again
Worktrees created by Kimaki, by OpenCode, or manually all show up in /worktrees for the channel's project.
Powered byHolocron