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