feat(kimi-code): add -w, --worktree [name] flag for isolated sessions by rrva · Pull Request #818 · MoonshotAI/kimi-code

rrva · 2026-06-16T11:31:26Z

Related Issue

Closes #828

Problem

Users running multiple Kimi Code sessions on the same repository need a way to avoid file conflicts and branch-switching overhead. The legacy Kimi CLI already supports this with a worktree flag, and users expect the same capability in Kimi Code CLI.

What changed

Added "-w, --worktree [name]" to create a new git worktree for the session.
New worktrees live under "/.kimi/worktrees/" with a detached HEAD checkout at the current HEAD.
Auto-generates a three-word slug name (e.g. amber-drifting-cloud) when no name is supplied.
Validates conflicts: --worktree cannot combine with --session or --continue.
Persists worktree_path and parent_repo_path in session metadata.
Cleans up the worktree on exit when the session is empty, so abandoned worktrees do not accumulate.
Added unit tests for the worktree utilities and CLI option parsing/conflict detection.
Updated CLI reference docs in English and Chinese.

Checklist

I have read the CONTRIBUTING document.
I have linked a related issue, or explained the problem above.
I have added tests that prove my feature works.
Ran gen-changesets skill, or this PR needs no changeset.
Ran gen-docs skill, or this PR needs no doc update.

Verification

pnpm --filter @moonshot-ai/kimi-code typecheck
pnpm --filter @moonshot-ai/kimi-code exec vitest run test/cli test/tui test/utils
pnpm exec oxlint --tsconfig=apps/kimi-code/tsconfig.json

Add a CLI flag that creates a new git worktree under <repo-root>/.kimi/worktrees/<name> and runs the session inside it. When no name is given, a kimi-<timestamp> name is generated. The worktree is created in detached HEAD at the current HEAD. - New worktree utility module with create/remove/list/find helpers. - Conflict validation against --session and --continue. - Persist worktree_path and parent_repo_path in session metadata. - Clean up the worktree on exit when the session is empty. - Add CLI parsing tests and worktree utility unit tests. Inspired by the upstream kimi-cli worktree feature.

changeset-bot · 2026-06-16T11:31:33Z

🦋 Changeset detected

Latest commit: 42902f6

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 4 packages

Name	Type
@moonshot-ai/agent-core	Minor
@moonshot-ai/kimi-code	Minor
@moonshot-ai/acp-adapter	Patch
@moonshot-ai/migration-legacy	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: b7db693578

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 895e65e2de

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

… names

- Make prepareWorktree synchronous; it performs no async work. - Log best-effort worktree cleanup failures instead of swallowing them.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: a74eb192b7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ed15942c78

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 91be1d7b83

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

- Keep .kimi/ out of the parent git index via .git/info/exclude. - Preserve the caller's subdirectory when entering a worktree session. - Delay worktree creation until after update preflight returns continue. - Skip prompt-mode worktree cleanup on turn failures; leave worktrees inspectable. - Track lifetime session content so /new does not delete earlier-session worktrees. - Emit resume hints with cd '<worktree>' for worktree sessions.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 6a86ada5cb

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

When a user ran /new inside a worktree session, createSessionFromCurrentState() did not pass the startup metadata, so the replacement session lost worktreePath and parentRepoPath. The TUI then no longer surfaced worktree context in the system prompt or subagents. Forward the startup metadata into replacement sessions and add a test covering the /new path.

- Set everHadSessionContent when entries are appended/pushed and before the transcript is cleared, so /new after an earlier session does not delete the worktree. - Fall back to the worktree root when the mirrored caller subdirectory does not exist in the detached worktree; clean up the worktree if chdir still fails. - Use quoteShellArg for the cd path in worktree resume hints so paths with shell metacharacters are safe to paste.

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4710074370

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

