repo-explorer

name	repo-explorer
description	Clone and inspect external GitHub repositories in a reusable local cache at ~/explore/repos. Use when asked to explore, inspect, investigate, compare, review, or answer questions about a repository that is not already in the current workspace, especially when the request names a GitHub owner/repo or repository URL.

Repo Explorer

Overview

Use a dedicated repository cache so external codebase exploration stays out of the active workspace. Always use the GitHub CLI for GitHub repository metadata and cloning.

Workflow

1. Identify the requested repository as a GitHub slug or URL, such as owner/repo or https://github.com/owner/repo.

2. Create and inspect the cache before doing anything else:

   mkdir -p "$HOME/explore/repos"
   ls -la "$HOME/explore/repos"
   

3. Resolve the repository through GitHub CLI before cloning:

   gh repo view OWNER/REPO --json nameWithOwner,url --jq '.nameWithOwner'
   

4. Use a stable cache folder name derived from the resolved nameWithOwner by lowercasing it and replacing / with _. For OpenAI/codex, use ~/explore/repos/openai_codex.

5. If the cache folder already contains a .git directory, do not clone again. Move into that folder and continue the user's request.

6. If the cache folder does not exist, clone with GitHub CLI:

   gh repo clone OWNER/REPO "$HOME/explore/repos/owner_repo"
   

7. If the target cache folder exists but does not contain .git, stop and report the conflict instead of overwriting or deleting it.

8. After entering the repository, run:

   ls -la
   

9. Inspect the repository using read-only commands first, such as rg --files, rg, git status --short, git branch --show-current, and file reads. Do not install dependencies, build, run tests, or modify files unless the user's request needs it.

Isolation Rules

• Keep external repository exploration inside ~/explore/repos; do not clone into the active workspace.
• Treat cached repositories as external context. Avoid accidental edits unless the user explicitly asks for changes in that repository.
• Keep command output grounded in the cached checkout path so the user can tell which repository was inspected.
• If the current workspace is already the requested repository, use the current workspace instead of cloning or switching to the cache, but still say that no external cache checkout was needed.

Shell Pattern

Adapt this pattern for concrete repository requests:

repo="OWNER/REPO"
cache_root="$HOME/explore/repos"
mkdir -p "$cache_root"
ls -la "$cache_root"

name_with_owner="$(gh repo view "$repo" --json nameWithOwner --jq '.nameWithOwner')"
cache_name="$(printf '%s' "$name_with_owner" | tr '[:upper:]/' '[:lower:]_')"
repo_dir="$cache_root/$cache_name"

if [ -d "$repo_dir/.git" ]; then
  cd "$repo_dir"
elif [ -e "$repo_dir" ]; then
  echo "Cache path exists but is not a git repository: $repo_dir" >&2
  exit 1
else
  gh repo clone "$name_with_owner" "$repo_dir"
  cd "$repo_dir"
fi

ls -la