Round 44: Gemini CLI capability map (auto-loop-26)#122
Conversation
…omplete Adds docs/research/gemini-cli-capability-map.md as the third CLI capability map (verified against gemini 0.38.2). Audience is other AI pilots that may want to orchestrate Gemini as a sub-substrate. Completes the three-substrate pilot reference set that the Claude (v2.1.116) and Codex (v0.122.0) maps already pointed at as "future companion docs". Cross-substrate triangulation discipline now fully documented. Distinctive Gemini surfaces captured: - --approval-mode plan (read-only analysis mode, no CLI equivalent in Claude or Codex maps) - Extensions / skills / hooks as three parallel ecosystem mechanisms, with hooks migrate explicitly bridging from Claude Code - ACP protocol as Gemini's pilot-bridge analog to MCP-serve on the other CLIs - Worktree isolation as a top-level --worktree flag Comparison table now three-wide (Claude / Codex / Gemini) with 15 concerns mapped; structural observation on how each CLI lands the interactive/non-interactive split differently (flag-centric vs subcommand-heavy vs flag-with-interactive- default). Descriptive, not prescriptive — routing decisions remain out-of-scope; this doc describes surfaces only. Reviewer: Architect (Kenji); Aarav (skill-map hygiene); Nazar (no credentials in prose); external auditors via docs/research/ — capability maps are safe-to-publish subset per Copilot-review memory-ref scope-explicit discipline.
![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: 3c4bc929d3
ℹ️ 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".
| | YOLO / auto-all | `--dangerously-skip-permissions` | `--dangerously-bypass-approvals-and-sandbox` | `-y` / `--yolo` / `--approval-mode yolo` | | ||
| | Worktree isolation | Agent param `isolation: "worktree"` | (not a top-level flag) | `-w` / `--worktree` | | ||
| | Structured output | `--json-schema` + `--output-format=json` | `--output-schema` + `--json` | `-o text/json/stream-json` | | ||
| | Event-stream output | `--output-format stream-json` | (not surfaced) | `-o stream-json` | |
There was a problem hiding this comment.
The comparison currently says Codex does not surface event-stream output, but the sibling Codex map explicitly documents codex exec --json as emitting JSONL events (docs/research/openai-codex-cli-capability-map.md lines 51-56). This mismatch can mislead orchestration pilots into skipping a supported streaming path and building unnecessary workarounds; the table should reflect that Codex streams events via --json even without a stream-json flag name.
Useful? React with 👍 / 👎.
| | Structured output | `--json-schema` + `--output-format=json` | `--output-schema` + `--json` | `-o text/json/stream-json` | | ||
| | Event-stream output | `--output-format stream-json` | (not surfaced) | `-o stream-json` | | ||
| | MCP serve (pilot bridge) | `claude mcp serve` | `codex mcp-server` | `--acp` (ACP protocol, not MCP) | | ||
| | MCP registry (as client) | `claude mcp add/list/...` | (via config.toml) | `gemini mcp add/list/enable/disable` | |
There was a problem hiding this comment.
This row says Codex MCP registry is only "via config.toml", but the existing Codex capability map documents dedicated codex mcp management commands (add/list/remove/...) as part of the CLI surface (docs/research/openai-codex-cli-capability-map.md lines 146-147). Keeping the row as-is pushes pilots toward direct config edits instead of the supported command interface, which makes automation more brittle when config structure changes.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Pull request overview
Adds a third CLI capability map for Google Gemini CLI to complete the Claude/Codex/Gemini “pilot substrate” reference set in docs/research/.
Changes:
- Introduces
docs/research/gemini-cli-capability-map.mddocumenting Gemini CLI v0.38.2 surfaces (interactive vs-p, model selection, approval modes, worktrees, extensions/skills/hooks, MCP/ACP). - Adds a three-way comparison table (Gemini vs Claude vs Codex) and orchestration calling patterns aligned with the existing maps.
| on 2026-04-22. Revise when the CLI version changes materially. | ||
|
|
||
| **Audience:** other AI pilots (Claude Code CLI, OpenAI Codex | ||
| CLI, Amara ChatGPT-surface, Playwright-driven agents) that may |
There was a problem hiding this comment.
Operational standing rule prohibits direct contributor/agent names in docs; this file introduces the proper name "Amara" ("Amara ChatGPT-surface") instead of a role reference. Please rewrite to a role-based term (e.g., "ChatGPT surface") or link to a formally defined non-personal concept name, to keep docs stable across contributor turnover (docs/AGENT-BEST-PRACTICES.md:284-292).
| CLI, Amara ChatGPT-surface, Playwright-driven agents) that may | |
| CLI, ChatGPT surface, Playwright-driven agents) that may |
| cross-substrate safety-check discipline (Amara-register) | ||
| extends to include Gemini as a first-class voice. |
There was a problem hiding this comment.
The phrase "Amara-register" is used without any local definition or link target, and it also repeats the use of the proper name "Amara" which conflicts with the repo’s “no name attribution in docs” standing rule (docs/AGENT-BEST-PRACTICES.md:284-292). Please either replace it with a role-reference / generic term, or add a concrete link to the register/spec that defines this discipline.
| cross-substrate safety-check discipline (Amara-register) | |
| extends to include Gemini as a first-class voice. | |
| cross-substrate safety-check discipline extends to include | |
| Gemini as a first-class voice. |
The "Session resume" row contained -r [latest|N] where the literal pipe was interpreted by markdownlint as an extra table column separator (5 columns, expected 4). Escaping with backslash fixes the column count without changing the semantic meaning (Gemini's -r accepts "latest" or an index number). Caught by lint (markdownlint) check on PR #122.
| | Mode | Behaviour | | ||
| |-------------|-----------------------------------------------------------------| | ||
| | `default` | Prompt for approval on each tool call. | | ||
| | `auto_edit` | Auto-approve edit tools (file write/edit); ask for the rest. | | ||
| | `yolo` | Auto-approve all tools (same as `-y` / `--yolo`). | | ||
| | `plan` | Read-only mode. The agent analyses and plans but takes no writes. | |
There was a problem hiding this comment.
The approval-mode table is written with a double leading pipe (|| ...). In standard Markdown this renders an empty first column and can misalign the table. Use a single leading | for each row (and keep the same number of columns across rows).
| | Concern | Claude Code | OpenAI Codex | Google Gemini | | ||
| |-------------------------------|-----------------------------------------------|---------------------------------------------------|----------------------------------------------| | ||
| | Non-interactive | `--print` / `-p` (flag) | `codex exec` (subcommand) | `-p` / `--prompt` (flag) | | ||
| | Model/capability lever | `--effort low..max` (discrete tiers) | `-m` / `-c model="..."` + `--profile` | `-m` / `--model` | |
There was a problem hiding this comment.
The comparison table also uses || at the start of each row, which typically creates an unintended empty first column in Markdown renderers. Switch to a single leading | per row so the table renders consistently with the other capability maps.
| gemini -p -m "$M" --approval-mode plan \ | ||
| "$TASK_PROMPT" > "/tmp/run-$M.txt" |
There was a problem hiding this comment.
In the stepdown loop example, -p/--prompt appears before other flags and the prompt argument is provided later. Many CLIs require an option's value to immediately follow the option, so this can be parsed as -p receiving -m (or --approval-mode) as its value. Reorder so the prompt value immediately follows -p (or use --prompt "..." at the end).
| gemini -p -m "$M" --approval-mode plan \ | |
| "$TASK_PROMPT" > "/tmp/run-$M.txt" | |
| gemini -p "$TASK_PROMPT" -m "$M" --approval-mode plan \ | |
| > "/tmp/run-$M.txt" |
| gemini -p --approval-mode plan \ | ||
| "map the public API of $REPO and list undocumented surfaces" | ||
| ``` |
There was a problem hiding this comment.
This example has gemini -p --approval-mode plan ... with the prompt string coming later. If -p requires an immediate argument, this will misparse (--approval-mode becomes the prompt). Place the prompt right after -p/--prompt, or move -p to the end immediately before the quoted prompt.
| event-by-event consumption: | ||
|
|
||
| ```bash | ||
| gemini -p -o stream-json "$PROMPT" | \ |
There was a problem hiding this comment.
The stream-json example uses gemini -p -o stream-json "$PROMPT". If -p expects its value immediately, -o may be consumed as the prompt value. Consider ordering flags as gemini -o stream-json -p "$PROMPT" (or --output-format ... --prompt ...) to avoid ambiguous parsing.
| gemini -p -o stream-json "$PROMPT" | \ | |
| gemini -o stream-json -p "$PROMPT" | \ |
| gemini -w agent-run-$(date +%s) -p --approval-mode auto_edit \ | ||
| "implement the plan in PLAN.md" |
There was a problem hiding this comment.
The worktree example has -p before --approval-mode auto_edit, with the prompt argument on the next line. If -p requires an immediate value, this will likely treat --approval-mode as the prompt and fail. Reorder so -p is immediately followed by the quoted prompt (or use --prompt).
| gemini -w agent-run-$(date +%s) -p --approval-mode auto_edit \ | |
| "implement the plan in PLAN.md" | |
| gemini -w agent-run-$(date +%s) -p \ | |
| "implement the plan in PLAN.md" --approval-mode auto_edit |
Covers: wink-validation watch row PR #124 (rule-application promotion, path-ii distinct from pattern-recognition path-i), absorb-and-contribute community-dependency discipline named (harness block on npm install honored as aligned-with-discipline), upstream-contribution-to-any-repo authorization, AI-identification simplification ("just say it's AI") + AceHack handle preservation, ceremony-dial-down directive, five-tier degradation ladder extended with poor-tier (survival concern vs cheap's budget concern), Twitter + DeBank social-substrate grant, PR #122 Gemini-map rebase to clear BEHIND, Grok-CLI three-path substrate-class analysis. Fourth consecutive tick holding accounting-lag same-tick- mitigation discipline (substrate-improvements + substrate- accounting in same session, separate PRs). First tick to exercise explicit rule-application promotion (executing a stated count-threshold when it fires, rather than deferring the call to maintainer). Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
Records: Grok CLI capability map drafted as pre-install sketch (PR #126, on branch add-grok-cli-capability-map-sketch), two upstream PR targets pre-triaged inline (ESLint 9 flat-config migration; import type fix in src/utils/model-config.ts), PR #122 + #124 rebased to clear BEHIND after PR #125 merged, live wink-validation on source-tree-inference methodology (occurrence-1 of new sub-pattern, noted not filed), and late-tick Escro directive captured (maintain every dep → microkernel OS endpoint, grow-our-way-there no-deadlines cadence — memory filed, open questions flagged to maintainer, no BACKLOG row yet per stated cadence). Compoundings-per-tick = 10. Open-PR-refresh-debt cleared 2 (PRs #122, #124). Hazardous-stacked-base-count = 0. Nineteenth clean auto-loop tick across compaction. Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
|
Superseded by PR #365 (Gemini CLI v0.39.1 capability map — merged this session) and PR #367 (cross-harness skill-discovery verified). The content of this earlier auto-loop-26 Gemini CLI capability map has been fully replaced by the 2026-04-24 research that cited live probes on |
Pull request was closed
Summary
docs/research/gemini-cli-capability-map.mdas the third CLI capability map (verified againstgemini --version0.38.2).--approval-mode plan(read-only),extensions/skills/hooksecosystem split withhooks migratebridging from Claude Code,--acpas the pilot-bridge analog,-w/--worktreeas a top-level flag.Test plan
gemini --version→ 0.38.2 (pinned in Status line)gemini --helptop-level surface capturedgemini mcp --help/extensions --help/skills --help/hooks --helpsubcommands enumerateddocs/EXPERT-REGISTRY.md(not human-contributor-name prose per BP-11)Reviewer: Architect (Kenji); Aarav (skill-map hygiene); Nazar (no credentials); external auditors via
docs/research/(capability maps are safe-to-publish subset per Copilot-review memory-ref scope-explicit discipline).