Skip to content
Back to search

SolaScope

Local-first code search with incremental indexing, hybrid retrieval, and a read-only MCP server.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 21 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/wchiway/SolaScope with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/wchiway/SolaScope'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/wchiway--solascope/badge.svg)](/listings/wchiway--solascope)

HTML

<a href="/listings/wchiway--solascope"><img src="/api/listings/wchiway--solascope/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install both CLI entry points from a local checkout:

cargo install --path apps/solascope --locked

Development and validation use Rust 1.99; older toolchains have not been tested. SQLite is bundled, so no database service is required. Cargo installs both binaries into its bin directory, normally `~/.cargo/bin`; make sure that directory is on `PATH`.

To build without installing:

cargo build --release --locked -p solascope-cli --bins

The binaries are written to `target/release/`. `solascope` and `sas` accept the same commands and options and produce the same output.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 198 lines
  1. # SolaScope
  2. English | [简体中文](README.zh-CN.md)
  3. Local-first code search that turns a question, symbol name, keyword, or error message into a file, symbol, and line range. Use it from the terminal with `solascope` or `sas`, or connect an assistant through the read-only MCP server.
  4. SolaScope works without a model. SQLite FTS5 and symbol lookup provide the default search; optional embeddings and reranking add model-based retrieval.
  5. - **Incremental indexing.** Reparse changed files and request embeddings only for uncached inputs.
  6. - **Source locations.** Results include relative paths, symbols, line ranges, snippets, and a `stale` flag when the source changes.
  7. - **Structured parsing.** Tree-sitter extracts definitions from Rust, Python, JavaScript/JSX, TypeScript/TSX, and Go. Other text can use line-based chunks.
  8. - **Independent model providers.** Choose embedding and reranking services separately, including Ollama, OpenAI-compatible APIs, DashScope, SiliconFlow, and optional local ONNX reranking.
  9. - **One search engine.** The CLI, MCP server, and benchmark tools share the same indexing and retrieval implementation.
  10. Current version: **0.1.0**. See [support and limitations](docs/implementation-status.md) for the tested scope.
  11. ## Architecture at a glance
  12. ![Hand-drawn overview: CLI and read-only MCP share an Engine that scans repository source, reads and writes a local SQLite index, and optionally calls embedding and reranking models.](docs/assets/solascope-overview.png)
  13. The CLI and MCP server share one engine and index. Indexing scans and parses source locally; model adapters are optional. See the [architecture](docs/architecture.md) for publication, caching, and consistency details.
  14. ## Install
  15. Install both CLI entry points from a local checkout:
  16. ```bash
  17. cargo install --path apps/solascope --locked
  18. ```
  19. Development and validation use Rust 1.99; older toolchains have not been tested. SQLite is bundled, so no database service is required. Cargo installs both binaries into its bin directory, normally `~/.cargo/bin`; make sure that directory is on `PATH`.
  20. To build without installing:
  21. ```bash
  22. cargo build --release --locked -p solascope-cli --bins
  23. ```
  24. The binaries are written to `target/release/`. `solascope` and `sas` accept the same commands and options and produce the same output.
  25. ## Quick start
  26. Run these commands in the repository you want to search:
  27. ```bash
  28. solascope init
  29. solascope index
  30. sas search "where are database transactions committed"
  31. sas status
  32. ```
  33. `init` creates a user configuration file and leaves an existing file untouched:
  34. | Platform | User configuration |
  35. | --- | --- |
  36. | Linux / macOS | `~/.solascope/.solascope.toml` |
  37. | Windows | `$USERPROFILE/.solascope/.solascope.toml` |
  38. It does not create a project configuration or bind the user defaults to the current repository. You can run `index` directly with the built-in defaults: it recursively scans the **current working directory and all levels of subdirectories**, subject to ignore rules and privacy filters. An explicit positional path takes precedence over `--root`, followed by the process environment variable `SOLASCOPE__PROJECT__ROOT`; otherwise the current directory is used without expanding to a parent Git root.
  39. A project `.solascope.toml` can supply settings, including one discovered in a parent directory or selected with `--config`. Its location and any `project.root` value in TOML or a sibling `.env` do not select the source directory. `project.index_dir` controls only where index data is stored. Search, status, and watch use the same directory selection rules.
  40. Create an optional project ignore file:
  41. ```bash
  42. solascope ignore
  43. # Equivalent: sas ignore
  44. ```
  45. This creates `.solascopeignore` in the project root with commented gitignore-style examples, without overwriting an existing file. Use `ignore /path/to/project` or `ignore --root /path/to/project` to select another root. Edit the file to exclude files or directories; see the [ignore-file reference](docs/configuration.md#ignore-files) for syntax and privacy restrictions.
  46. Keep the index up to date while editing:
  47. ```bash
  48. solascope index --watch
  49. ```
  50. Results identify a relative path, a 1-based line range, a symbol when available, a score, and a source snippet. After changing source files, run `index` again or leave a watcher running.
  51. ## CLI
  52. | Command | Purpose |
  53. | --- | --- |
  54. | `init [--probe]` | Create user defaults; optionally probe the configured models |
  55. | `ignore [path]` | Create `.solascopeignore` in the project root without overwriting existing rules |
  56. | `index [path] [--rebuild] [--probe]` | Recursively index the current directory or an explicit path; rebuild all chunks when requested |
  57. | `index [path] --watch` | Index once, then watch for changes; `--no-watch` overrides `index.watch` |
  58. | `search <query>` | Search code with optional embeddings and reranking |
  59. | `symbol <name> [--kind K]` | Find definitions by exact, prefix, substring, or limited fuzzy matching |
  60. | `context <path>[:line]` | Read current source, up to 200 lines or 64 KiB |
  61. | `status` | Show the index generation, counts, relocated vectors, and model fingerprint |
  62. | `watch [path] [--probe]` | Watch and incrementally update an index |
  63. | `mcp [--probe]` | Start the read-only stdio MCP server |
  64. | `doctor [--models] [--prune-cache]` | Check configuration and index consistency, probe models, or prune unused cache entries |
  65. Common options include `--root`, `--config`, `--json`, `--limit` (1–100), `--mode lexical|semantic|hybrid`, `--path`, `--no-rerank`, and `--verbose`.
  66. - `lexical` retrieves from FTS5.
  67. - `semantic` retrieves from vectors and requires an embedding provider.
  68. - `hybrid` combines lexical, symbol, and optional vector results with reciprocal rank fusion (RRF).
  69. Reranking can be enabled independently of the retrieval mode. With `--json`, stdout contains one JSON result; warnings and errors go to stderr, and progress follows the log configuration. In watch mode, only the initial indexing report is written to stdout.
  70. Exit codes: `0` success, `1` internal/storage/I/O error, `2` invalid input or configuration, `3` missing or outdated index, `4` model failure or incompatibility, `5` writer lock conflict, and `130` interruption.
  71. ## How search works
  72. ![Hand-drawn query flow: query, mode-specific retrieval, RRF fusion, source checks, optional reranking, another source check, and deduplicated file, symbol, and line results.](docs/assets/solascope-search-flow.png)
  73. The selected mode determines which retrieval channels run. Source checks filter blocked paths and mark stale code before reranking, then run again afterward. Reranking uses non-stale candidates, and final results are deduplicated by entity. See the [search pipeline](docs/architecture.md#search-pipeline).
  74. ## Models and configuration
  75. Embedding and reranking are disabled by default. Enable either through the user configuration or a project override:
  76. | Capability | Providers |
  77. | --- | --- |
  78. | Embeddings | `ollama`, `openai`, `remote`, `dashscope`, `siliconflow` |
  79. | Reranking | `remote`, `openai`, `dashscope`, `siliconflow`, `fastembed` |
  80. HTTP model providers require `privacy.remote_opt_in = true`, except for Ollama on a loopback address. The reranking provider named `openai` supports a vendor-compatible request format; check the service's reranking API before configuring it. Local `fastembed` reranking requires a build with `--features local-rerank`, a compatible ONNX Runtime, and model files.
  81. Store API keys in a `.env` beside the configuration file, using variable names such as `DASHSCOPE_API_KEY` and `SILICONFLOW_API_KEY`. The TOML configuration references those names through `api_key_env`. Existing process variables take precedence. Restart a watcher or MCP server after changing `.env`.
  82. CLI diagnostics are also appended to `logs/solascope.log` beside the active configuration, normally `~/.solascope/logs/solascope.log` on Linux/macOS or `$USERPROFILE/.solascope/logs/solascope.log` on Windows. Retry status and final failures are recorded with credentials redacted. Set `log.persist = false` to keep stderr only.
  83. The [configuration reference](docs/configuration.md) covers every field, precedence rule, provider protocol, and setup example.
  84. An embedding index is bound to a fingerprint of the provider, model, endpoint, dimensions, normalization, and input template. After changing the embedding setup, rebuild the index:
  85. ```bash
  86. solascope index --rebuild
  87. ```
  88. Changing the reranker or rotating an API key does not require a rebuild. Parser configuration changes trigger reparsing on the next indexing run. Read-only queries report an outdated index instead of migrating it.
  89. ## MCP integration
  90. From the project directory, build an index and start the server:
  91. ```bash
  92. solascope index
  93. solascope mcp
  94. ```
  95. A client configuration can use:
  96. ```json
  97. {
  98. "mcpServers": {
  99. "solascope": {
  100. "command": "solascope",
  101. "args": ["mcp"]
  102. }
  103. }
  104. }
  105. ```
  106. The server exposes `search_code`, `find_symbol`, `get_code_context`, and `index_status`, with read-only annotations and typed output schemas. No startup path is required: tools default to the server's working directory and accept an optional `root` so agents can select another project per call. Each project's index defaults to its `.solascope/` directory. The server reads updates from a separate `index` or `watch` process without restarting. Context reads current source even without an index. See [MCP integration](docs/mcp.md) for tool parameters, responses, and client setup.
  107. ## Privacy
  108. The built-in defaults use no models and send no code to a model service. Enabling remote embeddings or reranking can send indexed code snippets to the configured provider.
  109. Source access stays within the project root and follows ignore rules. Sensitive paths, including `.env` files, private keys, and credential directories, are always excluded from indexing and source-context reads. API keys are referenced by environment-variable name and redacted from application diagnostics. Endpoints cannot contain credentials, query strings, or fragments; model HTTP clients do not follow redirects.
  110. The index contains source snippets and is stored in the project's `.solascope/` directory by default. Keep it out of version control and shared artifacts. See the [configuration reference](docs/configuration.md#privacy) for the full privacy settings and excluded paths.
  111. ## Documentation and development
  112. - [Configuration](docs/configuration.md)
  113. - [MCP integration](docs/mcp.md)
  114. - [Architecture](docs/architecture.md)
  115. - [Benchmark guide](benchmarks/README.md) and [recorded measurements](docs/benchmarks.md)
  116. - [Support and limitations](docs/implementation-status.md)
  117. ```bash
  118. cargo test --workspace --all-targets --locked
  119. cargo test --workspace --all-targets --locked --features local-rerank
  120. cargo clippy --workspace --all-targets --locked -- -D warnings
  121. cargo fmt --all -- --check
  122. ```
  123. GitHub Actions is configured to run workspace formatting, Clippy, default tests, and package tests on Linux, macOS, and Windows, with `local-rerank` tests in a separate Linux job. After all checks pass, a reusable workflow builds both CLI binaries and packages them with public documentation and `SHA256SUMS`: `.tar.gz` on Unix, `.zip` on Windows, named by version and Rust target. Runs reuse Rust dependency caches and cancel superseded runs.
  124. Following zoxide's release convention, a `main` push whose commit message starts with `chore(release)` creates a **draft GitHub Release** after CI succeeds. The release workflow reuses the three platform packages, verifies their contents and checksums, and combines their checksum entries into one `SHA256SUMS`. Maintainers can also run `release.yml` manually on `main`, supplying the ID of a successful `ci.yml` run from `main`. The tag is `v<workspace version>` and targets that run's source commit; existing releases are rejected, and existing tags must match the source commit. Drafts require manual review and publication. Publishing to crates.io is not configured. See [release operations](docs/implementation-status.md#release-operations) for the procedure and validation limits.
  125. Package and release-collection tests can also run locally with Python 3.9 or newer:
  126. ```bash
  127. python -I -B -m unittest discover -s .github/scripts -p 'test_*.py' -v
  128. ```
  129. Linux CLI builds, installation, and automated tests have been exercised. Model protocol tests use local mock servers. Live model quality, local ONNX inference, macOS/Windows execution, commercial MCP clients, remote CI packages, and GitHub draft-release creation still need validation.
  130. ## License
  131. [Apache License 2.0](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.