Akin

Semantic code search for AI agents and CLI users. Finds code by meaning rather than exact text match. Works as both a CLI tool and an MCP (Model Context Protocol) server. Runs entirely locally — no API keys, no external services.

Built on the VectorSharp libraries, using the Nomic Embed Text v1.5 model via ONNX for embeddings and VectorSharp.Chunking for structure-aware chunking of Markdown, C#, JavaScript/TypeScript/JSX/TSX, HTML, CSS, Python, and plain text.

Installation

Install script (macOS / Linux)

curl -fsSL https://raw.githubusercontent.com/AdamTovatt/akin/master/install-akin.sh | bash

This detects your platform, downloads the latest release, verifies its SHA256 checksum, and installs the akin binary to /usr/local/bin. Requires only curl, unzip, and sha256sum/shasum — all standard on macOS and Linux. Run the same command again to update.

Updaemon (Linux)

If you use updaemon for managing tools:

updaemon new akin --from github --remote AdamTovatt/akin/akin-linux-arm64.zip --type cli
updaemon set-exec-name akin Akin.Cli
updaemon init akin

Replace akin-linux-arm64.zip with akin-linux-x64.zip on x86_64 systems. Future updates via updaemon update.

.NET tool

dotnet tool install --global Akin

After installation, the akin command is available globally.

Update: dotnet tool update --global Akin. Uninstall: dotnet tool uninstall --global Akin.

MCP registration

To register as an MCP server in Claude Code:

claude mcp add akin -- akin --mcp

For Cursor or other MCP clients, add to your MCP configuration:

{
  "mcpServers": {
    "akin": {
      "command": "akin",
      "args": ["--mcp"]
    }
  }
}

Usage

akin search <query> [--max N] [--snippets] [--max-per-file N]   # Semantic search
akin status                                                     # Show index status
akin reindex                                                    # Force a full reindex
akin --mcp                                                      # Run as MCP server
akin --version                                                  # Show version
akin help                                                       # Show help

Examples

# Natural-language query across the current repository (paths and line ranges only)
akin search "where do we handle authentication failures"

# Cap the number of files returned
akin search "database connection pooling" --max 5

# Drill in on a focused query — include the chunk text inline
akin search "error handling" --snippets

# Only show the single best match per file (most compact survey)
akin search "cosine similarity" --max-per-file 1

# Check whether the index is built and current
akin status

Search output

Results are grouped by file. Each file carries an aggregate score (the maximum score across its matching chunks) and up to --max-per-file matching regions with their own line ranges. Defaults are tuned for cheap survey output: paths and line ranges only (no snippet text), capped at 3 regions per file. Excess matches in a file are summarized as +N more matches not shown. Pass --snippets for the inline chunk text when drilling in, and raise --max-per-file (or set it to 1) to widen or narrow per-file detail.

How it works

Akin stores its index in a .akin/ folder at the repository root. Add .akin/ to your .gitignore to keep it out of version control. The folder contains three files:

• vectors.bin — the vector store in VectorSharp's binary format
• chunks.json — chunk metadata (file path, line range, content hash, text)
• manifest.json — embedding model identifier, dimension, chunker fingerprint, schema version

On startup, Akin compares the stored manifest against its current configuration. If the embedding model or chunker has changed, the index is rebuilt automatically. If copied to a new worktree (e.g. via worktree-initializer), the index is reused and only the changed files are re-embedded.

Files indexed

Akin runs git ls-files to enumerate tracked files, so the set of indexed files exactly matches what you have chosen to version. Binary files are detected by scanning the first 8KB for null bytes and skipped. Files larger than 1MB are skipped.

Chunking

Files are chunked using the predefined VectorSharp.Chunking format for their extension:

Extension	Format
.md, .markdown	Markdown
.cs	C#
.js, .jsx, .ts, .tsx, .mjs, .cjs	JavaScript
.html, .htm	HTML
.css, .scss	CSS
.py, .pyi	Python
anything else	plain text

Incremental updates (MCP mode)

When running as an MCP server, Akin watches the repository for file changes via FileSystemWatcher and debounces events into batched incremental reindexes. A periodic reconciliation every five minutes diffs the current tracked set against the index to catch events the watcher may have dropped, as well as files that have become gitignored or newly tracked.

In CLI mode (short-lived invocations), no watcher is used — each invocation opens the existing index, runs the command, and exits.

As MCP server

akin --mcp

When running as an MCP server, the following tools are available:

• akin_search(query, maxResults?, includeSnippets?, maxRegionsPerFile?, paths?, excludePaths?, includeTypes?) — Semantic code search
• akin_status() — Report index state, file and chunk counts, compatibility
• akin_reindex() — Force a full rebuild of the index

When to use akin vs. grep

Akin and grep are complementary, not alternatives. The right mental model is akin for discovery, grep for completeness:

• Use akin when you don't yet know the vocabulary the codebase uses. Questions like "how do we handle backwards compatibility" or "where do we deal with rate limiting" are good fits — the concept has no single keyword to grep for.
• Use grep when the concept has a unique, greppable marker: an attribute name ([JsonPolymorphic]), a distinctive identifier, an exact error string. Grep is faster and more precise when you already know what to search for.
• Combine them. Semantic ranking has silent recall gaps — a relevant file may be missing from the results without any indication, so don't treat akin's output as exhaustive. A common workflow is akin first to learn the vocabulary (attribute names, doc-comment phrasing, type names), then grep on those terms to enumerate every occurrence.

Development

git clone <repository-url>
cd akin
dotnet build Akin.slnx
dotnet test Akin.slnx

Run as MCP server during development:

dotnet run --project Akin.Cli/Akin.Cli.csproj -- --mcp

Package locally:

dotnet pack Akin.Cli/Akin.Cli.csproj --configuration Release

License

MIT License