indexio

indexio

indexio is a code search engine for AI coding agents. It indexes all the repositories of an organization one time. It answers a query in milliseconds. It gives the index to agents as a tool through the Model Context Protocol (MCP) and through an HTTP API.

indexio is one binary, written in Rust. It does not need a database or an external service. The index is a set of files in one data directory. You can copy that directory to another machine.

Let your agent install it

Paste the block below to Claude Code, Cursor, Codex or any coding agent that can run shell commands. It installs indexio, indexes your code, registers the MCP server and verifies the result. Replace ~/code with the folder that holds your repositories.

Install indexio (https://github.com/IOServicesLabs/indexio) on this machine and connect it

to me. Do these steps in order and stop at the first failure with the exact error.

1. Install the binary.

• Linux: curl -fsSL https://raw.githubusercontent.com/IOServicesLabs/indexio/main/install.sh | sh
• Windows (PowerShell): irm https://raw.githubusercontent.com/IOServicesLabs/indexio/main/install.ps1 | iex
• macOS (no prebuilt binary): cargo install --git https://github.com/IOServicesLabs/indexio indexio
• If the script fails, use pip install indexio-cli, npm install -g indexio, or the cargo install above. The binary lands in ~/.local/bin (Linux), %LOCALAPPDATA%\Programs\indexio (Windows) or ~/.cargo/bin (cargo). If indexio --version is not found afterwards, add that folder to PATH and open a new shell. git must be on PATH.

1. Index my code: indexio add ~/code This registers every git repository under the folder at any depth and builds the index. Nothing is uploaded; the index lives in ~/.indexio.

1. Register the MCP server with the agent you are.

• Claude Code: indexio setup claude --claude-md ~/.claude/CLAUDE.md then indexio hook install (the hooks route file reads and greps through the index; scripts and builds run as before)
• Any other MCP client: add this server to its MCP configuration and restart the client: command: indexio args: ["mcp"] Use the absolute path of the binary if the client does not search PATH.

1. Verify. All four must succeed:

• indexio --version prints a version
• indexio stats lists the repositories and a file count above zero
• indexio search "TODO" --limit 3 returns hits from my code
• indexio usage prints a report (it is empty until I use the tools)

1. Tell me what was installed, where the data directory is, which repositories were indexed, and that I must restart my agent session so it picks up the new MCP server. Do not modify any file inside my repositories.

What the agent gets afterwards: code_search, code_grep, find_symbol, who_calls, file_outline, read_span, impact_of_symbol, impact_of_diff and recall as tools, answered from the index in milliseconds. The tools table describes each one.

Install

Pick one. Each one gives you the indexio command.

The scripts and the npm package download the binary of the latest release for your OS and CPU and check its SHA-256. The pip wheels carry the binary inside them, one wheel per platform. The pip package is called indexio-cli because indexio on PyPI belongs to an unrelated project; the command it installs is indexio. The container image works with no install at all: see Deploy with Docker. git must be on the PATH. No service, no database and no model download is necessary.

Upgrade

Run the same install command again. The index in ~/.indexio stays, and you do not index again.

Then do two more steps:

1. Run indexio hook install. It adds the hooks that the new version brings and repairs the others. It keeps your own hooks.
2. Restart your agent sessions. A running session keeps its indexio server until it restarts.

Running sessions do not stop you from upgrading:

• The two scripts replace the binary while sessions use it. On Windows, install.ps1 moves the running indexio.exe to indexio.old.exe and copies the new one in.
• On Windows, npm and pip try to overwrite the binary in place, and Windows does not allow that while it runs. Close your agent sessions first, or use the script.
• Sessions that still run the old version can read an index that the new version wrote.
• The first new server does its one-time work in the background: it embeds files that have no vectors and it writes session cards. Calls are not blocked.

Quick start

Three commands. The third one is only for Claude Code.

indexio add ~/code            # 1. index every git repository under a folder

indexio search parse_config # 2. search it (add --mode hybrid for a question in words) indexio setup claude # 3. register the MCP server with Claude Code

Then restart Claude Code. Its sessions now have the indexio tools. Two optional commands make the savings larger:

indexio hook install          # reads and greps of indexed files go through the index

indexio sync # run from cron or a timer to keep the index current

indexio stats shows what is indexed. indexio usage shows the tokens the index served against what the built-in tools would have returned.

All data goes into one directory: --data-dir, $INDEXIO_DATA_DIR, or ~/.indexio.

Contents

1. Let your agent install it
2. What indexio does
3. Add sources
4. Keep the index current
5. Embeddings
6. What is never indexed
7. Secure the HTTP API
8. Team indexing: live worktree overlays
9. Enterprise setup
10. Use indexio with Claude Code
11. Token savings, measured
12. Impact analysis
13. Use indexio from other tools
14. Command reference
15. Environment variables
16. Deploy with Docker
17. Architecture
18. Measured performance
19. Limits
20. Development and releases

What indexio does

indexio answers three kinds of question about the code of an organization.

indexio also knows the definitions and the call graph of the code. It can tell you where a symbol is defined, who calls it, and what breaks if you change it.

Add sources

Each add indexes the source immediately and builds the semantic plane.

indexio add ~/code                             # every git repository under the folder, at any depth

indexio add /srv/checkouts/legacy-monolith # a folder without git: indexed as-is indexio add github:my-org # a GitHub organization or user indexio add github:my-org/payments # one GitHub repository indexio add azdo:my-org/Platform # an Azure DevOps project indexio add https://gitlab.example.com/g/r.git # any git host

Search:

indexio search parse_config

indexio search "how is backpressure applied" --mode hybrid

Serve the index to agents:

indexio mcp                           # MCP over stdio

indexio serve # HTTP API on http://127.0.0.1:7717

indexio remembers each source in /sources.json. indexio sources lists the sources and the registered repositories. indexio remove forgets a source.

Useful flags for add: --limit 20 (trial run on a large organization), --include-forks, --include-archived, --full-clone, --dest DIR (where remote clones go), --no-embed, --exclude PATH, --pdf-text.

Folders with repositories and other files. A folder often holds git repositories and files that are not in any repository: notes, specs, exports, PDFs. indexio add indexes each repository as a repository, and the other files as one more repository with the folder's name:

projectA/                     indexio add ~/projectA

├── backend/ (git) → repository "backend" ├── frontend/ (git) → repository "frontend" ├── docs/notes.md → repository "projectA": the contents ├── docs/spec.pdf → repository "projectA": the name only └── old-copy/ → left out with --exclude old-copy

• Text files are indexed by contents, up to the size limit (256 KiB for text, 4 MiB for code).
• Documents (PDF, Word, Excel, PowerPoint, OpenDocument, RTF, EPUB) and text files over the limit are indexed by name only. list_files and a search for words of the name find them. read_span on one says that its contents are not indexed; read the file itself. The hooks let a Read of such a file through.
• --pdf-text indexes the text layer of these PDFs instead of their name. A PDF that was exported from a document (Word, Google Docs, a browser) has one, so a search finds words inside it. A scanned PDF has no text layer and keeps its name-only entry: indexio does no OCR. The extracted text has the text size limit. A PDF over 64 MiB, or one that takes longer than 20 seconds to read, keeps its name-only entry. The option is remembered with the source.
• Images, media, archives and other binary files are not indexed.
• --exclude PATH (repeatable, relative to the folder) keeps a folder out: it is not a repository and its files are not indexed. Excludes are remembered with the source and accumulate when you run add again.
• A folder that is registered on its own is not indexed a second time.

Credentials. indexio reads credentials from the environment only: GITHUB_TOKEN (or GH_TOKEN)