Metadata-Version: 2.4
Name: ag-cache
Version: 1.0.0
Summary: Multi-agent build & test command deduplicator and token saver for Antigravity and Claude Code.
Author: Dhruv Dankhara
License: MIT
Keywords: ai-agents,antigravity,claude-code,cache,cli,llm-tokens
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Build Tools
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# ag-cache ⚡

**Multi-Agent Build & Test Command Deduplicator for Google Antigravity, Claude Code, and AI Agent Harnesses.**

In multi-agent workflows, orchestrators and subagents frequently run `npm test`, `pytest`, `cargo build`, or `tsc` multiple times without changing a single line of code between runs. This wastes build time and floods LLM context windows with duplicate terminal output.

`ag-cache` plugs directly into `PreToolUse` and `PostToolUse` agent hooks to fingerprint your workspace in milliseconds and skip redundant runs automatically.

---

## ✨ Features

- **Zero-Config Hook Interception:** Native support for **Google Antigravity** (`.agents/hooks.json`) and **Claude Code** (`.claude/settings.json`).
- **Under-15ms Workspace Fingerprinting:** Combines `git rev-parse HEAD`, staged/unstaged `git diff`, and untracked file contents (`git ls-files --others`). Falls back to file modification timestamps outside Git repos.
- **Massive Token Savings:** Replaces thousands of lines of duplicate test output with a 2-line cached pass receipt.
- **Smart Failure TTL (120s):** Blocks agents from blindly re-running failing tests when zero lines of code have changed, returning the cached error tail instead.
- **Parallel Subagent Locking:** If two subagents trigger the same build at the exact same millisecond, the second agent waits for the in-flight run to finish and reuses the result.
- **Savings Analytics (`ag-cache stats`):** Tracks total commands intercepted, hit rate, estimated LLM tokens saved, and wall-clock time saved.

---

## 📦 Installation

### Option 1: Python (`pipx`, `uv`, or `pip`)

```bash
# Recommended: Install globally via pipx
pipx install ag-cache

# Or via uv
uv tool install ag-cache

# Or via pip
pip install ag-cache
```

### Option 2: Node.js (`npm` or `npx`)

_(Requires Python 3.8+ installed on your system)_

```bash
npm install -g ag-cache
# Or run directly without installing:
npx ag-cache install
```

---

## 🚀 Quick Start

### 1. Enable hooks in your project repository

Navigate to the root of any project and run:

```bash
ag-cache install
```

This automatically generates:

- `.agents/hooks.json` for **Google Antigravity**
- `.claude/settings.json` for **Claude Code**

### 2. View your token & time savings

As your agents work, check how many redundant builds and tests were skipped:

```bash
ag-cache stats
```

Example output:

```text
============================================================
 ag-cache Analytics (/Users/dev/my-app)
============================================================
 Total Agent Commands Intercepted : 14
 Actual Executions Run            : 3
 Redundant Runs Blocked (Total)   : 11 (78.6% hit rate)
   ├─ Cached Passes Skipped       : 8
   ├─ Cached Failures Skipped     : 2
   └─ Parallel Collisions Merged  : 1
------------------------------------------------------------
 Estimated LLM Tokens Saved       : ~12,450 tokens
 Estimated Build/Test Time Saved  : 84.5s (1.4 min)
============================================================
```

---

## 🛠️ CLI Commands

| Command                  | Description                                                                       |
| :----------------------- | :-------------------------------------------------------------------------------- |
| `ag-cache install [dir]` | Install `PreToolUse` and `PostToolUse` hooks in the target repo (defaults to `.`) |
| `ag-cache stats`         | Show token and execution time savings for the current repo                        |
| `ag-cache stats --all`   | Show aggregated savings across all repositories on your machine                   |
| `ag-cache status`        | Print the raw JSON cache state and workspace fingerprints                         |
| `ag-cache clear`         | Clear the cache for the current workspace                                         |
| `ag-cache run <cmd>`     | Run any command directly through the `ag-cache` wrapper outside hooks             |

---

## ⚙️ Configuration & Escape Hatches

- **Force a fresh run (Bypass Cache):** Append `# nocache` to any command (e.g., `npm test # nocache`) or set `AG_CACHE_BYPASS=1`.
- **Customize Failure TTL:** Set `AG_CACHE_FAIL_TTL=60` (default is `120` seconds).
- **Customize Error Tail Length:** Set `AG_CACHE_ERROR_LINES=60` (default is `40` lines).

---

## 📄 License

MIT
