MediaMetz/gemini-cli
1
0
Fork 0
mirror of https://github.com/google-gemini/gemini-cli.git synced 2026-05-15 14:23:02 -07:00
Code Issues Packages Projects Releases Wiki Activity

feat(ux-extension): address feedback and fix build errors

Browse Source
This commit is contained in:
Keith Guerin
2026-03-24 15:48:25 -07:00
parent 3c22fd2787
commit 2188d09009
6 changed files with 275 additions and 36 deletions
Download Patch File Download Diff File Expand all files Collapse all files
package-lock.json
Generated
+3 -31
View File
@@ -486,8 +486,7 @@
"version": "2.11.0",
"resolved": "https://registry.npmjs.org/@bufbuild/protobuf/-/protobuf-2.11.0.tgz",
"integrity": "sha512-sBXGT13cpmPR5BMgHE6UEEfEaShh5Ror6rfN3yEK5si7QVrtZg8LEPQb0VVhiLRUslD2yLnXtnRzG035J/mZXQ==",
"license": "(Apache-2.0 AND BSD-3-Clause)",
"peer": true
"license": "(Apache-2.0 AND BSD-3-Clause)"
},
"node_modules/@bundled-es-modules/cookie": {
"version": "2.0.1",
@@ -1490,7 +1489,6 @@
"resolved": "https://registry.npmjs.org/@grpc/grpc-js/-/grpc-js-1.13.4.tgz",
"integrity": "sha512-GsFaMXCkMqkKIvwCQjCrwH+GHbPKBjhwo/8ZuUkWHqbI73Kky9I+pQltrlT0+MWpedCoosda53lgjYfyEPgxBg==",
"license": "Apache-2.0",
"peer": true,
"dependencies": {
"@grpc/proto-loader": "^0.7.13",
"@js-sdsl/ordered-map": "^4.4.2"
@@ -2197,7 +2195,6 @@
"integrity": "sha512-t54CUOsFMappY1Jbzb7fetWeO0n6K0k/4+/ZpkS+3Joz8I4VcvY9OiEBFRYISqaI2fq5sCiPtAjRDOzVYG8m+Q==",
"dev": true,
"license": "MIT",
"peer": true,
"dependencies": {
"@octokit/auth-token": "^6.0.0",
"@octokit/graphql": "^9.0.2",
@@ -2378,7 +2375,6 @@
"resolved": "https://registry.npmjs.org/@opentelemetry/api/-/api-1.9.0.tgz",
"integrity": "sha512-3giAOQvZiH5F9bMlMiv8+GSPMeqg0dbaeo58/0SlA9sxSqZhnUtxzX9/2FzyhS9sWQf5S0GJE0AKBrFqjpeYcg==",
"license": "Apache-2.0",
"peer": true,
"engines": {
"node": ">=8.0.0"
}
@@ -2428,7 +2424,6 @@
"resolved": "https://registry.npmjs.org/@opentelemetry/core/-/core-2.5.0.tgz",
"integrity": "sha512-ka4H8OM6+DlUhSAZpONu0cPBtPPTQKxbxVzC4CzVx5+K4JnroJVBtDzLAMx4/3CDTJXRvVFhpFjtl4SaiTNoyQ==",
"license": "Apache-2.0",
"peer": true,
"dependencies": {
"@opentelemetry/semantic-conventions": "^1.29.0"
},
@@ -2803,7 +2798,6 @@
"resolved": "https://registry.npmjs.org/@opentelemetry/resources/-/resources-2.5.0.tgz",
"integrity": "sha512-F8W52ApePshpoSrfsSk1H2yJn9aKjCrbpQF1M9Qii0GHzbfVeFUB+rc3X4aggyZD8x9Gu3Slua+s6krmq6Dt8g==",
"license": "Apache-2.0",
"peer": true,
"dependencies": {
"@opentelemetry/core": "2.5.0",
"@opentelemetry/semantic-conventions": "^1.29.0"
@@ -2837,7 +2831,6 @@
"resolved": "https://registry.npmjs.org/@opentelemetry/sdk-metrics/-/sdk-metrics-2.5.0.tgz",
"integrity": "sha512-BeJLtU+f5Gf905cJX9vXFQorAr6TAfK3SPvTFqP+scfIpDQEJfRaGJWta7sJgP+m4dNtBf9y3yvBKVAZZtJQVA==",
"license": "Apache-2.0",
"peer": true,
"dependencies": {
"@opentelemetry/core": "2.5.0",
"@opentelemetry/resources": "2.5.0"
@@ -2892,7 +2885,6 @@
"resolved": "https://registry.npmjs.org/@opentelemetry/sdk-trace-base/-/sdk-trace-base-2.5.0.tgz",
"integrity": "sha512-VzRf8LzotASEyNDUxTdaJ9IRJ1/h692WyArDBInf5puLCjxbICD6XkHgpuudis56EndyS7LYFmtTMny6UABNdQ==",
"license": "Apache-2.0",
"peer": true,
"dependencies": {
"@opentelemetry/core": "2.5.0",
"@opentelemetry/resources": "2.5.0",
@@ -4129,7 +4121,6 @@
"integrity": "sha512-6mDvHUFSjyT2B2yeNx2nUgMxh9LtOWvkhIU3uePn2I2oyNymUAX1NIsdgviM4CH+JSrp2D2hsMvJOkxY+0wNRA==",
"devOptional": true,
"license": "MIT",
"peer": true,
"dependencies": {
"csstype": "^3.0.2"
}
@@ -4404,7 +4395,6 @@
"integrity": "sha512-6sMvZePQrnZH2/cJkwRpkT7DxoAWh+g6+GFRK6bV3YQo7ogi3SX5rgF6099r5Q53Ma5qeT7LGmOmuIutF4t3lA==",
"dev": true,
"license": "MIT",
"peer": true,
"dependencies": {
"@typescript-eslint/scope-manager": "8.35.0",
"@typescript-eslint/types": "8.35.0",
@@ -5278,7 +5268,6 @@
"resolved": "https://registry.npmjs.org/acorn/-/acorn-8.15.0.tgz",
"integrity": "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==",
"license": "MIT",
"peer": true,
"bin": {
"acorn": "bin/acorn"
},
@@ -7413,8 +7402,7 @@
"version": "0.0.1581282",
"resolved": "https://registry.npmjs.org/devtools-protocol/-/devtools-protocol-0.0.1581282.tgz",
"integrity": "sha512-nv7iKtNZQshSW2hKzYNr46nM/Cfh5SEvE2oV0/SEGgc9XupIY5ggf84Cz8eJIkBce7S3bmTAauFD6aysMpnqsQ==",
"license": "BSD-3-Clause",
"peer": true
"license": "BSD-3-Clause"
},
"node_modules/dezalgo": {
"version": "1.0.4",
@@ -7998,7 +7986,6 @@
"integrity": "sha512-GsGizj2Y1rCWDu6XoEekL3RLilp0voSePurjZIkxL3wlm5o5EC9VpgaP7lrCvjnkuLvzFBQWB3vWB3K5KQTveQ==",
"dev": true,
"license": "MIT",
"peer": true,
"dependencies": {
"@eslint-community/eslint-utils": "^4.2.0",
"@eslint-community/regexpp": "^4.12.1",
@@ -8516,7 +8503,6 @@
"resolved": "https://registry.npmjs.org/express/-/express-5.2.1.tgz",
"integrity": "sha512-hIS4idWWai69NezIdRt2xFVofaF4j+6INOpJlVOLDO8zXGpUVEVzIYk12UUi2JzjEzWL3IOAxcTubgz9Po0yXw==",
"license": "MIT",
"peer": true,
"dependencies": {
"accepts": "^2.0.0",
"body-parser": "^2.2.1",
@@ -9829,7 +9815,6 @@
"resolved": "https://registry.npmjs.org/hono/-/hono-4.12.7.tgz",
"integrity": "sha512-jq9l1DM0zVIvsm3lv9Nw9nlJnMNPOcAtsbsgiUhWcFzPE99Gvo6yRTlszSLLYacMeQ6quHD6hMfId8crVHvexw==",
"license": "MIT",
"peer": true,
"engines": {
"node": ">=16.9.0"
}
@@ -10108,7 +10093,6 @@
"resolved": "https://registry.npmjs.org/@jrichman/ink/-/ink-6.4.11.tgz",
"integrity": "sha512-93LQlzT7vvZ1XJcmOMwN4s+6W334QegendeHOMnEJBlhnpIzr8bws6/aOEHG8ZCuVD/vNeeea5m1msHIdAY6ig==",
"license": "MIT",
"peer": true,
"dependencies": {
"@alcalzone/ansi-tokenize": "^0.2.1",
"ansi-escapes": "^7.0.0",
@@ -13866,7 +13850,6 @@
"resolved": "https://registry.npmjs.org/react/-/react-19.2.4.tgz",
"integrity": "sha512-9nfp2hYpCwOjAN+8TZFGhtWEwgvWHXqESH8qT89AT/lWklpLON22Lc8pEtnpsZz7VmawabSU0gCjnj8aC0euHQ==",
"license": "MIT",
"peer": true,
"engines": {
"node": ">=0.10.0"
}
@@ -13877,7 +13860,6 @@
"integrity": "sha512-ePrwPfxAnB+7hgnEr8vpKxL9cmnp7F322t8oqcPshbIQQhDKgFDW4tjhF2wjVbdXF9O/nyuy3sQWd9JGpiLPvA==",
"devOptional": true,
"license": "MIT",
"peer": true,
"dependencies": {
"shell-quote": "^1.6.1",
"ws": "^7"
@@ -16027,7 +16009,6 @@
"resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.3.tgz",
"integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==",
"license": "MIT",
"peer": true,
"engines": {
"node": ">=12"
},
@@ -16250,8 +16231,7 @@
"version": "2.8.1",
"resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz",
"integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==",
"license": "0BSD",
"peer": true
"license": "0BSD"
},
"node_modules/tsx": {
"version": "4.20.3",
@@ -16259,7 +16239,6 @@
"integrity": "sha512-qjbnuR9Tr+FJOMBqJCW5ehvIo/buZq7vH7qD7JziU98h6l3qGy0a/yPFjwO+y0/T7GFpNgNAvEcPPVfyT8rrPQ==",
"devOptional": true,
"license": "MIT",
"peer": true,
"dependencies": {
"esbuild": "~0.25.0",
"get-tsconfig": "^4.7.5"
@@ -16425,7 +16404,6 @@
"integrity": "sha512-p1diW6TqL9L07nNxvRMM7hMMw4c5XOo/1ibL4aAIGmSAt9slTE1Xgw5KWuof2uTOvCg9BY7ZRi+GaF+7sfgPeQ==",
"devOptional": true,
"license": "Apache-2.0",
"peer": true,
"bin": {
"tsc": "bin/tsc",
"tsserver": "bin/tsserver"
@@ -16648,7 +16626,6 @@
"resolved": "https://registry.npmjs.org/vite/-/vite-7.2.2.tgz",
"integrity": "sha512-BxAKBWmIbrDgrokdGZH1IgkIk/5mMHDreLDmCJ0qpyJaAteP8NvMhkwr/ZCQNqNH97bw/dANTE9PDzqwJghfMQ==",
"license": "MIT",
"peer": true,
"dependencies": {
"esbuild": "^0.25.0",
"fdir": "^6.5.0",
@@ -16762,7 +16739,6 @@
"resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.3.tgz",
"integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==",
"license": "MIT",
"peer": true,
"engines": {
"node": ">=12"
},
@@ -16775,7 +16751,6 @@
"resolved": "https://registry.npmjs.org/vitest/-/vitest-3.2.4.tgz",
"integrity": "sha512-LUCP5ev3GURDysTWiP47wRRUpLKMOfPh+yKTx3kVIEiu5KOMeqzpnYNsKyOoVrULivR8tLcks4+lga33Whn90A==",
"license": "MIT",
"peer": true,
"dependencies": {
"@types/chai": "^5.2.2",
"@vitest/expect": "3.2.4",
@@ -17423,7 +17398,6 @@
"resolved": "https://registry.npmjs.org/zod/-/zod-3.25.76.tgz",
"integrity": "sha512-gzUt/qt81nXsFGKIFcC3YnfEAx5NkunCfnDlvuBSSFS02bcXu4Lmea0AFIUwbLWxWPx3d9p8S5QoaujKcNQxcQ==",
"license": "MIT",
"peer": true,
"funding": {
"url": "https://github.com/sponsors/colinhacks"
}
@@ -17867,7 +17841,6 @@
"resolved": "https://registry.npmjs.org/@grpc/grpc-js/-/grpc-js-1.14.3.tgz",
"integrity": "sha512-Iq8QQQ/7X3Sac15oB6p0FmUg/klxQvXLeileoqrTRGJYLV+/9tubbr9ipz0GKHjmXVsgFPo/+W+2cA8eNcR+XA==",
"license": "Apache-2.0",
"peer": true,
"dependencies": {
"@grpc/proto-loader": "^0.8.0",
"@js-sdsl/ordered-map": "^4.4.2"
@@ -17971,7 +17944,6 @@
"resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.3.tgz",
"integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==",
"license": "MIT",
"peer": true,
"engines": {
"node": ">=12"
},
packages/cli/src/acp/fileSystemService.ts
+1 -1
View File
@@ -14,7 +14,7 @@ export class AcpFileSystemService implements FileSystemService {
constructor(
private readonly connection: acp.AgentSideConnection,
private readonly sessionId: string,
private readonly capabilities: acp.FileSystemCapability,
private readonly capabilities: acp.FileSystemCapabilities,
private readonly fallback: FileSystemService,
) {}
packages/extensions/ux-extension/WELCOME.md
+4 -2
View File
@@ -50,8 +50,10 @@ When you're happy, just say "I'm ready to submit." I'll run the
structural integrity.
3. **Snapshots**: Fixes snapshots for CI using a neutral environment.
4. **Preflight**: Runs the full `preflight` suite.
5. **Commit Strategy**: Squashes your main feature into one commit, but keeps
review-fix commits separate to keep the diffs manageable for reviewers.
5. **Commit Strategy**: Squashes your main feature and ALL previous review
fixes into one commit, but keeps only the **very last** round of code review
comments as separate commits. This keeps the diffs manageable and fast for
reviewers (30 seconds vs. 10 minutes).
### **Phase 5: Handling Feedback**
packages/extensions/ux-extension/skills/_ux_finish-pr/SKILL.md
+5 -2
View File
@@ -48,8 +48,11 @@ You are a senior co-author assistant. Your goal is to ensure this PR passes CI o
- **Diff Verification**: After reverting, run `git diff origin/main...HEAD` on the specific reverted files to ensure their diff is completely empty.
### 7. Final Submission
- **Commit Strategy**: Squash commits for the main feature into a single Conventional Commit (e.g., `feat(ui): ...`), BUT keep code review fixes as separate commits. Do not squash review fixes into the main feature commit; reviewing the entire diff repeatedly is brutal for reviewers.
- **Commit Strategy**: Maintain a **Two-Tier** commit history to optimize for reviewer speed (30s vs 10m):
1. **Tier 1 (Base)**: A single squashed Conventional Commit (e.g., `feat(ui): ...`) containing the core feature and all *previously addressed* review cycles.
2. **Tier 2 (Latest)**: Separate, granular commits addressing only the **very last** round of reviewer feedback.
- **Action**: Use `git rebase -i` or `git reset --soft` to squash all older review-fix commits into the Tier 1 base. Ensure only the commits from the current (latest) review cycle remain as separate entries.
- **Push**: `git push origin HEAD --force-with-lease`.
- **Link**: Provide the GitHub PR link.
- **Link**: You MUST provide the full, clickable GitHub PR link (e.g., `https://github.com/google-gemini/gemini-cli/pull/23487`) as the final output of this skill. This allows the user to immediately verify the update.
**Note**: If any step fails, do NOT claim completion. Fix the issue and restart from Step 1.
pr-workflow-improvements.md
+70
View File
@@ -0,0 +1,70 @@
# PR Workflow Improvements: Lessons Learned & Skill Updates
During a recent PR review cycle, we encountered two significant workflow issues
that resulted in wasted review cycles, polluted diffs, and unnecessary churn. To
prevent these from recurring, we need to update our standard operating
procedures, specifically within the `_ux_finish-pr` skill.
## Problem 1: Blindspots in Fetching Reviewer Feedback
### The Issue
When instructed to address reviewer feedback, the agent relied on high-level PR
summaries (`gh pr view`) and top-level comments. It completely failed to fetch
or parse **inline, file-specific review comments**. As a result, critical
feedback (like removing unsafe type casts, fixing hardcoded arrays, and
reverting specific lines of code) was ignored. Furthermore, the agent did not
directly reply to the reviewer's comments to confirm resolution, leaving the
reviewer in the dark.
### The Solution for `_ux_finish-pr`
The skill must be updated to strictly mandate the retrieval and addressing of
_all_ review comments, especially inline ones.
**Proposed Skill Additions:**
- **Mandatory Comprehensive Fetching:** Require the use of `gh api graphql` or
advanced `gh pr view` parsing to explicitly extract _inline_ review comments,
which are often nested inside review objects and missed by basic commands.
- **Checklist Execution:** Mandate that the agent enumerates every single
comment from the reviewer and explicitly verifies its resolution against the
codebase.
- **Direct Engagement:** Require the agent to use the GitHub API to post a
direct reply to _every_ addressed inline comment (e.g., "Done. Extracted to a
helper.") to provide the reviewer with a clear audit trail.
---
## Problem 2: Git Base-State & Branch Management Errors
### The Issue
When the reviewer requested that specific configuration files be reverted to
their pre-PR state to remove them from the diff, the agent executed
`git checkout origin/main -- <files>`. Because `origin/main` had advanced with
new commits since the PR was originally branched, this action accidentally
pulled in _unrelated_ recent changes from `main`. This polluted the PR's diff,
causing it to include changes that had nothing to do with the feature, violating
the principle of atomic commits.
### The Solution for `_ux_finish-pr`
The skill must be updated to enforce strict Git merge-base practices when
reverting or referencing the original state of a PR.
**Proposed Skill Additions:**
- **Merge-Base Awareness:** Explicitly forbid blindly checking out files from
the tip of `origin/main` when attempting to restore a file's pre-PR state.
- **Safe File Reversion Protocol:** Instruct the agent to always find the true
branch point using `git merge-base` when reverting files to strip them from a
PR:
```bash
BASE_SHA=$(git merge-base origin/main HEAD)
git checkout $BASE_SHA -- <files_to_revert>
```
- **Diff Verification:** Add a mandatory validation step where the agent runs
`git diff origin/main...HEAD` on the specific reverted files to ensure their
diff is completely empty, confirming they have been successfully excised from
the PR.
worktrees-discussion.md
+192
View File
@@ -0,0 +1,192 @@
# Gemini CLI Git Worktrees Discussion Transcript
## Overview
This document captures a discussion regarding the new experimental native Git
Worktree support in the Gemini CLI and whether it makes the custom
`_ux_git-worktree` skill obsolete for the UX team.
### Skill Information
**Path:** `packages/extensions/ux-extension/skills/_ux_git-worktree/SKILL.md`
**High-Level Description:** The `_ux_git-worktree` skill manages a specific
"Base Folder Strategy" for the engineering team. Rather than nesting worktrees
inside a hidden `.gemini` folder, it enforces that all functional work occurs in
sibling sub-directories (e.g., `main/`, `feature-name/`). It automates creating
new task branches, checking out GitHub PRs into semantically named folders
(e.g., `pr-123-fix-core-bug`), and automatically running `npm install` to ensure
the isolated environment is immediately ready for development. It also handles
macOS sandbox pathing requirements.
---
## Discussion Transcript
**User:** Take a look at this new feature of Gemini CLI, and let me know if you
think it makes our git-worktree skill obsolete.
https://geminicli.com/docs/cli/git-worktrees/
**Gemini CLI:** Based on the documentation for the new native Git Worktree
feature and the specific rules defined in your `_ux_git-worktree` skill, **no,
it does not make your custom skill obsolete.**
While the new native feature is great for general-purpose isolation, your
`_ux_git-worktree` skill enforces highly specific, project-tailored workflows
that the native feature doesn't cover out-of-the-box:
1. **Directory Structure (The "Base Folder" Strategy):** The native CLI creates
worktrees hidden away in `.gemini/worktrees/`. Your skill strictly enforces
that worktrees must be **sibling directories** to `main/` (e.g.,
`../feature-name/`).
2. **Semantic PR Checkouts:** Your skill uses a custom `worktree-manager.sh`
script to automatically fetch PR titles and create human-readable, semantic
directory names (like `pr-123-fix-core-bug`). The native CLI does not
integrate with GitHub PRs in this way.
3. **Mandatory Environment Setup:** Your skill enforces a mandatory
`npm install` immediately after a worktree is created to ensure the
environment is ready for development.
4. **macOS Sandbox Management:** Because your worktrees live outside the
immediate repository container as sibling folders, your skill includes
specific logic to ensure the primary `../main/.git` path is added to the
trusted environment to bypass macOS sandbox restrictions.
**Recommendation:** The native `--worktree` flag is an excellent feature for
standard use cases, but for the rigorous, standardized workflows required by the
UX Extension in this repository, you should continue using your custom
`_ux_git-worktree` skill to maintain compliance with the "Base Folder"
architecture.
**User:** Let's back up a step. My goal is for the UX team that uses this
extension to be able to use git worktrees following the standard team convention
(i.e. the whole eng team will use this worktrees feature). We don't want to
duplicate or recreate the feature with our skill, nor do we want to diverge from
standard team practice. The exception is that I'd like the UX team (and end
users potentially) to be able to create and use worktrees with natural language.
Let's take a user-journey approach to designing the experience. Start by
creating a list of the use-cases/journeys that users will want to do with
worktrees. My current behavior is:
1. I want to create a new worktree to work on a new feature. I have a name in
mind, and I want to start from main. Its nice that I can use gemini cli
interactive mode and say 'new worktree called blahblah' and i dont have to
remember a specific syntax, but also the startup time maybe means I should
just learn the syntax. It seems simple. Its convenient that it runs npm
install to save me a step, but not critical.
2. I want to create a new worktree by cloning someone's branch/PR to my local
machine. Its easy for me to run gemini cli interactive mode and say 'create a
new worktree from http://PRURL and call it blahblah. Again, the npm install
is convenient. In this case Im not sure how to do this in noninteractive
mode.
3. I want to see all the worktrees ive created locally, and its handy i can look
at my folders, becuase it basically represents a list of my projects/features
im working on. Im not sure how this could be done in noninteractive mode, so
I would worry about losing my work in progress. its kind of confusing if my
worktrees are in gemini's hidden folder. It would be great if there was a way
to see my worktrees within gemini cli interactive and non interactive mode.
So as a worktree novice, and someone who has not tested this experimental
feature still, I may be misunderstanding things. Would you please create a list
of use-cases that includes mine, as well as any key ones im missing? Under each
use-case, identify whether its supported by the experimental feature in both
interactive and noninteractive modes.
**Gemini CLI:** This is a great approach. Stepping back to look at the user
journey is the best way to determine if a feature genuinely serves the team's
workflow or just adds unnecessary complexity.
Based on your current workflow, the documentation for the new experimental
feature, and standard Git worktree lifecycles, here is a breakdown of the key
user journeys.
### 1. Create a new worktree for a new feature (from `main`)
**User Goal:** Spin up an isolated environment to start fresh work, optionally
with a specific name, without messing up the primary `main` branch.
- **Experimental Native Feature (Non-Interactive):** **Supported.** You launch
Gemini with `gemini --worktree <name>`. It automatically creates a new branch
and a linked directory in `.gemini/worktrees/<name>`. _(Note: It does not
automatically run `npm install` like your current skill does)._
- **Experimental Native Feature (Interactive):** **Partially Supported.** You
cannot start a standard `gemini` session and then type a native slash command
(like `/worktree new`) to instantly pivot the current session into a worktree.
You must use the `--worktree` flag _when launching_ the CLI. However, once
inside any interactive session, you can always just ask the agent in natural
language to run standard `git worktree add` commands for you.
### 2. Create a worktree from a remote branch or PR
**User Goal:** Review a teammate's PR or continue work on a remote branch
without stashing current local changes.
- **Experimental Native Feature (Non-Interactive):** **Not Supported Natively.**
The `--worktree` flag only creates _new_ branches from your current HEAD. It
does not accept a PR URL or remote branch name. You would have to manually
fetch the remote branch and use standard `git worktree add` commands before
launching Gemini.
- **Experimental Native Feature (Interactive):** **Not Supported Natively.**
Again, the native feature lacks a "PR-to-worktree" pipeline. To do this with
natural language, you still rely on the AI agent running shell commands (which
is exactly what your `_ux_git-worktree` skill automates so reliably).
### 3. Discoverability: View existing local worktrees
**User Goal:** See a list of all active projects/features currently in progress.
- **Experimental Native Feature (Non-Interactive):** **Supported (but hidden).**
The native feature stores worktrees inside `.gemini/worktrees/`. Because this
is a hidden directory, you won't see your projects when doing a standard `ls`
in your file explorer. You have to explicitly check that hidden path or run
standard `git worktree list`.
- **Experimental Native Feature (Interactive):** **Supported.** You can ask the
agent, "What worktrees do I have open?" and it will run `git worktree list` to
tell you.
### 4. Resume work on an existing worktree _(Missing Use-Case)_
**User Goal:** Switch context back to a feature you started yesterday.
- **Experimental Native Feature (Non-Interactive):** **Supported.** You have to
manually `cd` into the hidden `.gemini/worktrees/<name>` directory and run
`gemini` again.
- **Experimental Native Feature (Interactive):** **Supported.** If you want to
resume the exact AI conversation you were having in that worktree, you
navigate to the hidden folder and launch with `gemini --resume <session_id>`.
### 5. Clean up / Delete a finished worktree _(Missing Use-Case)_
**User Goal:** After a PR is merged, delete the local branch and the isolated
folder to free up space.
- **Experimental Native Feature (Non-Interactive):** **Not Supported.** The
documentation explicitly states Gemini does not automatically clean up
worktrees. You must manually run `git worktree remove <path> --force` and
`git branch -D <branch>`.
- **Experimental Native Feature (Interactive):** **Not Supported Natively.** You
can ask the AI agent to run the cleanup commands for you, but there is no
native garbage collection.
---
### The Verdict for Your Team
You are not misunderstanding things; your concerns are spot on.
The new native `--worktree` feature is designed primarily for **AI
isolation**—giving the agent a safe sandbox so it doesn't break the user's main
repository while generating code. Because it hides these folders in
`.gemini/worktrees/`, it treats them as ephemeral AI scratchpads rather than
primary developer workspaces.
Your team's **"Base Folder Strategy"** (creating sibling folders like
`../feature-name/`) is designed for **Developer ergonomics**. It keeps projects
visible, integrates directly with PR workflows, and handles environment setup
(`npm install`).
**Conclusion:** The native feature does _not_ replace your skill. If you adopt
the native feature, your team will lose the PR checkout automation, the
automatic dependency installation, and the visibility of having worktrees as
top-level sibling folders. You should keep your `_ux_git-worktree` skill to
maintain your team's specific, natural-language-driven engineering standards.