`bash
osgrep index # Index current dir
osgrep index --dry-run # See what would be indexed
osgrep index --verbose # Watch detailed progress (useful for debugging)
osgrep index --allow-fallback # Include files without grammar support
osgrep index --reset # Full re-index from scratch
`

$3

Runs a lightweight HTTP server with live file watching so searches stay hot in RAM.

- Keeps LanceDB and the embedding worker resident for <50ms responses.
- Watches the repo (via chokidar) and incrementally re-indexes on change.
- Health endpoint: GET /health
- Search endpoint: POST /search with { query, limit, path, rerank }
- Writes lock: .osgrep/server.json with port/pid

Options:

| Flag | Description |
| --- | --- |
| -p, --port | Port to listen on (auto-increments if not specified) |
| -b, --background | Run server in background and exit immediately |

Port Selection (priority order):
1. Explicit -p flag
2. OSGREP_PORT environment variable
3. Auto-increment from registry (last used port + 1, or 4444 if no servers)

Usage:

`bash
osgrep serve # Foreground, port 4444 (or next available)
osgrep serve --background # Background mode, auto port
osgrep serve -b -p 5000 # Background on specific port
`

Subcommands:

`bash
osgrep serve status # Show server status for current directory
osgrep serve stop # Stop server in current directory
osgrep serve stop --all # Stop all running osgrep servers
`

Example workflow:

`bash


Start servers in multiple projects

`bash
osgrep list
`

Shows store names, sizes, and last modified times. Useful for seeing what's indexed and cleaning up old stores.

$3

Generates a compressed "skeleton" of a file, showing only signatures, types, and class structures while eliding function bodies.

`bash
osgrep skeleton src/lib/auth.ts
`

Output:
`typescript
class AuthService {
validate(token: string): boolean {
// → jwt.verify, checkScope, .. | C:5 | ORCH
}
}
`

Modes:
- osgrep skeleton : Skeletonize specific file.
- osgrep skeleton : Find symbol in index and skeletonize its file.
- osgrep skeleton "query": Search for query and skeletonize top matches.

Supported Languages:
TypeScript, JavaScript, Python, Go, Rust, Java, C#, C++, C, Ruby, PHP.

$3

Checks installation health, model paths, and database integrity.

`bash
osgrep doctor
`

Performance & Architecture

osgrep is designed to be a "good citizen" on your machine:

1. Bounded Concurrency: Chunking/embedding stay within small thread pools (1–4) and capped batch sizes to keep laptops responsive.
2. Smart Chunking: Uses tree-sitter to split code by function/class boundaries, ensuring embeddings capture complete logical blocks.
3. Deduplication: Identical code blocks (boilerplate, license headers) are embedded once and cached, saving space and time.
4. Semantic Split Search: Queries both "Code" and "Docs" separately to ensure documentation doesn't drown out implementation details, then reranks with ColBERT.
5. Global Batching: A producer/consumer pipeline decouples chunking from embedding. Files are chunked concurrently, queued, embedded in fat batches, and written to LanceDB in bulk.
6. Anchor-Only Scans & Batch Deletes: File discovery and stale cleanup hit only anchor rows, and stale/changed paths are removed with a single IN delete to minimize I/O.
7. Structural Boosting: Function/class chunks get a small score boost; test/spec paths are slightly downweighted to bubble up primary definitions first.
8. Role Classification: Detects ORCHESTRATION functions (high complexity, many calls) vs DEFINITION (types/classes) to help agents prioritize where to read.

Configuration

$3

osgrep automatically creates a unique index for each repository based on:

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 for collision safety

Examples:
`bash
cd ~/work/myproject # Auto-detected: owner-myproject
osgrep "API handlers"

cd ~/personal/utils # Auto-detected: utils-abc12345
osgrep "helper functions"
`

Stores are isolated automatically — no manual --store flags needed!

$3

osgrep respects both .gitignore and .osgrepignore files when indexing. Create a .osgrepignore file in your repository root to exclude additional files or patterns from indexing.

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

$3

- View all stores: osgrep list
- Override auto-detection: osgrep --store custom-name "query"
- Clean up old stores: rm -rf ~/.osgrep/data/store-name
- Data location: ~/.osgrep/data

Development

`bash
pnpm install
pnpm build # or pnpm dev
pnpm format # biome check
`

Troubleshooting

- Index feels stale? Run osgrep index to refresh.
- Weird results? Run osgrep doctor to verify models.
- Index getting stuck? Run osgrep index --verbose to see which file is being processed.
- Want faster indexing? Keep fallback disabled (default) to skip files without TreeSitter support.
- Need a fresh start? Delete ~/.osgrep/data and ~/.osgrep/meta.json and run osgrep index`.

Attribution

osgrep is built upon the foundation of mgrep by MixedBread. We acknowledge and appreciate the original architectural concepts and design decisions that informed this work.

See the NOTICE file for detailed attribution information.

License

Licensed under the Apache License, Version 2.0.
See LICENSE and Apache-2.0 for details.