Oko

Help your coding agent find code faster and use fewer tokens.

Oko helps Codex, Claude Code, and OpenCode spend less time searching and fewer tokens reading irrelevant code. It delivers relevant source snippets through MCP, and answers a code question as you send it, so your agent can get to the task sooner. Gains vary by task and coding tool.

Each benchmark's method and caveats are in its section below.

Oko runs locally and uses TypeSafe AI’s Jev to rank selected source snippets. Use it through your coding agent or directly from your terminal.

Install · Connect your coding tool · Benchmarks · CLI examples · Documentation

oko ask "where is authentication handled?"

No Node.js or Rust runtime needed for downloaded binaries. Oko needs a TypeSafe AI API key for Jev ranking; local keyword search also works without a key.

Install

Run this on macOS or Linux to install the latest release:

curl -fsSL https://raw.githubusercontent.com/bartlomein/oko/main/install.sh | sh
export PATH="$HOME/.local/bin:$PATH"

The installer detects your processor, downloads Oko and its bundled ripgrep, verifies the checksum, and installs them without administrator access. Add the export PATH line to ~/.zshrc or ~/.bashrc to keep oko available in new terminals. Existing installations from other sources are left untouched.

Supported downloads: macOS Apple Silicon and Intel; Linux ARM64 and x64 with glibc 2.35+ (Ubuntu 22.04 or newer). Alpine and Windows are not supported by the installer. macOS binaries are not yet signed or notarized.

To upgrade later, run oko upgrade: it installs the latest release and refreshes every project you set up. Oko tells you when one is out.

Prefer to inspect the script, install manually, or select a version? See installation options.

Continue with oko setup below—it prompts for your TypeSafe AI key. For terminal use or a manual connection, save the key with oko auth login. Oko uses your operating system’s credential store; headless Linux can use an environment variable or ignored .env instead. See key configuration.

Connect your coding tool

Run setup from the project you want to search, naming your coding tool:

cd /path/to/your/project
oko setup                     # Codex app or CLI
oko setup --client claude     # Claude Code
oko setup --client opencode   # OpenCode 1.x
oko setup --client all        # all three

Setup installs stable copies, connects the tool to Oko for this project, adds search guidance to the instructions that tool reads, and checks the connection. The guidance matters: in our benchmark it is what makes Codex and OpenCode sessions faster, not just cheaper. Setup also adds a prompt hook: when you ask a code question, Oko's answer is in the agent's context before its first turn, so it skips a round of searching. Start a new session afterwards. Repeat setup for each project.

In Codex, approve the hook once. Codex runs no hook you have not reviewed. The first time you open the project after setup, it shows Hooks need review: choose Trust all and continue (or Review hooks to read Oko's first). It asks once per project, and again only if a later Oko release changes the hook. If you skipped it, /hooks brings it back. Claude Code and OpenCode need no extra step.

For a key-free connection, add --no-jev. See what setup changes. The manual steps below do the same by hand, without the guidance.

Claude Code by hand

From the project you want to search:

cd /path/to/your/project
oko auth login
claude mcp add-json --scope local oko \
  "{\"type\":\"stdio\",\"command\":\"$(command -v oko)\",\"args\":[\"mcp\",\"--root\",\"$PWD\"],\"alwaysLoad\":true}"
claude mcp list

Start a new Claude Code session and check /mcp for Oko. This connection is private to you and scoped to this project; repeat the command for other projects. Skip oko auth login if you already saved your key.

OpenCode by hand

Save your key once with oko auth login, then add this to opencode.json in your project root (merge the oko entry if the file exists):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "oko": {
      "type": "local",
      "command": ["oko", "mcp"],
      "enabled": true
    }
  }
}

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "servers": {
      "oko": {
        "type": "local",
        "command": ["oko", "mcp"]
      }
    }
  }
}

Run opencode mcp list from your project to check the connection, then start a new OpenCode session. Use opencode --version if you are unsure which format to use. See the OpenCode MCP docs for more options.

Try it

Ask your agent:

Use Oko to find where authentication is handled in this project.

Your coding tool starts Oko automatically. You do not need to run a server yourself. Connecting Oko makes it available; it does not force the agent to use it for every search. A function, class or method named in the question is always found; literal text can still be searched with native grep.

Use in your terminal

Oko searches the directory you run it from:

