# Grec

> Local repository index, lookup, and checkout. Companion to `glk`. Use `grec` before deep repository browsing. Find the repo locally, or clone it quickly.

- Skill: `radiusmethod/grec` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add radiusmethod/grec`
- Raw SKILL.md: https://api.skillmd.com/api/skills/radiusmethod/grec/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: radiusmethod (https://skillmd.com/u/radiusmethod)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/radiusmethod/grec

---


# grec — Git REpo Cache

Local repository index, lookup, and checkout. Companion to `glk`.

Use `grec` before deep repository browsing. Find the repo locally, or clone it quickly.

First check whether the repo already exists on disk. If it does, inspect that checkout with local tools. If it does not, use `grec checkout` to get a shallow clone, then explore locally with `Read`, `Grep`, or `Glob`.

Prefer local access (`grec` + local tools) over repeated remote `glk file` or `glk tree` calls.

## Choose the right tool

- Use `grec` when you expect to inspect multiple files, search file contents, trace code across directories, or study repository structure.
- Use `grec locate` when you expect one local match and want its path.
- Use `grec find` when you want several possible matches.
- Use `grec checkout` when you need a local copy and may need to clone.
- Use `glk` instead when you only need GitLab metadata or a one-off file read.

## Commands

    grec checkout [project] [--depth N] [--host HOST] [--ref REF]  # Get a local copy of a project (index lookup or shallow clone)
    grec find <keyword> [keyword...]                               # List all repos matching keywords
    grec index build                                               # Scan directories and build local repo index
    grec index list [pattern]                                      # List indexed repos, optionally filtered by pattern
    grec index status                                              # Show index statistics
    grec locate [keyword...]                                       # Return path for a single matching repo (for scripting)

This is the curated agent-facing command reference.

For the full runnable command and output inventory, run `grec help-all`.

## Pick the right `grec` command

- `grec locate <project>`: return one path for direct inspection or scripting
- `grec find <keyword>`: list matching repos when you are not sure of the exact name
- `grec checkout <project>`: return an existing local path or shallow-clone if needed
- `grec index build`: refresh the index when expected repos are missing
- `grec index status`: check whether the index is stale

## Output format

Use TSV first.

Reach for `--json` only when:

- TSV does not include a field you need
- you will actually parse the structure programmatically

TSV is preferred in agent sessions because it costs fewer tokens and keeps the next action obvious.

Example:

    grec locate <project>
    grec find kyverno

    checkout:    raw path to stdout (existing or freshly cloned)
    find:        HOST PROJECT PATH
    index list:  HOST PROJECT PATH
    locate:      raw path to stdout

Treat stdout as machine-readable output.
If you get a raw path on stdout, use it with local tools next.

## Recovery rules

If `grec locate` finds nothing, run `grec index build` before assuming the repo is absent.

If you need code exploration and do not already have a local checkout, prefer `grec checkout` over repeated remote reads.

## Exit codes

    0  Success
    1  General error (config, I/O)
    2  Safety refusal (project not public, via glk)
    3  Not found (project not in index or on remote)