Octocode
Connects your AI assistant to GitHub and local codebases for intelligent code research and repository analysis. Provides code search, file exploration, commit history tracking, and package metadata retrieval.
What it does
- Search code patterns across GitHub repositories
- Read file content with partial range support
- Explore repository directory structures
- Track pull request history and changes
- Find NPM and Python package metadata
- Search repositories by keywords and topics
Best for
Tools (6)
## Search file content or files by path <when> - Find code patterns | Locate files | Discovery - Find File (`match="path"`), Find Pattern (`match="file"`) </when> <fromTool> - self: Refine query | Try semantic variants | Switch `match="path"↔"file"` (BFS/DFS) - githubGetFileContent: Read full content of found matches - githubViewRepoStructure: Locate file in directory tree - githubSearchRepositories: Find other repositories - githubSearchPullRequests: Find history/blame for file - packageSearch: Check imported packages </fromTool> <gotchas> - FILTERS: 1-2 filters safe. 3+ filters risky. NEVER combine extension+filename+path (returns empty). - PATHS: Strict prefix matching. `path:pkg` finds `pkg/file`, NOT `parent/pkg/file`. Verify with githubViewRepoStructure. - AVOID: Broad terms | Finding package repos (use `packageSearch`). - Start lean: single filter → verify results → add one filter at a time. - Prefer specifying owner & repo for precision and cost. </gotchas> <examples> - owner="facebook", repo="react", match="path", keywordsToSearch=["utils"] - owner="facebook", repo="react", keywordsToSearch=["useState"], match="file", limit=10 - owner="facebook", repo="react", path="src/api", extension="ts", keywordsToSearch=["export"] </examples>
## Read file content <when> - Use when you need details from a known file path. - Supports partial ranges or full file reading. </when> <fromTool> - self: Read more context by expanding 'startLine'/'endLine' or 'matchStringContextLines'. - githubSearchCode: Search for context from findings (imports, patterns, functions, objects). - githubViewRepoStructure: Get context from file discovered by structure. - githubSearchRepositories: Find usage in other repositories. - packageSearch: Check dependencies/imports repo locations (then use githubSearchRepositories). - githubSearchPullRequests: Read PR/commit data related to file. </fromTool> <gotchas> - Choose one strategy: 'startLine' + 'endLine' OR 'matchString' OR 'fullContent'. - Token efficiency: Use 'fullContent' only if the whole file is needed (small files). - File size limit: 300KB max. Larger files return FILE_TOO_LARGE error. - Branch: For pagination, use branch NAME (e.g. "main"), not commit SHA (which changes). </gotchas> <examples> - matchString="somePattern", matchStringContextLines=20 - startLine=1, endLine=20 (known location) - fullContent=true (small configs only) </examples>
## Display directory structure <when> - Understand repo structure (layout, configs, implementations) | Discover file paths. - Workflow: Map Root (`depth=1`) → Drill Down (`path` + `depth=2`) → Locate Files. </when> <output> - Returns `structure`: Record<dirPath, {files: string[], folders: string[]}> - Returns `summary`: {totalFiles, totalFolders, truncated, filtered, originalCount} - Keys are relative paths ("." = root, "src" = src/) - Auto-filters: 85+ directories (.git, node_modules, dist, build, etc.) - Truncation: Max 200 items (50 per depth level). Check summary.truncated </output> <fromTool> - self: Drill into subdirectory | Explore sibling paths. - githubSearchCode | githubGetFileContent: Search/Read file from found path. - githubSearchRepositories | packageSearch: Initial exploration entry point. </fromTool> <gotchas> - Avoid unknown paths (use root with depth=1 first). - `depth=2` is slow on large dirs (use on specific subdirectories). - Monorepos: Check `packages/` or `apps/` individually. </gotchas> <examples> - path="", depth=1 (root overview) - path="src", depth=2 (drill down) - path="packages/core", depth=1 (monorepo package) </examples>
## Search repositories by keywords/topics <when> - Starting research | Finding repos | Discovering projects - Use keywords in organizations and topics for public (open-source) - AVOID: Known package → use 'packageSearch' FIRST </when> <fromTool> - self: Refine query | Try semantic variants | Switch topics↔keywords - githubSearchCode: Found code ref? Search for origin repo - githubGetFileContent: Found readme/manifest? Search for origin repo - githubSearchPullRequests: Found PR? Search for base repo </fromTool> <gotchas> - After finding repo: use 'githubViewRepoStructure' or 'githubSearchCode' for discovery - Matches against: Name, Description, and README (use 'match' param to filter) - Freshness: Check 'pushedAt' in response (last code change) > 'updatedAt' (meta change) - Public Repos: Use 'stars' >1000 to filter noise (Caution: may hide very new projects) - Topics: Use to find related open-source projects (combine with keywords) - Synonyms: Try variants (e.g. "auth" vs "authentication", "ai" vs "llm") - Auto-filtering: Archived repositories are excluded automatically </gotchas> <examples> - topicsToSearch=["typescript", "cli"], stars=">1000" (public projects) - keywordsToSearch=["someRepoInOrg"] </examples>
## Search or fetch Pull Requests (metadata, diffs, discussions) <when> - Implementation history | Review changes | Find changes - Workflow: Review PR Meta (type=metadata) → Check specific diff (type=partialContent) - Use type=fullContent on small PRs only </when> <fromTool> - SELF: Refine query | Try semantic variants | Check related PRs | Widen date range. - Other: Find changes or known issues in repository </fromTool> <gotchas> - AVOID: Fetching large changes (fullContent - token-heavy) - prNumber ignores all other filters. </gotchas> <examples> - prNumber=123, type="metadata" (specific PR) - owner="org", repo="repo", state="closed", merged=true, limit=3 - prNumber=123, type="partialContent", partialContentMetadata=[{"file": "src/app.ts"}] </examples>
