opty

A code intelligence tool built with Hyperdimensional Computing (HDC). It indexes function signatures, type definitions, and imports from your codebase and provides semantic search, cross-file references, impact analysis, change detection, and functional clustering — all locally, with no network calls or GPU.

Examples

Quick start — one-shot query (no daemon):

$ opty oneshot "authentication error handling" --dir ~/projects/myapp
# indexed 1,247 units across 89 files
functions[5]{name,signature,file,line}:
handleAuthError,pub fn handleAuthError(err: AuthError) !Response {,src/auth.zig,156
validateTokenOrFail,fn validateTokenOrFail(token: []const u8) !User {,src/auth.zig,203
logAuthFailure,fn logAuthFailure(reason: []const u8, ip: []const u8) void {,src/logging.zig,78

Start daemon for instant queries:

$ opty daemon ~/projects/myapp &
opty daemon on http://127.0.0.1:7390

$ opty query "HTTP route handlers"
functions[8]{name,signature,file,line}:
handleGetUser,pub fn handleGetUser(req: *Request, res: *Response) !void {,src/routes/users.zig,12
handleCreatePost,pub fn handleCreatePost(req: *Request, res: *Response) !void {,src/routes/posts.zig,45
handleLogin,pub fn handleLogin(req: *Request, res: *Response) !void {,src/routes/auth.zig,23
...

$ opty query "database connection pooling"
functions[3]{name,signature,file,line}:
initPool,pub fn initPool(alloc: Allocator, config: PoolConfig) !Pool {,src/db/pool.zig,34
acquireConnection,pub fn acquireConnection(pool: *Pool) !*Connection {,src/db/pool.zig,67
releaseConnection,pub fn releaseConnection(pool: *Pool, conn: *Connection) void {,src/db/pool.zig,89

Global daemon — works across all projects:

$ opty global --port 7390 &

$ cd ~/projects/api-server
$ opty query "error types"        # auto-indexes api-server

$ cd ~/projects/frontend
$ opty query "React components"   # auto-indexes frontend

$ opty status
Project: /home/you/projects/api-server
  Files: 142  Units: 2,891  Memory: 3.6 MB
Project: /home/you/projects/frontend  
  Files: 203  Units: 4,127  Memory: 5.1 MB

Semantic search finds code by concept, not exact names:

# Find authentication logic without knowing function names
$ opty query "user login session management"
→ handleLogin, createSession, validateSession, refreshToken

# Discover error handling patterns
$ opty query "handle failures and errors"  
→ handleError, tryParseOrFail, logFailure, unwrapOrDefault

# Explore data structures
$ opty query "user data models"
→ User struct, UserProfile struct, UserSettings struct

When to use opty vs grep

opty and grep solve different problems. Use the right tool for the job:

| Scenario | opty | grep | |---|---|---| | "How does indexing work?" | ✅ Returns scanAndIndex, IgnoreFilter, watchLoop | ❌ What would you grep for? | | Find all uses of alloc.free | ❌ Too syntactic | ✅ grep "alloc.free" | | "What types exist?" | ✅ opty_ast gives every type with nesting | ⚠️ grep "pub const.*struct" is brittle | | Find where port 7390 is set | ❌ HDC doesn't index literals | ✅ grep "7390" | | "What's the HTTP API surface?" | ✅ Returns route handlers semantically | ⚠️ grep "router\." works but misses context | | Rename a variable | ❌ Wrong tool entirely | ✅ grep to find, edit to replace |

Rule of thumb: opty for understanding, grep for locating, view for reading, edit for changing.

opty answers conceptual questions — "what handles authentication?", "show me the error handling patterns", "what's the project structure?" — where you don't know the exact symbol names. It returns results across multiple files from a single natural language query.
grep finds exact text — specific strings, regex patterns, symbol references, configuration values. It's the right tool when you know what you're looking for.
opty_ast gives the full structural skeleton of a project or file (all functions, types, imports, fields, variables with nesting depth) in one call — useful for orientation before diving into code.

In practice, opty queries use 88-93% fewer tokens than reading equivalent source files, making it especially useful when feeding context to an LLM.

What it does

opty extracts code unit skeletons — function signatures, type/struct definitions, and import declarations — from source files. It encodes each one into a 10,000-bit binary hypervector, then uses hybrid search (HDC + BM25 via reciprocal rank fusion) to match natural language queries against them.

Beyond search, opty builds a cross-file reference map linking imports to definitions, enabling impact analysis, symbol context lookups, and change detection.

What it's good at:

Exploration — "what handles authentication?" finds handleAuth, validateToken, refreshSession even if your query shares no exact substrings
Discovery — navigating an unfamiliar codebase by concept rather than by name
Impact analysis — "if I change handleAuth, what breaks?" shows downstream dependents with confidence scores
Code review — "what symbols changed in this diff?" maps git changes to affected functions and types
Architecture — "what are the subsystems?" clusters related symbols into functional groups
Compact overviews — results come in TOON format, which uses ~60% fewer tokens than JSON, useful when feeding context to an LLM

What it doesn't do:

Index function bodies, comments, or docstrings — only signatures
Replace grep for exact string matching or regex patterns
Understand what code does — it matches on names, types, and structural tokens

Think of it as a fast, intelligent table of contents for your codebase. You still need to read the actual code to understand it.

How it works

Parse — Scans source files and extracts structural elements (functions, types, imports) via pattern matching or tree-sitter
Encode — Maps each code unit to a 10,000-bit binary hypervector using HDC bind/bundle algebra. Splits identifiers (camelCase, snake_case) into sub-tokens for partial matching
Index — Stores vectors in an in-memory associative memory, builds a BM25 text index and a cross-file reference map
Query — Hybrid search combines HDC similarity with BM25 keyword matching via reciprocal rank fusion
Output — Returns matching code signatures in TOON format

All indexing and querying happens locally. No network calls, no LLM inference, no GPU.

Quick start

# Build (requires Zig 0.15+)
zig build

# One-shot query (no daemon)
./zig-out/bin/opty oneshot "authentication error handling" --dir /path/to/project

# Or run as a daemon for instant queries
./zig-out/bin/opty daemon /path/to/project &
./zig-out/bin/opty query "functions that handle database errors"
./zig-out/bin/opty status
./zig-out/bin/opty stop

On Windows, use .\zig-out\bin\opty.exe instead of ./zig-out/bin/opty.

Global multi-project daemon

The global mode runs a single opty daemon that serves all your projects. Projects are auto-loaded on first query and stay indexed in memory.

# Start the global daemon
opty global --port 7390 &

# Query from any project directory — opty auto-detects the project root
cd ~/projects/myapp
opty query "authentication flow"

cd ~/projects/api-server
opty query "database connection pool"

# Check all loaded projects
opty status

# Reindex current project
opty reindex

Project root detection walks up from your CWD looking for: .git, build.zig, Cargo.toml, package.json, go.mod, pyproject.toml, Makefile, CMakeLists.txt, .sln, Gemfile, pom.xml, build.gradle.

Auto-loading means you never need to configure project paths. Just cd into any project and query — opty indexes it on the fly (typically <500ms) and keeps the index in memory. The file watcher updates all loaded projects every 2 seconds.

Commands

| Command | Description | |---|---| | opty global [--port N] | Global multi-project daemon (HTTP server, auto-loads projects on demand) | | opty daemon [dir] [--port N] | Single-project daemon (HTTP server, default port 7390) | | opty mcp [dir] | Standalone MCP server over stdio (indexes locally) | | opty query <text> [--port N] | Query the running daemon via HTTP | | opty status [--port N] | Show indexed file/unit counts for current project | | opty reindex [--port N] | Force full re-index of current project | | opty stop [--port N] | Shut down the daemon | | opty oneshot <query> [--dir D] | Index + query in one shot (no daemon) | | opty version | Show version |

HTTP API

The daemon exposes an HTTP API on http://127.0.0.1:<port>:

| Method | Path | Body | Response | |---|---|---|---| | POST | /query | {"cwd": "...", "query": "..."} | TOON-format results | | GET | /status | query param ?cwd=... (optional) | Status text | | POST | /reindex | {"cwd": "..."} (optional) | Confirmation text | | POST | /shutdown | — | "OK shutting down" | | POST | /mcp | JSON-RPC body | MCP JSON-RPC response |

curl -X POST http://localhost:7390/query \
  -d '{"cwd":"/path/to/project","query":"error handling"}'

curl http://localhost:7390/status

Example output (TOON format)

functions[3]{name,signature,file,line}:
handleAuth,pub fn handleAuth(req: Request) !Response {,src/auth.zig,42
validateToken,fn validateToken(token: []const u8) !bool {,src/auth.zig,87
refreshSession,pub fn refreshSession(id: SessionId) !Session {,src/session.zig,23

Compare to the equivalent JSON (~60% more tokens):

{"functions":[{"name":"handleAuth","signature":"pub fn handleAuth(req: Request) !Response {","file":"src/auth.zig","line":42},{"name":"validateToken","signature":"fn validateToken(token: []const u8) !bool {","file":"src/auth.zig","line":87},{"name":"refreshSession","signature":"

Opty

Install / Use

README