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)