agent-tools/doc/tool-parity.md

Tool parity: Google's agent vs Claude Code

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 (https://geminicli.com/docs/reference/tools/), Claude Code's toolset as of 2026-08, live probing of agy 1.1.9.

1. Already at parity — nothing to build

Capability	Claude Code	Gemini CLI
Read/write/edit files	Read / Write / Edit	read_file / write_file / replace
Find files / search text / list dirs	Glob / Grep	glob / grep_search / list_directory, plus read_many_files
Shell, incl. background processes	Bash (+ background tasks)	run_shell_command (+ background processes)
Web	WebFetch / WebSearch	web_fetch / google_web_search
Ask the user a structured question	AskUserQuestion	ask_user
Plan mode	EnterPlanMode / ExitPlanMode	enter_plan_mode / exit_plan_mode
Skills / slash commands	Skill (.claude/skills)	activate_skill (.gemini/skills)
Persistent memory	file-based memory dir	save_memory (simpler, but exists)
Todo/task tracking	TaskCreate/TaskUpdate/…	write_todos, tracker_* (experimental)
MCP servers + resources	MCP tools, ListMcpResources/ReadMcpResource	MCP tools, list_mcp_resources/read_mcp_resource
Subagents	Agent (background, custom types)	subagents (experimental) — weaker, see fanout below

Not worth replicating (harness-internal to Claude Code, no value as a CLI): ToolSearch, EndConversation, ReportFindings, ShareOnboardingGuide, DesignSync, remote cloud execution.

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.

3.1 cronr — scheduled/recurring runs (Claude: CronCreate/CronList/CronDelete, /loop)

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 '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
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.

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.

waitfor --cmd "curl -sf https://gitea.brasse-pc.eu/api/healthz" --interval 30s --timeout 20m
waitfor --cmd "ssh pi5 docker ps --format '{{.Names}}'" --matches 'gitea' --timeout 10m
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).

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 infra-Doc services/observability.md). notifyr is a thin client so every agent uses it the same way:

notifyr send --topic ci-fel --title "Build failed" --msg "agent-tools arm64 test: FAIL" --priority high
notifyr read --topic pi5-server-fel --since 2h     # poll mode: what has alerted lately?

read (ntfy's ?poll=1&since=…) is the underrated half: it lets an agent check what the infra has been complaining about before/after a change. Config (~/.config/notifyr/config.json): server URL + token.

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 NPM, e.g. pages.brasse-pc.eu) and prints the stable URL.

pagepub publish report.html --slug ci-report     → https://pages.brasse-pc.eu/ci-report/
pagepub publish notes.md --slug pi5-audit        # .md rendered to HTML with built-in template
pagepub list | rm <slug>

Requires the static host to exist first (small infra task; goes in infra-Doc + NPM proxy host via npmctl).

3.5 nbcell — Jupyter notebook editing (Claude: NotebookEdit)

.ipynb is JSON that's miserable to edit via replace. nbcell exposes cells as text:

nbcell list nb.ipynb                 # index, type, first line, exec count
nbcell show nb.ipynb 3               # cell source (and outputs with --outputs)
nbcell edit nb.ipynb 3 --from-file cell.py
nbcell add nb.ipynb --at 4 --type code --from-file new.py
nbcell rm nb.ipynb 7

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:

wtreectl new [--branch dev/foo]   # prints the new worktree path
wtreectl list
wtreectl clean                    # removes worktrees with no changes

Lets two agent sessions work in the same repo without trampling each other.

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 an output dir. A poor man's Workflow:

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.

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, services/observability.md, the per-service "operational quick-ref" blocks). These help any agent (Claude or Gemini) administer the 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.

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 /srv/storage1/gitea/actions_log/… on the Pi5. Wraps the Gitea REST + Actions API:

giteactl runs <repo> [--limit 5]          # status, branch, duration
giteactl log <repo> <run> [--job N]       # fetches + decompresses the zst log
giteactl wait <repo> [--timeout 30m]      # block until latest run finishes; exit 0 = green
giteactl wait-quiet [--max-active 1]      # block until ≤N heavy builds are running
giteactl release <repo> [<tag>]           # rolling-release assets + checksums

wait-quiet encodes the hard-learned rule "serialize pushes — >2 heavy builds take the Pi5 down": giteactl wait-quiet && git push. Composes with waitfor/notifyr.

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 loop once, properly:

fleet status          # containers (state, image, restarts), disk/mergerfs fill %, failed systemd units
fleet status --host brasse-linux01
fleet checks          # Uptime Kuma monitor states + last ntfy alerts (via notifyr read)

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.

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 findings:

envaudit check /srv/dockge-staks --env /srv/.env
  → UNDEFINED  ${STORAGE1}   used by media-stack/compose.yaml
  → INLINE     LDAP_ADMIN_PASSWORD  hardcoded in openldap/compose.yaml (should live in .env)
  → UNUSED     OLD_API_KEY   defined but referenced nowhere

Pure text analysis of compose files — safe to run anywhere, catches the two failure classes that have actually happened.

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:

reghelper ls                      # catalog + tags + image sizes
reghelper tags <image>
reghelper prune-plan --keep 2     # prints the delete+GC commands (does NOT run them)

prune-plan deliberately only prints the mutation commands for the supervised tmux flow — same pattern as the sudo policy.

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 per source, repo size, last check result) closes the loop — an agent can then verify backups instead of trusting them. Not a separate tool; park under fleet.

Cross-reference

/home/brasse/repos/dify-agent-tools/ already has a specced-but-unbuilt 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.

5. Suggested build order

1. ✅ notifyr — smallest, everything else composes with it, ntfy already runs. (built 2026-08-07)
2. ✅ giteactl — removes the biggest daily friction (CI logs + build serialization). (built 2026-08-07; private repos need an API token in the config)
3. ✅ waitfor + cronr — turns both agents into unattended operators. (built 2026-08-07)
4. fleet — replaces the hand-rolled health loops in every runbook.
5. envaudit, reghelper, pagepub, nbcell, wtreectl — as needed.
6. fanout — only if a concrete multi-agent need shows up.

Also built 2026-08-07 (outside this list, Björns direct request): svgc (svg-maker/) — SVG graphics from text, displayed in agent-helm via helmd share. Agy integration: the agent-tools skill + a tools section in ~/.gemini/config/AGENTS.md.