Code Explorer

Purpose and when to use

Investigate OSS (Open Source Software) by cloning the repository locally using ghq and reading the source code directly. This skill is for understanding implementation details, architecture, and debugging OSS behavior through code reading.

Use this skill when the user wants to:

Understand how an OSS library or tool is implemented internally
Investigate the cause of a bug or unexpected behavior in OSS
Explore the architecture or design patterns of an OSS project
Read specific parts of OSS source code

Constraints

Web search is strictly prohibited
WebFetch tool: Only allowed for GitHub pages and URLs listed in official documentation
All investigation must be done through local source code analysis

Workflow

1. Input parsing

Accept one of the following:

GitHub repository URL (e.g., https://github.com/owner/repo)
Package name (e.g., vite, serde, requests)

Determine which format the user provided.

2. Resolve package name to GitHub URL (if needed)

If the user provided a package name instead of a GitHub URL:

Detect the language/ecosystem (ask user if unclear)
Query the appropriate package registry API to find the GitHub repository URL
See references/registry-lookup.md for detailed API endpoints and field mappings
If no GitHub URL is found in registry metadata, report to user and ask for manual input

Example registries:

npm: https://registry.npmjs.org/{package}
PyPI: https://pypi.org/pypi/{package}/json
RubyGems: https://rubygems.org/api/v1/gems/{gem}.json
Crates.io: https://crates.io/api/v1/crates/{crate}

3. Verify GitHub repository exists

Use gh api repos/{owner}/{repo} to confirm the repository is accessible.

If the repository does not exist or is not accessible:

Report the error to the user
End the workflow

4. Determine target version

Determine which version to investigate using this priority order:

User explicitly specifies version → Use that version
Package file in current directory contains the package → Extract version from package file
No version info available → Use default branch

Package file detection:

Check for package files in the current working directory in this order:

package.json (Node.js)
Cargo.toml (Rust)
go.mod (Go)
requirements.txt or pyproject.toml (Python)
Gemfile (Ruby)

If a package file is found and contains the target package:

Extract the version specification (e.g., "vite": "^5.0.0" in package.json)
Strip version range operators (^, ~, >=, etc.) to get base version
Use that version for checkout

See references/package-file-formats.md for detailed version extraction methods for each package format.

Example workflow:

User asks: "investigate vite"
Found package.json with "vite": "^5.0.0"
Extract version: 5.0.0
Will checkout v5.0.0 or 5.0.0 after cloning

5. Check if repository is already cloned locally

Run:

ghq list | grep "{owner}/{repo}"

This checks if the repository is already in the local ghq root.

6. Clone or update the repository

If not cloned:

Run ghq get {owner}/{repo} to clone the repository
If version is determined (from user or package file), navigate to the cloned directory and run git checkout {version}
Try with v prefix first (e.g., v1.2.3), then without if that fails

If already cloned:

If no version is specified, use the current state (typically default branch)
If version is specified:
- Navigate to the repository directory (find path with ghq list --full-path)
- Run git fetch --all to update refs
- Run git checkout {version} to switch to the specified version
- Try with v prefix first, then without if that fails
- If checkout fails (tag/branch does not exist), report to user and list available versions

7. Investigate the source code

Use the following tools to analyze the local repository:

Read tool: Read specific files
Glob tool: Find files by pattern (e.g., **/*.js, src/**/*.py)
Grep tool: Search for code patterns or keywords
Task tool (explore agent): For thorough codebase exploration and answering questions like "how does X work?" or "where is Y implemented?"
Bash tool: Run commands like git log, git blame, tree, ls, etc. for repository inspection

Investigation approach:

If the user specified a clear goal (e.g., "find the authentication logic"), focus the investigation on that
If the goal is general exploration, provide an overview of the repository structure first
Prioritize reading key files like README.md, main entry points, and core modules
Use Task tool for complex or multi-step explorations

8. Report findings

Provide findings in the chat with:

Clear summary of what was investigated
Relevant code snippets with file paths and line numbers (use file_path:line_number format)
Explanation of how the code works or what was discovered
Links to specific locations in the codebase for easy navigation

Do not create Markdown files unless explicitly requested by the user.

Tool usage

Allowed tools

ghq get, ghq list, ghq root
git commands (clone, checkout, fetch, log, blame, etc.)
gh api for GitHub API access
grep, glob, read for code analysis
bash for general command execution
task (explore agent) for codebase exploration
webfetch (restricted to GitHub pages and official documentation URLs only)

Prohibited tools

General web search (do not use webfetch for arbitrary URLs)
Any tool that fetches information from non-GitHub, non-official-documentation sources

Error handling and validation

Repository does not exist

Report: "The repository {owner}/{repo} does not exist or is not accessible on GitHub."
Ask if the user wants to try a different URL or package name

Tag or branch does not exist

Report: "The specified version '{version}' was not found in the repository."
List available tags with git tag --list or branches with git branch -a
Ask user to choose from available versions

Version from package file doesn't exist in git

Report: "Version {version} from {package-file} not found in repository."
List available versions with git tag --list
Ask user to choose or proceed with default branch

Package file cannot be parsed

Report: "Could not parse {package-file}. Proceeding with default branch."
Continue without version detection

Package registry has no GitHub URL

Report: "Could not find a GitHub repository URL for package '{package}' in the {registry} registry."
Ask user to provide the GitHub URL manually

Repository is cloned but has local changes

Report: "The repository has local changes. Do you want to proceed anyway?"
If user confirms, proceed; otherwise, ask user to clean or stash changes

ghq is not installed or not working

Report: "ghq tool is not available. Cannot clone repositories."
End workflow

References

references/registry-lookup.md - Package registry API endpoints and GitHub URL extraction
references/package-file-formats.md - Version detection from package manifest files

Validation checklist

Before cloning:

✓ GitHub repository existence verified
✓ ghq list checked for existing clone
✓ Package file checked for version info (if no explicit version provided)

Before investigating:

✓ Repository is cloned or updated successfully
✓ Correct version is checked out (if specified or detected from package file)

During investigation:

✓ Only local files are read (no web search)
✓ WebFetch only used for GitHub and official docs URLs

Troubleshooting

Problem: ghq get fails

Check network connection
Verify repository URL is correct
Check if repository is private (may need authentication)

Problem: Cannot find repository path after clone

Use ghq list --full-path | grep {repo} to locate
Use ghq root to find the base directory

Problem: Large repository takes too long to clone

Inform user that cloning is in progress
Consider using --depth=1 for shallow clone if full history is not needed (ask user first)

Problem: User's goal is unclear

Ask: "What specific aspect of this OSS would you like me to investigate?"
Provide examples: implementation of a feature, cause of a bug, overall architecture, specific file or function

code-explorer