osgrep

osgrep automatically isolates repositories into unique indices (stores) to prevent cross-project pollution.

Automatic Isolation Logic

1. Git Remote URL: e.g., github.com/facebook/react → facebook-react.
2. Git Repo without Remote: directory name + hash (e.g., utils-7f8a2b3c).
3. Non-Git Directory: directory name + hash.

Manual Management

• List all stores: osgrep list (shows names, sizes, and last modified times).
• Override auto-detection: Use the --store flag: osgrep --store custom-name "query".
• Clean up stores: Manually delete the directory in ~/.osgrep/data/store-name.
• Data Location: All store data is kept in ~/.osgrep/data.

When a snippet provided by osgrep is insufficient, do not read the entire file. Instead, use the line ranges provided in the search results to read only the relevant section using the Read tool.

Example: If osgrep reports: osgrep found src/auth/handler.ts:45-90 as ORCH, Use: Read src/auth/handler.ts:45-120

The primary command for semantic search is osgrep "<query>". This returns approximately 10 results containing code snippets (typically 15+ lines each) to provide context.

Tips for better results:

• Use more descriptive queries. Instead of "auth", use "where does the server validate JWT tokens".
• Rephrase queries as if you were asking a teammate.
• Prioritize results labeled as ORCHESTRATION, as these contain the core logic.

osgrep "where do we validate user permissions"

To understand a codebase's architecture using osgrep, follow this pattern:

1. Find entry points: Search for where requests or processes enter the system. osgrep "where do requests enter the server"
2. Review ORCH results: Look at the code snippets provided in the orchestration results to understand the high-level logic.
3. Deep dive: If a specific function needs more context, use Read on the specific line range identified.
4. Trace flow: Use osgrep trace <function_name> to understand the call hierarchy and data flow.

You can integrate osgrep directly into Claude Code or Opencode to enable semantic search capabilities for your coding agent.

Claude Code Plugin

1. Run osgrep install-claude-code.
2. Open Claude Code (claude).
3. It is recommended to index your codebase before use. The plugin automatically manages the osgrep serve background process.

Opencode Plugin

1. Run osgrep install-opencode.
2. Open Opencode (opencode).
3. It is recommended to index your codebase before use. The plugin automatically manages the osgrep serve background process.

osgrep respects both .gitignore and .osgrepignore files. To exclude specific files or patterns from being indexed that are not already in your .gitignore, create a .osgrepignore file in your repository root.

.osgrepignore syntax:

• Uses the same pattern syntax as .gitignore.
• Patterns are relative to the repository root.
• Supports glob patterns, negation (!), and directory patterns (/).

If any osgrep command returns a status indicating "Indexing", "Building", or "Syncing", the semantic index is not yet complete.

Important for AI Agents:

1. STOP current processing.
2. INFORM the user that the semantic index is building and results will be incomplete.
3. ASK the user if they wish to proceed with partial results or wait for indexing to finish.

When performing a semantic search, osgrep categorizes results to help you understand the role of the code found:

• ORCHESTRATION (ORCH): Contains logic that coordinates other parts of the code (e.g., a handler that calls validation and response functions).
• DEFINITION: Contains types, interfaces, or class definitions.
• Score: A relevance score where 1 is the best match.
• Calls: A list of what the code snippet calls, which helps in tracing execution flow.

To remove the osgrep integration from OpenCode, use the uninstall-opencode command. This will:

1. Remove the tool shim at ~/.config/opencode/tool/osgrep.ts.
2. Unregister the osgrep MCP server from ~/.config/opencode/opencode.json.
3. Clean up any legacy plugin files in ~/.config/opencode/plugin/.

osgrep uninstall-opencode

The Skeletonizer class reduces token usage (typically by 80-95%) by replacing function and method bodies with concise summaries. It preserves structural elements like class/interface declarations, signatures, type definitions, and decorators, while providing inline metadata about what the elided functions do (e.g., complexity, role, and referenced symbols).

You can use the Skeletonizer class directly or use the skeletonizeFile convenience function for a simpler API.

import { skeletonizeFile } from './path/to/skeletonizer';

const filePath = 'example.ts';
const content = '...'; // file content

const result = await skeletonizeFile(filePath, content, {
  preserveDecorators: true,
  includeSummary: true,
  maxCallsInSummary: 4
});

if (result.success) {
  console.log(result.skeleton);
} else {
  console.error(result.error);
}