cd /path/to/your/project
oko ask "where is authentication handled?"
oko ask "how are retries handled?" --json
oko ask "how does authentication work?" --deep --max-steps 5
oko ask "where is authentication handled?" --no-jev

Start with normal search. Deep mode can investigate further, but makes additional Jev requests and can take longer. --no-jev uses local keyword ranking only.

To replace, check, or remove your saved key, use oko auth login, oko auth status, or oko auth logout.

Benchmarks

Agent sessions

We give the same coding task to the same agent twice, once with its built-in search and once with Oko set up by oko setup, and compare the whole session: time, the agent's tokens, and tool calls. Nine tasks on pinned commits of Astro, HTTPX, and ripgrep: six ask for code spread over several places, three ask for a small edit checked by tests. The wording never names the file or function. Each task runs 3 times per setup with Codex, OpenCode, and Claude Code: 162 sessions, measured on the 0.7.0 code. With Oko, the agent starts with Oko's answer to the prompt and usually needs no search of its own: 63 of the 81 sessions with Oko made no Oko call.

With Oko, Codex passed 27 of 27, OpenCode 27 and Claude Code 25; without it, 26, 27 and 26. Three of the four misses are one Astro edit task, where the agent also changed an identical copy of the function in another file (Claude Code twice with Oko, Codex once without); the fourth is a Claude Code answer without Oko citing a line past the end of a file. Tokens and tool calls fell on all nine tasks for every tool, and time on all nine for Codex and OpenCode and eight for Claude Code. Against Oko without the prompt hook, as in earlier releases, tokens fell a further 35–40%. The other Claude Code hooks oko setup installs are not part of these sessions, which use no subagents. It is a small benchmark with Codex CLI 0.155 and OpenCode 1.18 (gpt-5.6-sol) and Claude Code 2.1 (claude-sonnet-5) at low reasoning effort; your results will vary. Full results and methodology, the runner, tasks, and checks, and the raw results are in this repository.

Against Sense

Sense publishes an agent benchmark: six multi-step tasks on real repositories answered by Claude Opus 4.7, scored and judged by its own harness. We ran it with Oko and with Sense on the same evening, five runs per task each.

Cited recall and relations come from one task (Discourse, 24 locations) run five times. With this Claude Code version (2.1.286), Sense went over its budget in 8 of 30 sessions and ran to the time limit in one; the harness scores what those sessions wrote. In our earlier paired run, on an older Claude Code, Sense scored 0.875. Details.

Agent Retrieval Bench

Agent Retrieval Bench has 345 tasks from 25 repositories in six languages: given a repository and a signal from a coding workflow (a failing test's output, a pull request, a review comment, a code change), find the files a developer needs next. Oko's numbers are the mean of three runs on the 0.7.0 code, scored with the benchmark's own code; the baselines were run locally on the same tasks and reproduce the published figures.

Each task is one search, so setup's prompt hook plays no part here. Per-task tables, the held-out split, what was tuned on what, and the limits are in the details.

SWE-Explore

SWE-Explore has 848 real issues from SWE-bench Verified, Pro and Multilingual in ten languages. The answer is the code that successful agents read while fixing each issue; an explorer returns five ranked regions. The agent rows are the paper's published results; they explore for many turns with a frontier model, while Oko makes one search of about a second.

On ranking and precision one Oko search sits among the agents; on finding every file an issue needs it does not, because five regions from one search cannot cover the 4.3 files an issue needs on average. Details.

Privacy

File discovery and initial search run locally. Jev ranking sends your question and selected source snippets to TypeSafe AI; with setup's prompt hook, a prompt that reads as a code question is searched as you send it, so its first paragraph is the question. Once a day Oko asks GitHub for the latest release number, and nothing else; --no-jev and OKO_NO_UPDATE_CHECK=1 turn that off. Deep mode can send more snippets across multiple requests. Use --no-jev for local-only searches. Oko does not edit your source files. Prepared search data is cached outside your repository; configuration explains key storage and cache controls.

Documentation

Help and contributing

Found a bug or have an idea? Open an issue. Include your OS, oko --version, and steps to reproduce, without API keys or private source code. For code changes, build from source and run:

cargo fmt --check
cargo clippy --all-targets --locked -- -D warnings
cargo test --locked

The Rust tests need no API key or private repository. Live benchmarks are optional.

License

MIT. Dependency attributions are in THIRD_PARTY_NOTICES.md.