Orient Search

Fast local code search for coding agents.

Orient gives local agents repo maps, indexed search, query plans, and bounded file reads so they stop repeating expensive filesystem scans. It stores local code-search artifacts only and has no telemetry.

Start A Shared Daemon

cargo install --git https://github.com/evalops/orient-search
orient --version

orient agent-bootstrap \
  --repo /path/to/current/repo \
  --output-dir /path/to/local/cache/orient-shards

Or run the shared daemon setup manually:

export ORIENT_WORKSPACES=/path/to/workspaces
export ORIENT_SHARDS=/path/to/local/cache/orient-shards

orient ensure-shards \
  --discover-root "$ORIENT_WORKSPACES" \
  --output-dir "$ORIENT_SHARDS" \
  --family-limit 2

orient serve-tcp \
  --addr 127.0.0.1:8796 \
  --index-dir "$ORIENT_SHARDS" \
  --warm-repo /path/to/current/repo \
  --warm-query "file:README.md"

--index-dir registers a shard manifest and loads repo indexes lazily. Use --warm-repo for the one or two active checkouts agents are editing, and --max-cached-indexes N when many repos share the daemon. Use --warm-index-dir "$ORIENT_SHARDS" only when you intentionally want to load all shards at startup.

Check the daemon and generate the agent-facing setup text:

orient doctor --index-dir "$ORIENT_SHARDS"
orient daemon-status
orient agent-instructions --profile generic --index-dir "$ORIENT_SHARDS"

Unix sockets are supported with orient serve-unix --socket "$ORIENT_SOCKET".

Search

orient search-auto --retry-if-empty --summary "symbol:SessionManager token"
orient search-auto --no-daemon "symbol:SessionManager token"
orient search --repo . "issue token"
orient search --index-dir "$ORIENT_SHARDS" "repo:service issue token"
orient read-range --repo . src/lib.rs:40:80

With no explicit target, search-auto tries the shared daemon at 127.0.0.1:8796, scopes daemon requests to the current checkout when possible, then falls back to live local search. Set ORIENT_ADDR, ORIENT_SOCKET, or --no-daemon to choose a different path.

Useful filters include repo:, path:/dir:, file:, lang:, ext:, symbol:, kind:, test:, generated:, code:, content:, quoted phrases, negative filters such as -path:vendor, and mode:any for broad orientation. Pasted file locations, stack frames, test selectors, package scripts, Makefile targets, Justfile targets, and Bazel labels resolve to anchored searches.

Agent Protocol

Orient exposes JSON-lines, TCP, Unix socket, and MCP-shaped surfaces. Search results include ready-to-run read, related-file, related-symbol, repo-map, and query-plan follow-ups. Agents should run those returned requests directly instead of translating them back into shell search/read commands.

{"id":"tools","tool":"tool_manifest","arguments":{}}
{"id":"search","tool":"search_auto","arguments":{"query":"repo:service symbol:SessionManager token","limit":10,"summary":true}}
{"id":"read","tool":"open_ranges","arguments":{"ranges":["service/src/auth.rs:40:80"]}}

Compact fields are the default place to look first:

• query_plan_summary, summary, and next_action explain what to do next.
• read_request and next_read_batch_request open bounded context.
• refresh_request refreshes stale scoped shards without rebuilding everything.
• advice:true or --advice returns short query-plan retry guidance.

See Agent protocol for the full tool surface.

Footprint

Indexes contain source snapshots, line offsets, postings, symbols, and search metadata so snippets and bounded reads stay fast from a shared daemon. Keep them in a local cache and out of source control.

orient shard-status --index-dir "$ORIENT_SHARDS" --summary

Benchmarks

For local performance work, start with the 10-client shared-daemon contention benchmark:

ORIENT_DAEMON_CONTEND_ROOT=/path/to/workspaces \
ORIENT_DAEMON_CONTEND_CWDS=/path/to/repo-a:/path/to/repo-b \
ORIENT_DAEMON_CONTEND_MODE=both \
tools/ci/orient_daemon_contention_perf.sh

Use Benchmarking for the full benchmark matrix, including single-repo fallback vs indexed search, wide workspace gates, cold first-touch latency, warm daemon contention, and mixed search/read load.

Build And Test

bazel build -c opt //:orient
bazel test //...
bazel run //:ci_full_test
bazel run //:ci_perf_gates

Docs

• Shared daemon guide
• Agent adoption
• Agent protocol
• Benchmarking
• Storage and footprint
• Fast search roadmap