dissolution

Don't just embed your repo, dissolve into it.

dissolution indexes one or more directories into per-repo SQLite databases using sqlite-vec, keeps them synced with filesystem watchers, and gives you both a CLI search flow and a local browser UI.

Why dissolution?

• No external vector DB — just SQLite files in your repos.
• Multi-directory indexing — add as many paths as you want.
• .gitignore aware — indexing and sync respect ignore rules.
• Background daemon UX — dissolve start, then dissolve web.
• Agent-ready — dissolve onboard + pi extension package.

Install

Rust CLI

cargo install dissolution

pi extension package

pi install npm:@hyperprior/dissolution

Quickstart

# 0) Default embedder is OpenAI (set your key once)
export OPENAI_API_KEY=...

# Optional: switch to local/offline embeddings instead
dissolve config set embedding.provider local

# 1) Start background daemon + UI + watchers
dissolve start

# 2) Open UI (no need to remember the port)
dissolve web

# 3) Add directories
dissolve add .
dissolve add ~/projects/notes

# 4) Search semantically
dissolve search "where do we configure retries"

# 5) Print agent onboarding prompt
dissolve onboard

CLI

dissolve [--verbose] <command>

dissolve start [--port 7700] [--no-open]
dissolve web
dissolve stop

dissolve add PATH [--db PATH]
dissolve remove PATH
dissolve reindex PATH

dissolve search "query" [--limit 10] [--repo FILTER] [--json]
dissolve status
dissolve onboard [--mcp]
dissolve mcp
dissolve print-config

dissolve config get [KEY]
dissolve config set KEY VALUE

Embedding config

dissolve reads config from .dissolve/config.toml (or DISSOLVE_CONFIG_PATH).

Defaults:

• provider: openai
• model: text-embedding-3-large
• key env: OPENAI_API_KEY

Examples:

dissolve config get embedding.provider
dissolve config set embedding.model text-embedding-3-small
dissolve config set embedding.provider local

# inspect indexing progress and embedding batches
dissolve --verbose add .

Agent onboarding

dissolve onboard prints a prompt you can paste into Claude/Codex/pi-style agents. Use dissolve onboard --mcp for an MCP-first prompt.

1. run dissolve search first for repo/docs questions,
2. cite file_path:line_start, and
3. fall back to exact grep when needed.

pi extension setup

Install with:

pi install npm:@hyperprior/dissolution

If you prefer manual config, add:

{
  "extensions": ["@hyperprior/dissolution"]
}

The extension exposes a tool that routes semantic queries to local:

dissolve search "..." --json

Prefer MCP? Run:

dissolve mcp

and use dissolve onboard --mcp to print a ready mcpServers snippet.

Docs site (Astro + Starlight)

Docs live in docs/ and are designed for Cloudflare Pages deployment.

cd docs
bun install --linker hoisted
bun run dev

Testing

BDD-style tests are implemented with cucumber + Gherkin.

cargo test
# or
cargo test --test bdd

GitHub Actions publishing

• Crates.io: .github/workflows/publish-crate.yml (on push/merge to main)
• npm package (@hyperprior/dissolution): .github/workflows/publish-npm.yml (on push/merge to main)

Docs are deployed by Cloudflare's Git integration (no docs deploy GitHub Action).