sherpa-code 0.1.2

Local-first, evidence-backed codebase intelligence CLI

Sherpa

Sherpa is a local-first codebase intelligence tool. It will turn source code into an evidence-backed graph of files, symbols, and relationships.

The project is under active development. Sherpa indexes C, C++, and Python files and uses tree-sitter to extract functions, methods, classes, structs, includes/imports, calls, source locations, and parser diagnostics into a local SQLite database. It records evidence-backed defines, calls, and includes relationships while preserving ambiguous and unresolved references.

Build

Prerequisites: a C++20 compiler, CMake 3.25+, Ninja, and vcpkg.

cmake --preset dev -DCMAKE_TOOLCHAIN_FILE="$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake"
cmake --build --preset dev
ctest --preset dev

Install

Milestone 16 prepares three release channels:

# Homebrew tap
brew install sre0089/tap/sherpa

# PyPI CLI distribution (recommended)
pipx install sherpa-code

The PyPI distribution is named sherpa-code because sherpa belongs to an unrelated project. It still installs the sherpa and sherpa-server commands. These commands become available after the first signed-off release is published and the external Homebrew tap and PyPI trusted publisher are configured. Native archives are attached directly to each GitHub release.

See Installation for platforms and verification.

Sherpa also installs a C++20 library and CMake package. Embedded consumers use <sherpa/api/client.hpp> and link Sherpa::Sherpa; see the public C++ API. Hosts can also register explicitly linked observers through the versioned plugin API.

Editor integrations can launch the installed sherpa-server JSON-RPC process. See editor integration and the initial VS Code extension.

Use

./build/dev/sherpa index /path/to/repository
cd /path/to/repository
sherpa query symbol qualified::symbol
sherpa query symbol overloaded --signature 'overloaded(int value)'
sherpa query file src/file.cpp
sherpa query callers qualified::symbol
sherpa query callees qualified::symbol
sherpa callers qualified::symbol
sherpa callees qualified::symbol
sherpa impact src/file.cpp
sherpa impact qualified::symbol
sherpa path caller::symbol callee::symbol
sherpa export graph.json

Queries use the current directory as the repository by default. sherpa query ... is the grouped read-only query surface; the top-level callers and callees commands remain as compatibility aliases. Use --repo <path> to query another repository, --database <path> to override the platform cache location, and --format json for machine-readable output. See Indexing for incremental refresh behavior, Querying the graph for lookup rules, and the Query JSON contract for automation. See Graph export for the versioned interchange format. Release process documents artifact creation and publisher setup.

Status

Sherpa currently discovers .c, .cc, .cpp, .cxx, .h, .hh, .hpp, .hxx, .inc, .py, and .pyi files. It performs syntax-based analysis only: overload resolution, type inference, dynamic dispatch, preprocessor expansion, and compiler/interpreter-accurate semantics are not implemented. Call and dependency resolution is intentionally conservative and every result carries status, confidence, and provenance.

License

Sherpa is available under the MIT License.