diff --git a/doc/tool-parity.md b/doc/tool-parity.md index ce7a8e9..835af72 100644 --- a/doc/tool-parity.md +++ b/doc/tool-parity.md @@ -1,13 +1,28 @@ -# Tool parity: Gemini CLI vs Claude Code +# Tool parity: Google's agent vs Claude Code -Goal: let Gemini CLI (the agent driven via `agent-helm`) do everything -Claude Code can, by building the missing capabilities as small CLI tools -in this repo. Gemini calls them through `run_shell_command`, so every -tool follows the house rules: **text in, verifiable artifacts out**, -single static Go binary, self-explanatory output. +Goal: let Google's agent CLI do everything Claude Code can, by building +the missing capabilities as small CLI tools in this repo. The agent +calls them through its shell tool, so every tool follows the house +rules: **text in, verifiable artifacts out**, single static Go binary, +self-explanatory output. + +**Which Google agent?** Legacy `gemini-cli` is auth-dead for personal +accounts (verified again 2026-08-05, see infra-Doc +`hosts/brasse-linux01.md`). The real target is **`agy` (Antigravity +CLI)** — live-tested in section 2, and its toolset differs from the +old Gemini CLI docs. Section 1's table is kept for reference since +Gemini CLI still exists in API-key mode. + +A design rule that fell out of the live test: **a dedicated binary +beats ad-hoc shell because of approval prefixes.** agy (like Claude +Code) allowlists commands by prefix — `notifyr …` can be approved once +and forever, while every hand-rolled `for i in $(seq …); do curl …` +loop is a unique string that needs fresh human approval. Small stable +CLIs are therefore not just convenience: they are what makes +unattended agent operation possible at all. Sources: Gemini CLI tools reference (), -Claude Code's toolset as of 2026-08. +Claude Code's toolset as of 2026-08, live probing of `agy` 1.1.9. ## 1. Already at parity — nothing to build @@ -29,19 +44,65 @@ Not worth replicating (harness-internal to Claude Code, no value as a CLI): `ToolSearch`, `EndConversation`, `ReportFindings`, `ShareOnboardingGuide`, `DesignSync`, remote cloud execution. -## 2. Gaps → tools to build +## 2. Live test 2026-08-05: `agy` (Antigravity CLI 1.1.9) + +Tested interactively in a tmux session (Google AI Pro account, model +Gemini 3.6 Flash). Its 19 built-in tools, self-enumerated: + +`ask_permission`, `ask_question`, `define_subagent`, `generate_image`, +`grep_search`, `invoke_subagent`, `list_dir`, `list_permissions`, +`manage_subagents`, `manage_task`, `multi_replace_file_content`, +`read_url_content`, `replace_file_content`, `run_command`, `schedule`, +`search_web`, `send_message`, `view_file`, `write_to_file`. + +What this changes vs the old Gemini CLI picture: + +- **agy has real subagents** (`invoke_subagent`/`define_subagent`/ + `manage_subagents` + `send_message`) and background-task management + (`manage_task`). → `fanout` demoted further; probably never needed. +- **agy has `schedule`** — one-shot timer or cron expression that wakes + the agent with a prompt (same idea as Claude's `ScheduleWakeup`). + Confirmed limits, from its schema: it cannot run commands itself, + it is **in-memory and dies with the session**, and it cannot reach + the phone. → `cronr` (persistent systemd timers) and `notifyr` are + still needed; `schedule` complements them within a session. +- **agy has `generate_image`** — a *reverse* gap: Claude Code has no + native image generation. Nothing to build; just worth knowing. +- No MCP-resource tools, no memory tool and no glob in its toolset + (grep/list_dir cover finding files). + +Behavior tests run in a scratch arena: + +| Test | Result | +|---|---| +| Enumerate tools | Clean list of 19 (above) | +| Edit a text file | Worked, auto-approved in trusted folder | +| Edit a Jupyter cell, keep `.ipynb` valid | **Passed** — it wrote a `python3 -c` json script rather than text-replacing. Notebook stayed valid. Cost: a per-command approval each time → `nbcell` demoted to nice-to-have (stable prefix + no ad-hoc python). | +| Wait for a file to appear | Worked via a hand-rolled `for … sleep 1` shell loop — a unique command string needing fresh approval. → exactly the `waitfor` case. | +| Asked agy which CLI tools *it* wants for the homelab | Its list: ntfy client, `tea` (Gitea CLI), `skopeo`/`crane` (registry), `ofelia`/cron daemon, `ctop`-style fleet status — near-1:1 with section 4, and it independently made the approval-prefix argument. | + +**Buy before build:** agy's suggestions overlap with off-the-shelf +tools. Evaluate first: `tea` (official Gitea CLI — but it does not read +the Pi5's zst action logs and has no `wait-quiet`, which stay +`giteactl`'s reason to exist, possibly as a thin layer *on top of* +`tea`), `skopeo`/`crane` (cover most of `reghelper` — remaining value +is prune *plans* and size summaries), `ctop` (interactive TUI, not +agent-friendly output — `fleet` still wins for agents). + +## 3. Gaps → tools to build Ordered by expected value. Each becomes its own folder + binary + README, per repo convention. -### 2.1 `cronr` — scheduled/recurring runs *(Claude: `CronCreate`/`CronList`/`CronDelete`, `/loop`)* +### 3.1 `cronr` — scheduled/recurring runs *(Claude: `CronCreate`/`CronList`/`CronDelete`, `/loop`)* -Gemini CLI has no way to schedule work. `cronr` manages **systemd user -timers** so an agent can create recurring or one-shot scheduled jobs -(including "run this prompt every morning" via `gemini -p …`). +agy's built-in `schedule` dies with the session (see section 2). +`cronr` manages **systemd user timers** so an agent can create +recurring or one-shot jobs that survive session exit and reboot +(including "run this prompt every morning" via `agy -p …`). ``` -cronr add nightly-ci-check --schedule "*-*-* 07:00" --cmd 'gemini -p "check CI status and notify"' +cronr add nightly-ci-check --schedule "*-*-* 07:00" --cmd 'agy -p "check CI status and notify"' cronr add once-reboot-check --at "2026-08-06 03:00" --cmd '…' # one-shot cronr list # name, schedule, next run, last result cronr logs nightly-ci-check # journalctl for the unit @@ -51,7 +112,7 @@ cronr rm nightly-ci-check Output prints the generated unit files so the result is verifiable. No daemon of its own — systemd does the running. -### 2.2 `waitfor` — block until a condition holds *(Claude: `Monitor`)* +### 3.2 `waitfor` — block until a condition holds *(Claude: `Monitor`)* Turns "poll every N seconds" into a single blocking tool call, so the agent doesn't burn turns polling. @@ -65,7 +126,7 @@ waitfor … --then 'notifyr send --msg "gitea is back up"' Exit 0 = condition met, exit 3 = timeout; last output is printed either way. `--then` runs a command on success (composes with `notifyr`). -### 2.3 `notifyr` — push notifications, send **and read** *(Claude: `PushNotification`)* +### 3.3 `notifyr` — push notifications, send **and read** *(Claude: `PushNotification`)* The ntfy server **already runs on the Pi5** and is the house-wide notification bus (topics like `Info`, `pi5-server-fel`, `ci-fel` — see @@ -81,7 +142,7 @@ notifyr read --topic pi5-server-fel --since 2h # poll mode: what has alerted agent *check what the infra has been complaining about* before/after a change. Config (`~/.config/notifyr/config.json`): server URL + token. -### 2.4 `pagepub` — publish an HTML/Markdown report to a URL *(Claude: `Artifact`)* +### 3.4 `pagepub` — publish an HTML/Markdown report to a URL *(Claude: `Artifact`)* Claude Code can publish reports as web pages; Gemini cannot. `pagepub` rsyncs a file to a static-file host on the Pi5 (nginx container behind @@ -96,7 +157,7 @@ pagepub list | rm Requires the static host to exist first (small infra task; goes in infra-Doc + NPM proxy host via `npmctl`). -### 2.5 `nbcell` — Jupyter notebook editing *(Claude: `NotebookEdit`)* +### 3.5 `nbcell` — Jupyter notebook editing *(Claude: `NotebookEdit`)* `.ipynb` is JSON that's miserable to edit via `replace`. `nbcell` exposes cells as text: @@ -109,7 +170,7 @@ nbcell add nb.ipynb --at 4 --type code --from-file new.py nbcell rm nb.ipynb 7 ``` -### 2.6 `wtreectl` — disposable git worktrees *(Claude: worktree isolation for agents)* +### 3.6 `wtreectl` — disposable git worktrees *(Claude: worktree isolation for agents)* Claude Code can give each subagent an isolated git worktree. `wtreectl` does the same for any agent: @@ -123,7 +184,7 @@ wtreectl clean # removes worktrees with no changes Lets two agent sessions work in the same repo without trampling each other. -### 2.7 `fanout` — parallel subagent orchestration *(Claude: `Workflow`, `Agent`)* — roadmap, not agreed +### 3.7 `fanout` — parallel subagent orchestration *(Claude: `Workflow`, `Agent`)* — roadmap, not agreed Runs N prompts as parallel headless agent processes (`gemini -p` / `claude -p`) with a concurrency cap, collecting each result as JSON in @@ -136,7 +197,7 @@ fanout run jobs.json --max 3 --out results/ Heavier than the other tools and overlaps with agent-helm's territory — park until there's a concrete need. -## 3. Suggested tools from infra history +## 4. Suggested tools from infra history Grounded in what the agent has already been doing per infra-Doc (`maintenance-and-gaps.md`, `services/source-control-and-deploy.md`, @@ -146,7 +207,7 @@ fleet, and they respect the read-only sudo policy (`ssh/claude-sudo-policy.md`): everything below is read-or-notify; mutations still go through Björn's supervised tmux flow. -### 3.1 `giteactl` — Gitea repos, Actions runs and CI logs +### 4.1 `giteactl` — Gitea repos, Actions runs and CI logs The biggest recurring friction. Today: CI status is polled ad hoc, and logs for private repos are only readable as zst files under @@ -165,7 +226,7 @@ giteactl release [] # rolling-release assets + checksums builds take the Pi5 down": `giteactl wait-quiet && git push`. Composes with `waitfor`/`notifyr`. -### 3.2 `fleet` — one-shot health snapshot of the whole homelab +### 4.2 `fleet` — one-shot health snapshot of the whole homelab Every service doc ends with the same hand-rolled loop over `ssh pi5-claude sudo claude-docker ps/inspect …`. `fleet` does that @@ -181,7 +242,7 @@ Read-only by construction (claude-docker wrapper + sudo allowlist), so it needs no new permissions. Output is a stable text table an agent can diff between runs. -### 3.3 `envaudit` — compose ↔ `.env` key auditor +### 4.3 `envaudit` — compose ↔ `.env` key auditor Grounded in a real incident (`${STORAGE1}` undefined in `/srv/.env` → bad mount, rollback) and in maintenance-and-gaps' inline-secret @@ -197,7 +258,7 @@ envaudit check /srv/dockge-staks --env /srv/.env Pure text analysis of compose files — safe to run anywhere, catches the two failure classes that have actually happened. -### 3.4 `reghelper` — docker-registry catalog & hygiene +### 4.4 `reghelper` — docker-registry catalog & hygiene The LAN registry (`192.168.0.19:5000`) has no UI, no auth and no cleanup story, and the backup plan explicitly wants it slimmed: @@ -211,7 +272,7 @@ reghelper prune-plan --keep 2 # prints the delete+GC commands (does NOT run `prune-plan` deliberately only *prints* the mutation commands for the supervised tmux flow — same pattern as the sudo policy. -### 3.5 Backup status reader — once Backrest/restic exists +### 4.5 Backup status reader — once Backrest/restic exists future-plans.md has the whole Backrest+restic design chosen but unbuilt. When it lands, a `fleet backups` subcommand (last snapshot age @@ -226,7 +287,7 @@ set of FastAPI tools (file/image sorting, face recognition, ST-card export…) for the Dify platform. Different runtime (HTTP tools vs CLI binaries), same philosophy — don't duplicate those here. -## 4. Suggested build order +## 5. Suggested build order 1. `notifyr` — smallest, everything else composes with it, ntfy already runs. 2. `giteactl` — removes the biggest daily friction (CI logs + build serialization).