research: Gemini CLI v0.39.1 capability map — peer-agent onboarding#365
Merged
research: Gemini CLI v0.39.1 capability map — peer-agent onboarding#365
Conversation
There was a problem hiding this comment.
Pull request overview
Adds a research capability map for Google’s Gemini CLI (v0.39.1) to complement the existing Claude Code and OpenAI Codex CLI maps, with a focus on cross-harness onboarding and future factory integration considerations.
Changes:
- Added a new Gemini CLI capability map documenting install/auth, command surface, key flags, and config layout.
- Included a Claude/Codex/Gemini comparison table and deferred “factory integration shape suggestions”.
- Added sources and “not yet verified” items to guide future implementation work.
AceHack
added a commit
that referenced
this pull request
Apr 24, 2026
2 tasks
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: c5929bb000
ℹ️ 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".
AceHack
added a commit
that referenced
this pull request
Apr 24, 2026
AceHack
added a commit
that referenced
this pull request
Apr 24, 2026
Thread 59ZZRu — softened the skills-format claim. The module- doc section asserted identity with the Agent Skills open standard (and OpenAI's equivalent) as fact, but the Open questions list flagged that identity as unverified. Replaced with an "appears to" framing + pointed at the Gemini CLI docs page as the citation trail, so the stated fact and the listed question stop contradicting each other. Thread 59ZZSQ — removed a citation that pointed outside the repo. The version-numbers-websearch memory lives in my factory-personal memory store (`~/.claude/...`), not in `memory/` inside this repo, so readers following the reference would hit a dead path. Kept the discipline statement, dropped the broken pointer. Thread 59ZZSe — fixed an ambiguous CLI example. `-w` / `--worktree` takes an optional name argument, so `gemini -w "<prompt>"` would bind the prompt string to the worktree name rather than executing it. Rewrote the worktree vs. no-worktree example to pass the prompt via `-p` explicitly and call out the `-w` parse-order caveat inline. All three are doc-only corrections. No CLI behaviour implied by the doc changed.
AceHack
force-pushed
the
research/gemini-cli-capability-map-otto-223
branch
from
e835014 to
7dabce8
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 7dabce8721
ℹ️ 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".
Third agent CLI mapped to pair with the existing Claude Code
(2.1.116) + Codex (0.122.0) capability maps. Motivated by the
human maintainer's just-installed `gemini` binary on his
personal account and directive to "map it out like codex and
your own claude, get it to build it's skills, plugins,
whatever, start off with research and maping."
What's in the map:
* Install + identity (binary on /opt/homebrew/bin/gemini)
* Command surface: `skills`, `extensions`, `mcp`, `hooks`
(+ top-level REPL and headless `-p` modes)
* Runtime flags worth knowing: `-w/--worktree` built-in,
`--approval-mode {default|auto_edit|yolo|plan}`,
`-o {text|json|stream-json}`, `--policy`,
`--acp` agent-coordination-protocol (experimental)
* Config-tree layout: `~/.gemini/` (user) vs `.gemini/`
(workspace) vs `.agents/skills/` (cross-tool alias)
* Skill precedence: Workspace > User > Extension
* Key cross-harness wins: `gemini hooks migrate` imports
Claude Code hooks; `gemini extensions validate` is
out-of-the-box structural lint; `.agents/skills/` is a
cross-harness convention shared with Claude + Codex via
the Agent Skills open standard
* Factory integration shape (deferred design)
* Open questions (7) + not-yet-verified (3)
Not a factory-integration PR — this is the capability inventory
feeding the eventual design PR. No factory code changes, no
skills added.
Thread 59ZZRu — softened the skills-format claim. The module- doc section asserted identity with the Agent Skills open standard (and OpenAI's equivalent) as fact, but the Open questions list flagged that identity as unverified. Replaced with an "appears to" framing + pointed at the Gemini CLI docs page as the citation trail, so the stated fact and the listed question stop contradicting each other. Thread 59ZZSQ — removed a citation that pointed outside the repo. The version-numbers-websearch memory lives in my factory-personal memory store (`~/.claude/...`), not in `memory/` inside this repo, so readers following the reference would hit a dead path. Kept the discipline statement, dropped the broken pointer. Thread 59ZZSe — fixed an ambiguous CLI example. `-w` / `--worktree` takes an optional name argument, so `gemini -w "<prompt>"` would bind the prompt string to the worktree name rather than executing it. Rewrote the worktree vs. no-worktree example to pass the prompt via `-p` explicitly and call out the `-w` parse-order caveat inline. All three are doc-only corrections. No CLI behaviour implied by the doc changed.
…ef polish
Thread 59ZbbF (Codex P2) — `-w/--worktree` feature gate. The
flag is gated on `experimental.worktrees` in settings.json;
without that toggle the CLI rejects `-w`. Rewrote the flag's
section to call out the gate + cite the git-worktrees doc +
note it landed in v0.37.0 (2026-04-08). WebSearch verified
against geminicli.com/docs/cli/git-worktrees/ on 2026-04-24.
Thread 59ZbbM (Codex P2) — `-w "<prompt>"` example ambiguity.
Already addressed in the prior-commit rewrite that added an
explicit `-p` for the prompt + the `-w` parse-order caveat;
re-push associates the finding with the current corrected
text.
Thread 59ZfJJ (Copilot P1) — table-cell pipe rendering. The
backslash-escaped `\|` inside a backtick code-span renders
literally in GitHub-flavored Markdown. Rephrased the cell to
plain prose ("`-o` with `text`, `json`, or `stream-json`")
so there are no pipes inside backticks.
Thread 59ZfJh (Copilot P1) — "Otto-215 directive" xref. The
tag exists in memory + session history but not in-repo, so
readers can't follow it. Replaced with "the standing factory
direction" so the underlying discipline (factory-authored
plugins live in-source + target eventual cross-marketplace
publication) stays stated without a dangling handle.
Thread 59ZfQI (Codex P2) — extension-tree paths. The tree
previously showed `.mcp.json` + `hooks.json` at root; actual
Gemini structure puts MCP servers in the `mcpServers` field
inside `gemini-extension.json`, and hooks in `hooks/hooks.json`.
Rewrote the tree to match, added `policies/*.toml` (auto-loaded)
and TOML-ified `commands/`, cited the extension reference as
source-of-truth. WebSearch verified against
geminicli.com/docs/extensions/reference/ on 2026-04-24.
AceHack
force-pushed
the
research/gemini-cli-capability-map-otto-223
branch
from
7dabce8 to
6ca8676
Compare
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 6ca8676a6b
ℹ️ 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".
Comment on lines
+261
to
+262
| two shapes is the sandbox / no-sandbox diff carved into a | ||
| single tool invocation. |
There was a problem hiding this comment.
This sentence labels the two command shapes as a "sandbox / no-sandbox" comparison, but both examples only differ by --worktree and do not toggle --sandbox. That mismatch can invalidate onboarding experiments by causing readers to attribute observed behavior to sandboxing when the tested variable is actually worktree isolation, which skews conclusions drawn from the documented A/B procedure.
Useful? React with 👍 / 👎.
4 tasks
AceHack
added a commit
that referenced
this pull request
Apr 24, 2026
…/data split (#367) The prior Gemini capability map claimed `.agents/skills/` was a cross-harness alias shared by Claude Code + Codex + Gemini. The human maintainer flagged that the factory had earlier problems with skills outside each harness's canonical home and asked for a direct test before committing to anything cross- harness. Ran live discovery probes on 2026-04-24 with a single skill placed at `.agents/skills/agents-only-prove/SKILL.md` in an isolated tmp workspace (no `.claude/`, `.codex/`, `.gemini/` skill dirs present), asked each harness whether it could see the skill by name: Claude Code 2.1.116 -> NO (skill absent from listed set) OpenAI Codex 0.124.0 -> YES (codex exec returned YES) Gemini CLI 0.39.1 -> YES (gemini -p returned YES) Updated the Gemini map: * Replaced the "cross-harness alias" assertion with a verified-status table + probe-method column. * Added a "Cross-harness skill-discovery reality" section with the verified matrix. * Added a "Generic vs. harness-specific skills" section documenting the behaviour / data split discipline the factory uses: each harness gets its own SKILL.md in its canonical directory (behaviour layer, tuned per harness), all three reference the same `docs/` content (data layer, shared). Thinner-than-holding-the-data but not so thin they just proxy elsewhere. * Stated the human-maintainer's 2026-04-24 policy call: until all three harnesses support a common home, keep each skill in its canonical home. No factory-code change; doc-only accuracy correction. The superseded PR #365 merged with the earlier content; this PR lands the cross-harness additions as a separate doc update so the drift between map and empirical behaviour is closed.
6 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Third agent CLI mapped to pair with the existing Claude Code
(2.1.116) and Codex (0.122.0) capability maps. Opens the door
to Gemini-as-peer-reviewer in the cross-AI-triangulation
pattern, and to factory-authored Gemini extensions / skills
that live in-source per the Otto-215 marketplace-targeting
directive.
What's in the map
/opt/homebrew/bin/geminiv0.39.1on the human maintainer's account as of 2026-04-24, OAuth
against personal Google account
skills,extensions,mcp,hooks(plus top-level REPL and headless
-pmodes)to
-w/--worktree(built-in git worktree isolation),--approval-mode {default|auto_edit|yolo|plan}, and-o {text|json|stream-json}for agent-to-agent orchestration~/.gemini/(user) vs.gemini/(workspace) vs
.agents/skills/(cross-tool alias sharedwith Claude Code + Codex via the Agent Skills open standard)
gemini hooks migrateimports Claude Code hooks out ofthe box
gemini extensions validateis an out-of-the-boxSTRUCTURAL LINT (no more hand-rolled manifest check)
.agents/skills/= one skill dir serving all threeharnesses
design, not this PR):
.agents/skills/for cross-harnessskills,
.gemini-extension/gemini-extension.jsonin-sourcefor Gemini-specific extensions,
gemini extensions validateas pre-commit lint, the
-w/ no--wworktree-A/B patternthe human maintainer explicitly asked for
Open questions
Anthropic's SKILL.md?
lesson generalises)
Not yet verified
version-numbers-websearch discipline says re-verify at any
implementation PR time per Otto-213)
gemini-extension.jsonschema stabilityVerification
gemini --helpcapturedgemini skills list/extensions list/mcp listprobed live
~/.gemini/+~/.agents/skills/inspected for layoutformat workspace .gemini directory 2026" cross-checked
against live probes
What this PR does NOT do
follow-up PR (likely after the Gemini BACKLOG row from this
tick is triaged).
consideration per Otto-108: some Claude-Code-specific
skills may legitimately not cross-port; that's a per-skill
decision, not a blanket port.
~/.gemini/extensions/from within factory code. User-level install is per-machine.
Test plan
resolve to actual repo paths
shape before any follow-up design PR lands