| name | repo-cache |
| description | Use whenever the user references a GitHub repo by URL or owner/repo and you'd otherwise make repeated `gh api repos/.../contents` calls. Clones the repo into `~/.cache/claude-repo-cache/<owner>/<repo>` (shallow) and returns a local path so subsequent exploration uses Read/Grep/find on local files. Triggers — any github.com URL the user wants explored, "look at <owner>/<repo>", "what's in the X repo", "compare to <gh-url>", "find Y in <repo>". |
| user_invocable | false |
repo-cache
Replace repeated gh api repos/.../contents calls with a one-time shallow clone, then use normal local tools (Read, Grep, find, ripgrep) on the cached path.
When to use
Whenever any of these hold:
- The user gives a
github.com/<owner>/<repo> URL or says "look at <owner>/<repo>".
- You're about to make a 2nd
gh api repos/.../contents/... call against the same repo.
- The user asks to compare/diff/study/inspect a public GitHub repo's structure.
If you only need a single specific file and won't touch the repo again, gh api once is fine — don't bother caching.
What this skill is NOT
- Not for the user's own work-in-progress repos (those are already on disk via their normal checkouts).
- Not for private repos that need authenticated
git clone setup the user hasn't done — fall back to gh api.
- Not a substitute for
git worktree when the user wants to actually edit the code.
How to use
1. Sync (clone or refresh)
~/.claude/skills/repo-cache/scripts/sync.sh <owner>/<repo>
Accepted input forms (all normalized):
openai/codex-plugin-cchttps://github.com/openai/codex-plugin-cchttps://github.com/openai/codex-plugin-cc.gitopenai/codex-plugin-cc@<branch|tag|sha>
Capture the printed path:
REPO=$(~/.claude/skills/repo-cache/scripts/sync.sh openai/codex-plugin-cc)
2. Search locally
Once $REPO is set, use the regular tools:
- Tree / find:
find "$REPO" -maxdepth 3 -type f (faster than recursive gh api)
- Grep:
rg -n "<pattern>" "$REPO" (or grep -rn if rg isn't installed)
- Read a file: Read tool with absolute path
$REPO/<path>
- List a dir:
ls "$REPO/<subdir>" — beats paginated gh api .../contents calls
3. Idempotent re-use
sync.sh is safe to call repeatedly:
- If the repo isn't cloned, it clones (shallow, depth 1).
- If it's been fetched within
REPO_CACHE_TTL_S (default 24h), it's a no-op fast path.
- If older than the TTL, it does
git fetch && git reset --hard origin/<default>.
So you can call it at the top of every step that needs the repo without worrying about overhead.
Configuration (env vars)
| Var | Default | Purpose |
|---|
REPO_CACHE_DIR | ~/.cache/claude-repo-cache | Cache root |
REPO_CACHE_TTL_S | 86400 (24h) | Fetch only if older than this |
REPO_CACHE_DEPTH | 1 | Clone depth (set 0 for full history if you need git log/blame) |
REPO_CACHE_FORCE | 0 | If 1, always fetch regardless of TTL |
If the user wants commit history, blame, or to look across many tags, re-sync once with REPO_CACHE_DEPTH=0:
REPO_CACHE_DEPTH=0 REPO_CACHE_FORCE=1 ~/.claude/skills/repo-cache/scripts/sync.sh <owner>/<repo>
Helper scripts
| Script | Purpose |
|---|
scripts/sync.sh <spec> | Clone or refresh; prints local path on stdout, status on stderr. |
scripts/path.sh <spec> | Print local path if already cloned (no network), else exit 1. |
Failure modes
- Private repo without auth:
git clone fails. Fall back to gh api (which uses the user's token) and tell the user that authenticated cloning isn't set up.
- Network down: if the repo is already cached,
sync.sh will fail to fetch but still print the cached path — and you can keep working on possibly-stale content.
- Disk pressure: the cache lives under
~/.cache/. If it grows, it's safe to rm -rf any subtree — sync.sh will re-clone on next call.
- Spec parse fails: prints
sync.sh: could not parse owner/repo and exits 2. Re-prompt the user for an unambiguous form (<owner>/<repo>).
Example: replacing a chain of gh api calls
Before (one gh api per directory level — slow, paginated, hits rate limits):
gh api repos/openai/codex-plugin-cc/contents | ...
gh api repos/openai/codex-plugin-cc/contents/plugins | ...
gh api repos/openai/codex-plugin-cc/contents/plugins/codex | ...
gh api repos/openai/codex-plugin-cc/contents/plugins/codex/scripts | ...
After (one clone, then local FS):
REPO=$(~/.claude/skills/repo-cache/scripts/sync.sh openai/codex-plugin-cc)
find "$REPO" -maxdepth 4 -type f | head -40
rg -n "codex exec" "$REPO"
