AgentGitSmart 0.7.0

First release under the AgentGitSmart name, and the first with the repository public.

Renamed and relicensed

• Project renamed from AgentCache to AgentGitSmart; the cache side-ref namespace is now refs/agent-git-smart/<commit-oid>.
• Copyright is now Microsoft Corporation, with the standard Microsoft SECURITY.md and CODE_OF_CONDUCT.md.

Works with Claude Code

• Adds CLAUDE.md, and docs/ADOPTER_CLAUDE_TEMPLATE.md for adopters. Claude Code loads CLAUDE.md, not AGENTS.md, so a repo with only AGENTS.md was invisible to it.
• Both are thin pointers that import AGENTS.md, so there is still one source of truth — but each carries the "don't clone this repo" warning and a short cold-start inline, so they work even if the import is not resolved.
• The measured trial now scaffolds CLAUDE.md alongside AGENTS.md, .agentgitsmart and the workflow. It creates, never overwrites.

Fixes

• CI never used delta symbol indexing. actions/checkout fetches branches, never refs/agent-git-smart/*, so every run fell back to a full rebuild (fallback_reason: parent_uncached) and the public example of the feature never exercised it. The workflow now fetches the parent's cache ref first. On this repo that turned mode=full (104 files re-ctagged) into mode=delta (8 re-ctagged, 96 carried forward).
• agentgitsmart-service --help and agentgitsmart-hook --help exited 1 with a traceback; both now print usage. The hook also violated its own fail-open invariant — a config or repo-open error escaped as a traceback and a non-zero exit, which in a real post-receive would block the push. It now logs the reason and exits 0.
• pytest overwrote the committed experiments/results/exp3_hook_update.json on every run. exp3_hook_update.run() now takes an out_dir; the CLI default is unchanged.
• generate.py reports the generation mode, so a silent permanent fallback to full rebuilds is visible in CI output.

Documentation

• Corrected the documented shape of manifest.json and symbols.json. Both are envelopes — the file list is .entries[] and the symbol map is .symbols — and an agent following the old text would have indexed the wrong key. This was wrong in five places, including the agents.md written into every cache commit.
• Headline numbers recomputed from the committed exp1_cold_warm.json: the range is 16×–9,562×, not the 17×–9,979× previously claimed. experiments/results/SUMMARY.md was from an older run with wall times off by 3–5×; both its tables were regenerated from the raw data.
• README rewritten to about half its length, leading with the human path.
• Adds CONTRIBUTING.md, three issue forms (bug, measurement report, feature request) and a pull request template.

Housekeeping

• Removed 26 dead refs/agent-cache/* refs left on the remote from before the rename.
• Genericized the harness's remote-access documentation, and added a warning that the harness has no authentication and should be bound to a private interface.

Verified: 275 tests in tests/ and 34 in testharness/tests/ pass, the working tree stays clean afterward, the benchmark smoke run works, and the README's cold-start protocol was executed verbatim and anonymously against the live public repository.

AgentCache 0.6.0

Install offer: now sets itself up when worthwhile

The measured adoption trial can now SET ITSELF UP: when (and only when) it measures a repo as "agentcache worthwhile" inside a local clone, curl … | bash (or python scripts/try_agentcache.py) offers to scaffold the adoption files — the GitHub Action, AGENTS.md, and .agentcache — creating (never overwriting) files for you to review and commit. It never commits or pushes for you, and it stays silent when the honest verdict is "blobless is enough".

New packaged entrypoint & adopter template

• New packaged agentcache-generate console entrypoint and a generic adopter GitHub Action template (docs/adopter-workflow.yml) so any repo can generate refs/agent-cache/ on push by pip-installing the package.

Documentation reframe

• README "If you are human" reframed around the one-line curl trial; manual script usage moved to docs/TESTING.md.

Testing

• 265 tests pass.

AgentCache 0.5.0

Documentation Overhaul

The README is now a tight front door with four sections: What it is · If you're human · If you've been sent here by your agent · Dive deeper into AgentCache (a table of contents). Everything else moved into linked sub-docs:

• docs/INSTALL.md — Server hook, GitHub Action / dogfood mode, making your repo agent-aware
• docs/HOW_IT_WORKS.md — Why this shape, delta indexing + load reporting, the tested loop-safety guarantee, how human PRs don't break the cache, known edges
• docs/BLOBLESS.md — New explainer: what --filter=blob:none is, naive vs blobless vs agentcache, and the honest answer that you do NOT need AgentCache to use blobless (it's stock git; AgentCache only adds value on top for blob-heavy/high-reuse repos)
• docs/TESTING.md — The harness, the measured one-shot 'try it on your repo', tailnet/systemd serving, results digest links

Measured Adoption Trial — Now from Your Repo Root

curl -fsSL https://raw.githubusercontent.com/cdibona/AgentCache/main/scripts/try.sh | bash

Run this in your repo's root. The script self-bootstraps AgentCache to a temp dir and measures YOUR repo (or an explicit path/URL arg). Never measures itself.

python scripts/try_agentcache.py now defaults to the current directory.

Test Coverage

199 tests pass. All 40 intra-repo documentation links verified.

---

Generated with Amplifier.

AgentCache 0.4.0

AgentCache 0.4.0 — Measured adoption trial + explicit loop safety.

⚠️ Proof-of-Concept / Experimental Prototype
This is an early-stage project. The API, storage format, and semantics are subject to change. See README for the full caveat.

What's New

feat: One-shot MEASURED adoption trial

scripts/try_agentcache.py + scripts/try.sh — a curl-able wrapper for try-before-you-adopt.

The measured companion to the static assess_repo.py predictor. It mirrors your repo (local path or GitHub URL), stands up the real byte-counting proxy + git daemon + agentcache service on ephemeral ports (no Docker, no collision with a running harness), runs the real ExperimentRunner for one cold pass (seeds artifacts) + one warm pass (steady state), and reports:

• Actual network bytes for naive / blobless / agentcache strategies
• Warm % savings vs blobless
• Break-even passes (how many warm clones to amortize the cold cost)
• Honest suitability verdict — the same as used by the harness report: "agentcache worthwhile" / "blobless is enough" / "inconclusive — measure to be sure"

Cold-cost caveat: agentcache cold delivers full history; the blobless column is depth-1 shallow. See the README for interpretation.

feat(hook): Explicit, tested loop-prevention guard

Loop-prevention guarantee is now explicit and locked by tests — a self-trigger loop was already structurally impossible (cache artifacts written via in-process ref writes that never re-fire post-receive; hook acts only on refs/heads/; the Action's branches:[main] filter excludes refs/agent-cache/), but the guard is now config-correct, tested, and documented:

• Early skip for any ref under the configured AGENTCACHE_REF_PREFIX
• Documented loop-safety invariant
• 5 regression tests (cache-namespace no-op, tags no-op, deletions no-op, real branches generate, mixed stdin generates one)

Quality & Testing

• 183 tests pass (138 core + 45 new measured-trial integration)
• CI green: all steps (checkout, install, generate, publish, artifacts upload)
• Real repo measurement confirmed honest: reports "inconclusive" / "blobless is enough" correctly on previously-dangerous cases

Testing & Adoption Path

1. Static prediction (cheap, conservative): python scripts/assess_repo.py /path/to/repo
2. Measured trial (real proxy bytes): curl -fsSL https://raw.githubusercontent.com/cdibona/AgentCache/v0.4.0/scripts/try.sh | bash
3. Deploy to production (full harness + GitHub Action) if verdict says "agentcache worthwhile" and you've confirmed the break-even math fits your cloning velocity.

---

Generated with Amplifier

AgentCache 0.3.1

📊 Harness & Diagnostics: Reframed as an honest improvement roadmap

Experiment Report Reframing

The experiment harness report is now framed as an honest diagnostic to find where agentcache is weak vs naive/blobless approaches, not a marketing sheet. The report now leads with "Where agentcache has holes (improvement targets)":

1. Cold-start bundle penalty (the #1 structural hole): agentcache's bootstrap bundle scales with history depth, making it catastrophic vs blobless on deep-history repos:

   • git.git: 105.6 MiB cold vs 440.8 KiB blobless → 245×
   • cpython: 116.5 MiB vs 171× worse
   • go: 85.4 MiB vs 68× worse
   • django: 39.1 MiB vs 74× worse
   • Engineering target: partial-history / lazy / on-demand bundle construction.

2. Marginal warm wins on lean code repos: fd 12.4%, ripgrep 17.4%, codex 23.1%, redis 24.8%. On these, agentcache barely beats blobless even at steady state.

3. Impractical break-evens (warm passes before agentcache repays cold cost vs blobless): fd ~715, git ~682, cpython ~541, go ~148. For these, blobless is the correct default.

4. Per-commit hook overhead: real operational cost — go.git 15s, cookbook 7.3s, cpython 6.5s — that naive/blobless don't carry.

Each experiment now includes a cold-start table across all three approaches (naive/blobless/agentcache) with plainly visible bundle penalties, and verdict prose is neutral (no ✓).

Web UI: Unified Recent Activity Feed

• Left-hand nav "Runs" is now a unified "Recent Activity" feed showing recent experiments alongside raw tests, type-badged and routed to the correct detail view.
• Experiments feed shows all experiment variants with experiment links.

Earlier in the 0.3.x line

• Graceful cache-taint detection + fallback
• Hook vs GitHub Action warm-method comparison

---

No agentcache-core API changes since 0.3.0. This release is harness/docs/UI polish that enables honest iteration on the cold-bundle and hook-overhead targets.

Generated with Amplifier

AgentCache 0.3.0

Features

Cache Resilience: Graceful Taint Detection + Fallback

• Serve-time version/schema re-check: When a cached manifest's generator_version or symbols schema is stale, the service force-regenerates before serving.
• Targeted on-miss taint probe: When a path requested in /resolve is missing from the manifest, the service checks whether it actually exists in the commit's real git tree. If so, the manifest is stale—the service rebuilds the cache once and re-resolves, returning rebuilt:true. This is free in steady state (only fires on a real miss, never a per-request full tree walk).
• Agent fallback: If the agentcache manifest yields zero source files, the agent now downgrades to the blobless git ls-tree path instead of halting.
• Resilient to out-of-band commits made without the post-receive hook / GitHub Action firing, and to generator-version bumps.

Experimental Harness: Warm-Method Comparison

• warm_method configuration ("hook" | "action" | "both"):
  • "hook": Warm cache in-process (server post-receive equivalent, current behavior)
  • "action": Warm via GitHub-Action subprocess (scripts/generate_agentcache.py including blobless bundle)
  • "both": Build each from a cold cache for the same commit, record side-by-side comparison
• Measurements: hook_wall_s vs action_wall_s, ratio, winner
• Live results: action is 2.4–4.5× slower than in-process hook (subprocess overhead + bundle build)
• Human timeline now carries warm_method + per-mechanism load + comparison block

Other Notes

• The submodule/gitlink "subtree" limitation is unrelated to git worktrees. Worktrees share the object DB + refs and are fully supported (cache is OID-keyed and working-tree-free).
• 59 tests pass (49 prior + 6 taint + 4 warm-method).

Commit SHAs

• f665c71: feat: graceful cache-taint detection with blobless fallback and rebuild
• 25896c1: feat(harness): compare server-hook vs github-action cache warming
• cec2886: chore: bump package version to 0.3.0

AgentCache 0.2.2

• feat(harness): every test/experiment history now opens with a human-readable description of precisely what was done.
• feat(harness): the human (teammate) commits interleaved between agentcache agent passes are now measured — per human step: commit wall time, hook wall time, files changed, and the cache-rebuild load (delta vs full, files reindexed/carried-forward, bytes materialized, symbols).
• Validated live (fd.git + ripgrep.git, 2 passes, hook-pre-warmed human commit, fresh container per pass): human hook warm was a delta (reindexed=1, carried=57/222), warm agentcache 12.6x/15.3x less bytes than naive. 49 tests pass.

AgentCache 0.2.1

fix(harness): cpu_pct KeyError(1) that aborted larger-repo agentcache campaigns; per-repo errors now report Type: message + traceback instead of an opaque "1".

feat(harness): run/experiment histories now timestamped — runs.db completed_at, experiment completed_at, and per-pass started_at/completed_at.

Validation: Fresh human-interaction Docker experiment (fd.git + ripgrep.git, 2 passes, hook-pre-warmed human commit, fresh container per pass): both repos green, warm agentcache 12.6x (fd) and 15.3x (ripgrep) less bytes than naive. 49 tests pass.

AgentCache 0.2.0

🎯 Major Features

✅ Delta Symbol Indexing

Per-commit optimization for symbol cache generation. On pushes with changed files:

• Re-ctag only changed files instead of re-scanning the whole tree
• Carry forward unchanged symbols from the parent commit's cache
• Safe fallback to full rebuild (no parent cache / version/schema mismatch / ctags missing / root commit / merge unless enabled / changed-file ratio over AGENTCACHE_DELTA_MAX_RATIO limit)
• Canonicalization guarantee: delta output is byte-identical to full rebuild (preserves exp2 PRISTINE guarantee)

Load demo (exp3):

first_push    mode=full   reindexed=1  carried=0  bytes=32   parent=None
second_push   mode=delta  reindexed=1  carried=1  bytes=37   parent=3d97fc4c

See experiments/results/exp3_hook_update.json for live delta proof.

📊 Load Observability

meta.json and generate_for_commit() now emit a generation block with:

• mode — full or delta
• parent — parent commit SHA (if delta)
• files_in_tree, files_changed, files_reindexed, files_carried_forward
• content_bytes_materialized, symbol_count
• ctags_available, fallback_reason

Enables per-human-action telemetry and debugging.

🔧 Configuration

New knobs (all optional, backward-compatible defaults):

• AGENTCACHE_DELTA_SYMBOLS — enable/disable delta path (default: true if ctags present)
• AGENTCACHE_DELTA_ON_MERGE — delta across merges (default: false, safest)
• AGENTCACHE_DELTA_MAX_RATIO — fallback to full if changed_files / total_files exceeds ratio (default: 0.3)
• AGENTCACHE_WEB_HOST — test harness bind host (default: 127.0.0.1, now supports tailnet IPs)

Schema versions:

• GENERATOR_VERSION → 0.2.0
• SYMBOLS_SCHEMA → 2

🛠️ Tooling & Operations

System Prerequisites

• universal-ctags now required for symbol indexing (previously optional). Install via sudo apt-get install universal-ctags.
  • CI workflow now installs it automatically.
  • Detection: symbols.ctags_available() flips to true; delta path activates.

Test Harness

• Tailnet serving: bind test harness to tailnet IP for remote access over Tailscale.
  • AGENTCACHE_WEB_HOST=100.107.70.97 (or any tailnet IP)
  • Combine with tailscale serve for HTTPS access.
• Systemd --user integration: harness can run as a managed systemd --user service (auto-restart, reboot-survivable).
• Startup log fix: log line now reflects the real bind host instead of hardcoded 127.0.0.1:8080.

CI Workflow

• Renamed to "AgentCache generate" (was: "Generate AgentCache").
• Installs universal-ctags before running tests.

🐛 Compatibility Fix

Python < 3.11.4 / 3.12 compatibility: tarfile.extractall(filter=) kwarg is unavailable on Python 3.11.0–3.11.3 (added in 3.12, backported to 3.11.4+). Guarded with version check; falls back to plain extractall() on older interpreters (safe: git-archive members are trusted relative tree paths).

• Impact: previously masked because ctags was absent locally (symbol tests skipped) and CI Python had the backport.
• Fixed: symbol indexing now works on Python 3.11.2 with ctags present.
• Tests: all 49 tests pass (13 previously skipped delta tests now run + pass).

📖 Documentation Updates

• README.md: Delta symbol indexing overview, config knobs, ctags prerequisite.
• AGENTS.md: Load block structure, generation telemetry.
• .env.example: New env vars with descriptions.
• docs/ADOPTER_AGENTS_TEMPLATE.md: Notes on delta mode and load interpretation.
• experiments/README.md: exp3 now demonstrates delta (second push shows carried-forward symbols).

Contributors

Generated with Amplifier

AgentCache 0.1.0

v0.1.0

chore: add MIT license