- Resolve the worktree exclude via `git rev-parse --git-path info/exclude` instead of `--git-dir`. When the repo root is itself a linked worktree, `--git-dir` points at `.git/worktrees/<name>`, but Git reads the local exclude from the common git dir; the old path wrote `.kimi/` to a file Git never consults, so `git status` in the parent worktree still showed `?? .kimi/`. - Carry the current/resumed session's worktree metadata into replacement sessions when startup metadata is absent. A worktree session resumed with `-r` (no `--worktree`) has undefined startup metadata, so `/new` previously dropped worktreePath/parentRepoPath and lost the worktree system-prompt context for agents/subagents. Both paths gain regression tests (linked-worktree exclude resolution; resumed session /new metadata carry-forward).

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 42902f6c8d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

chatgpt-codex-connector · 2026-06-16T18:49:52Z

+    return;
+  }
+  const excludePath = resolve(repoRoot, excludePathResult.stdout);
+  const marker = '.kimi/';


Limit the local exclude to worktree storage

When a repository already has untracked .kimi content unrelated to these session worktrees, appending .kimi/ to the shared info/exclude hides the entire directory from git status for every checkout using this common git dir. Running kimi -w can therefore silently stop Git from reporting files the user may intend to add; exclude only the storage path such as .kimi/worktrees/ instead of the whole .kimi/ tree.

Useful? React with 👍 / 👎.

docs(reference): document -w, --worktree flag in EN and ZH

3974aa3

chatgpt-codex-connector Bot reviewed Jun 16, 2026

View reviewed changes

Comment thread apps/kimi-code/src/utils/git/worktree.ts Outdated

Comment thread apps/kimi-code/src/utils/git/worktree.ts

rrva mentioned this pull request Jun 16, 2026

feat: add -w, --worktree [name] flag for isolated sessions #828

Open

chatgpt-codex-connector Bot reviewed Jun 16, 2026

View reviewed changes

Comment thread apps/kimi-code/src/main.ts Outdated

Comment thread apps/kimi-code/src/main.ts Outdated

rrva added 3 commits June 16, 2026 18:12

feat(kimi-code): add bundled word lists for --worktree auto-generated…

c61f5d5

… names

fix(kimi-code): harden --worktree startup cleanup and name validation

3bbf152

fix(kimi-code): correct --worktree cleanup and prepareWorktree signature

a74eb19

- Make prepareWorktree synchronous; it performs no async work. - Log best-effort worktree cleanup failures instead of swallowing them.

rrva force-pushed the feat/worktree-cli-flag branch from 895e65e to a74eb19 Compare June 16, 2026 16:12

chatgpt-codex-connector Bot reviewed Jun 16, 2026

View reviewed changes

Comment thread apps/kimi-code/src/main.ts

chatgpt-codex-connector Bot reviewed Jun 16, 2026

View reviewed changes

Comment thread apps/kimi-code/src/cli/run-shell.ts

Comment thread apps/kimi-code/src/main.ts Outdated

feat(agent-core): surface worktree metadata in agent system prompt

91be1d7

rrva force-pushed the feat/worktree-cli-flag branch from ed15942 to 91be1d7 Compare June 16, 2026 17:03

chatgpt-codex-connector Bot reviewed Jun 16, 2026

View reviewed changes

Comment thread apps/kimi-code/src/tui/kimi-tui.ts

chatgpt-codex-connector Bot reviewed Jun 16, 2026

View reviewed changes

Comment thread apps/kimi-code/src/tui/kimi-tui.ts

Comment thread apps/kimi-code/src/main.ts Outdated

Comment thread apps/kimi-code/src/cli/run-shell.ts Outdated

rrva added 2 commits June 16, 2026 19:25

chatgpt-codex-connector Bot reviewed Jun 16, 2026

View reviewed changes

Comment thread apps/kimi-code/src/utils/git/worktree.ts Outdated

Comment thread apps/kimi-code/src/tui/kimi-tui.ts Outdated

chatgpt-codex-connector Bot reviewed Jun 16, 2026

View reviewed changes

Conversation

rrva commented Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Related Issue

Problem

What changed

Checklist

Verification

Uh oh!

changeset-bot Bot commented Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

Uh oh!

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Jun 16, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

rrva commented Jun 16, 2026 •

edited

Loading

changeset-bot Bot commented Jun 16, 2026 •

edited

Loading