refresh-backends
Assess and update agentgrep's backends and storage catalogue against the agent clients installed on this machine (claude, codex, cursor-agent, gemini, agy, grok, pi, opencode, VS Code, Cursor IDE, Antigravity IDE, Windsurf), versioning what each client version stores. Use when asked to sweep, refresh, audit, or update the backends or storages, check for drift after a client upgrade, observe a new client version, or record which version a storage change landed in.
- License 许可
- MIT
- 所属仓库
- tony/agentgrep
- 最近更新
- 2026-11-15
- Stars
- ★ 9
- Forks
- 1
01 前言 Front Matter
- name
- refresh-backends
- description
- Assess and update agentgrep's backends and storage catalogue against the agent clients installed on this machine (claude, codex, cursor-agent, gemini, agy, grok, pi, opencode, VS Code, Cursor IDE, Antigravity IDE, Windsurf), versioning what each client version stores. Use when asked to sweep, refresh, audit, or update the backends or storages, check for drift after a client upgrade, observe a new client version, or record which version a storage change landed in.
- argument-hint
- [agent ...]
03 SKILL.md 正文
Refreshing agent backends
Each installed client version gets a schema-only manifest in
docs/_observations/<agent>/<version>.toml, and the catalogue stamps in
src/agentgrep/store_catalog/ must match the newest one. A refresh records
new versions, catalogues what changed, ties each change to the version that
first showed it, and proves search still works and is no slower.
Arguments
$ARGUMENTS lists agent ids as uv run scripts/observe_stores.py --help
prints them; --agent takes one id, so run each command once per id. Empty
means --agent all. "In scope" below means these agents.
Rules
- Agent homes,
/mnt/cincluded, are read-only: read files and run--version, never another client subcommand. NoHOME=overrides. - No prompt text, PII, or real home paths anywhere: manifests use
${HOME}tokens, docs pages keep their existing~/form. - Never hand-edit a manifest, and never rewrite or delete one for a version that is no longer installed. One that already leaks a path is the user's call to scrub: report it.
- Never push, tag, or open a PR. No backup branches.
- If the user asked for
CHANGES, its entries land last, in their owndocs(CHANGES) <description>commit under the existing unreleased heading, with no version lead paragraph. Otherwise leaveCHANGESalone and list the entries it needs in the report.
Commits
Commit in this order, skipping a kind with nothing in it. Subjects stay at
50 characters or fewer, and bodies take the why:/what: form from
.github/WRITING.md.
agentgrep(fix[observe]): ...when the observer itself misbehaves, with a test intests/test_storage_observations.py.agentgrep(chore[catalog]): Refresh observed stamps: every new manifest, restamp, and version line. The body names each agent and version recorded, and says earlier manifests stay untouched.agentgrep(feat[catalog]): Catalogue <n> new stores: new rows, thecatalog_versionbump, and the touched agents re-observed at their unchanged versions.agentgrep(feat[<agent>]): ...oragentgrep(fix[<agent>]): ...: adapter changes with their fixture and test.docs(backends): Correct claims the sweep disproved.docs(backends): Record storage changes by version.docs(backends): Observe <Agent> <version>for a client that updates mid-sweep: its manifest, restamp, version lines, and entry in one commit.docs(CHANGES) <description>, when the user asked for it.
Steps
-
Worktree. Unless the user names a branch, branch from fresh
origin/masterinto a sibling worktree, with the session date asYYYYMMDD. Work only there.$ git fetch origin$ git worktree add --no-track -b storages-YYYYMMDD ../agentgrep-storages-YYYYMMDD origin/master -
Baseline. Exit 1 means drift. Table each in-scope agent's documented version (newest manifest;
_<AGENT>_OBSERVED_VERSIONinsrc/agentgrep/store_catalog/<agent>.py, hyphens as underscores) against the installed version this prints.$ uv run scripts/observe_stores.py check --agent <id>windsurfhas no version probe, sochecknever reports its upgrades. ReadwindsurfVersionfrom the newest~/.windsurf-server/bin/<commit>/product.json, and decide whether that build wrote its catalogued data before stamping it. The firstcheckafter the IDE probes landed reports each IDE once as drift from itsunknown.toml. -
Observe each in-scope agent whose version changed or that
checkreports drifting. A new version writes a new manifest; drift at the same version rewrites that version's file. A refusal to writeunknown.tomlover a versioned manifest means the version probe failed: report it, never work around it.$ uv run scripts/observe_stores.py observe --agent <id>A new version diffs against the previous manifest:
$ git diff --no-index docs/_observations/<id>/<old>.toml docs/_observations/<id>/<new>.tomlA same-version rewrite diffs against the commit:
$ git diff -- docs/_observations/<id>/<version>.toml -
Triage every diff line:
- Before calling a key added or removed, check older manifests. The observer samples each store's newest 40 files, so keys drift in and out of the sample without a schema change.
- Version changed, shape didn't: restamp only.
- New unclaimed path: add a
catalog_onlyrow, orprivatewhen it holds credentials or keys. A new home directory for the agent also goes in itsAgentProbe.homesinscripts/observe_stores.py. - Changed discriminator, keys, tables, or columns in a store agentgrep
reads: update the descriptor and adapter, add a redacted fixture under
tests/samples/<agent>/<store_id>/, and show the new test failing before it passes. source_count <old> -> <new>on a store agentgrep reads means its files moved, were renamed, or were recompressed, and search lost them. Make discovery and the adapter follow them, or, when that needs a design, list it first under what was left undone.- New readable conversation store: give it the
primary_chatorsupplementary_chatrole, neverprompt_history, so default search does not open it. - A file newer than its newest record is an empty draft session, not a parse failure.
- Re-read the agent's backend page and each touched row's
schema_notes, and correct any claim the observation disproves.
Any descriptor add, removal, or reshape follows "Adding or updating a store" in
docs/dev/storage-catalog.md, including itsupstream_ref(pinned to an upstream commit,github.com/<org>/<repo>@<sha>/...) orsample_record. Bumpcatalog_versionand re-observe the agent in that same commit. If the unclaimed list now names the children of a directory, the new row claims that directory by name without covering its children: put a<placeholder>or glob at that level of its pattern. -
Restamp only what you re-read:
_<AGENT>_OBSERVED_VERSION, keeping its prefix (claude-code v...)._<AGENT>_OBSERVED_AT,_CATALOG_CAPTURED_AT, and the date in the comment above the dated block, insrc/agentgrep/store_catalog/_common.py.- The
observed_versionline whereverdocs/backends/<agent>.mdanddocs/dev/storage-catalog.mdcarry one. Windsurf's page isdocs/backends/unsupported/windsurf.md.
An agent that is not installed, or whose version you could not read, keeps its version and date: move its
_OBSERVED_ATout of the dated block with a comment saying why, as Windsurf's is. When the gate fails on a row that keeps its ownobserved_at, re-verify that row on disk before pointing it at the module constant. -
Version the change under
## Changes by versionon the agent's page, adding that section, with the opening paragraph other pages use, where it is missing. Each### <new>entry opens "Seen in <new> (YYYY-MM-DD); absent in <old> (YYYY-MM-DD)." Versions between two observations were never seen, so a change landed after<old>and by<new>; never name an exact version. With no readable version, the entry is### Observed YYYY-MM-DD, bracketed "seen <date>, absent <date>", naming any build version you could read. A version with no storage change still gets an entry saying so. A store agentgrep does not read is "not searched", never "excluded". -
Prove search for every touched agent id except
windsurf, which has no search surface; check it through its docs page. Pick<term>from a store you changed, and keep it out of commits and the report.$ uv run agentgrep find --agent <id> --json$ uv run agentgrep search --agent <id> --scope all --exhaustive --json <term>Pass means records returned,
summary.coverage.sources_failedis 0, andsummary.diagnosticshas nothing new. For a field you started reading (model, cwd, title), returned records must carry real values; a key in the output proves nothing. Then run the Layer 0 MCP smoke from thetesting-mcp-with-cli-agentsskill: a throwaway FastMCP stdio client in the scratchpad doingtools/listplus onesearch. -
Gate, then commit. Before every commit:
rm -rf docs/_build, the gates in.github/CONTRIBUTING.md,just test-all, andjust build-docs. WhenFORCE_COLORis set, run tests underNO_COLOR=1. Read each command's own pass/fail line, never a| tailor| grepof it.just build-docslines startingstorage observations:mean a stamp and its newest manifest disagree. Then stage and scan the added lines; it must print nothing. It catches encoded project directories such ashome-<user>-work-...and%2Fhome%2F....$ git diff --cached | grep -nE "^\+.*(/home/|/mnt/|/Users/|home-$USER-|%2F(home|Users)%2F)"Before the last commit,
checkexits 0 for every in-scope agent; a client that updated mid-sweep gets commit 7. -
Measure after the last commit, with every configured bench and its configured runs and warmup, which each bench's timeout is sized for; the
benchmarkskill covers flags andanalyze. Defaultsearchmust not slow beyond run-to-run noise; explain any remaining delta withscripts/profile_engine.pyevidence. A fix goes back through step 8.$ uv run scripts/benchmark.py compare origin/master HEAD --format json --output <scratch>/bench.json --no-progress
Report
End with exactly these parts:
- A table: agent | old → new version | what changed | searchable (record count) | perf delta.
- Each store left documented but unread, with the reason.
CHANGESentries the user-visible changes need, unless commit 8 landed them.- Anything left undone, with the reason.
04 同仓库更多 Skills
profile
暂无简介
benchmark
暂无简介
textual-non-blocking-pump
Use when writing, reviewing, or auditing agentgrep TUI code (src/agentgrep/ui/) for anything that could freeze the Textual message pump — keystrokes/spinner/cancel hang, a handler that blocks, a slow filter/find/detail render, "the UI froze", a new pump method/timer/worker, or revising the ADR 0011 non-blocking safeguards.
testing-mcp-with-cli-agents
Test an MCP server by driving real CLI agents (Claude, Codex, Cursor, Gemini, Grok, agy) against it — isolating each CLI's config and the server's own backend state instead of trusting unit tests alone. Use this whenever verifying MCP-server behavior end-to-end, checking that a local branch or checkout works across installed agent CLIs, comparing trunk-vs-branch behavior, driving an interactive agent TUI to exercise approval flows or cancellation, or reproducing a bug through a live client. Reach for it even when the user only says "test the MCP", "does the branch work in the agents", "drive the CLI to call the tool", or "check it across Codex/Gemini/Cursor".