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.
Integrates with GitHub CLI and npm to provide repository analysis, code discovery, file exploration, commit history tracking, and package metadata retrieval with intelligent caching and cross-tool workflow support.
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
About Octocode
Octocode is a community-built MCP server published by bgauryy that provides AI assistants with tools and capabilities via the Model Context Protocol. Octocode seamlessly integrates with GitHub CLI and npm for fast code discovery, repo analysis, and commit tracking with It is categorized under ai ml, developer tools. This server exposes 6 tools that AI clients can invoke during conversations and coding sessions.
How to install
You can install Octocode in your AI client of choice. Use the install panel on this page to get one-click setup for Cursor, Claude Desktop, VS Code, and other MCP-compatible clients. This server runs locally on your machine via the stdio transport.
License
Octocode is released under the MIT license. This is a permissive open-source license, meaning you can freely use, modify, and distribute the software.
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>
Octocode: Research Driven Development for AI
Stop Guessing. Start Knowing.
Empower your AI assistant with the skills of a Senior Staff Engineer.
Installation
Prerequisites: GitHub authentication required. See Authentication Setup.
Recommended: Octocode CLI
npx octocode-cli
Interactive setup wizard with GitHub OAuth, MCP server installation, and skills marketplace.
Alternative Methods
One-Click Install (Cursor)
Manual MCP Configuration
Add to your MCP configuration file:
{
"mcpServers": {
"octocode": {
"command": "npx",
"args": ["octocode-mcp@latest"]
}
}
}
Research Skill (Direct Install)
npx add-skill https://github.com/bgauryy/octocode-mcp/tree/main/skills/octocode-research
MCP Server
The Octocode MCP Server connects your AI assistant to code:
- GitHub & GitLab: Search repositories, find usage patterns, read implementations, explore PRs
- Local Tools: Search code, browse directories, find files in your local codebase
- LSP Intelligence: Go to Definition, Find References, Call Hierarchy -- compiler-level understanding
https://github.com/user-attachments/assets/de8d14c0-2ead-46ed-895e-09144c9b5071
Skills
Agent Skills are a lightweight, open format for extending AI agent capabilities. Skills index: skills/README.md
| Skill | What it does |
|---|---|
| Research | Deep code exploration via LSP, local tools, GitHub API, packages, PRs |
| Local Search | Fast local codebase exploration with LSP semantic navigation |
| Plan | Evidence-based planning: Understand, Research, Plan, Implement |
| PR Reviewer | PR review across 7 domains with evidence-backed findings |
| Roast | Brutally honest code critique with file:line citations |
| Prompt Optimizer | Transform weak prompts into enforceable agent protocols |
| Documentation Writer | Generate comprehensive repo documentation in 6 phases |
https://github.com/user-attachments/assets/5b630763-2dee-4c2d-b5c1-6335396723ec
Documentation
For the full documentation index, start here: docs/README.md
Recommended quick links:
- Authentication Setup
- Configuration Reference
- Local Tools + LSP Reference
- CLI Skills Guide
- Skills Index
- Troubleshooting
The Manifest
"Code is Truth, but Context is the Map." -- Read the Manifest for Research Driven Development to understand the philosophy behind Octocode.
Contributing
See the Development Guide for monorepo setup, testing, and contribution guidelines.
Alternatives
Related Skills
Browse all skillsUI design system toolkit for Senior UI Designer including design token generation, component documentation, responsive design calculations, and developer handoff tools. Use for creating design systems, maintaining visual consistency, and facilitating design-dev collaboration.
Answer questions about the AI SDK and help build AI-powered features. Use when developers: (1) Ask about AI SDK functions like generateText, streamText, ToolLoopAgent, embed, or tools, (2) Want to build AI agents, chatbots, RAG systems, or text generation features, (3) Have questions about AI providers (OpenAI, Anthropic, Google, etc.), streaming, tool calling, structured output, or embeddings, (4) Use React hooks like useChat or useCompletion. Triggers on: "AI SDK", "Vercel AI SDK", "generateText", "streamText", "add AI to my app", "build an agent", "tool calling", "structured output", "useChat".
Master API documentation with OpenAPI 3.1, AI-powered tools, and modern developer experience practices. Create interactive docs, generate SDKs, and build comprehensive developer portals. Use PROACTIVELY for API documentation or developer portal creation.
Use when working with the OpenAI API (Responses API) or OpenAI platform features (tools, streaming, Realtime API, auth, models, rate limits, MCP) and you need authoritative, up-to-date documentation (schemas, examples, limits, edge cases). Prefer the OpenAI Developer Documentation MCP server tools when available; otherwise guide the user to enable `openaiDeveloperDocs`.
Guide for building TypeScript CLIs with Bun. Use when creating command-line tools, adding subcommands to existing CLIs, or building developer tooling. Covers argument parsing, subcommand patterns, output formatting, and distribution.
Integrate Vercel AI SDK applications with You.com tools (web search, AI agent, content extraction). Use when developer mentions AI SDK, Vercel AI SDK, generateText, streamText, or You.com integration with AI SDK.