hSUM 0.1.0-alpha.4

hSUM / docs 0.1.0-alpha.4 / quickstart

Quickstart

From a clean checkout to a cited search result. Nothing leaves your machine.

Requirements

1. Install and connect Codex

Run these commands from the Git repository you want hSUM to index. The version-pinned installer verifies the release archive, installs without sudo, registers one user-wide Codex MCP server, activates this exact repository, and completes an end-to-end citation probe.

version=0.1.0-alpha.4
base_url="https://github.com/burkan2/hSUM/releases/download/v$version"
curl -fsSLO "$base_url/install-hsum.sh"
curl -fsSLO "$base_url/SHA256SUMS"
grep ' install-hsum.sh$' SHA256SUMS | shasum -a 256 -c -
bash install-hsum.sh --activate . --confirm

Unsigned macOS prerelease

The linker-generated ad-hoc signature passes codesign --verify, but the alpha.4 binary has no Developer ID identity and is not notarized. On first launch, the installer requires the explicit --allow-unnotarized-alpha flag after you verify its checksum and read this warning.

On macOS, repeat the final command as:

bash install-hsum.sh --activate . --confirm --allow-unnotarized-alpha

Confirm the installed integration at any time:

hsum --version
hsum integration status codex --json
Build from source instead 
git clone https://github.com/burkan2/hSUM.git
cd hSUM
cargo build --locked --release

This requires Rust 1.91.0, pinned in rust-toolchain.toml. The binary lands at target/release/hsum.

2. Initialize an index manually (optional)

The installer already activates and indexes the selected repository. For a manual or non-Codex setup, run init from inside the repository you want indexed. hSUM selects the enclosing Git root by default.

hsum init .

Real output:

hSUM index initialized.
Root: /path/to/repo
Index: repo
Project: default
Data: ~/.local/share/hsum/indexes/repo/index.sqlite
Binding: 495d788b-897c-46b6-86c2-5d28d80b3d42
Eligible files: 2
Eligible bytes: 194
Skipped files: 0
Pointer: not requested
Active documents: 2
Active passages: 2
Lexical search is ready. No model or network was used.

Save that binding UUID. It authorizes MCP access to this project and is required by hsum mcp --binding.

Preview first

Use hsum init . --dry-run to inspect file selection and corpus estimates without writing anything.

3. Search

hsum search 'bearer token'
1  repo://src/auth.rs:1-4  [metadata_unchanged]
   BM25 #1
   /// Validate a bearer token against the session store.
   citation: 'hsum://v1/30bf24f0-.../c06745b2-...?rev=a893b630...#bytes=0-152'
stop: unique_exhausted

Each result carries a citation. That string is the durable handle to the passage.

4. Resolve a citation

hsum get 'hsum://v1/30bf24f0-.../c06745b2-...?rev=a893b630...#bytes=0-152'
Citation: hsum://v1/30bf24f0-.../c06745b2-...?rev=a893b630...#bytes=0-152
Source: repo://src/auth.rs
Title: auth.rs
Lines: 1-4
Source hash: not_requested
Content: /// Validate a bearer token against the session store.

Quote the citation in your shell — it contains ? and #, which most shells will otherwise interpret.

5. Refresh after edits

hSUM has no file watcher in alpha.4. Re-run ingest after changing files:

hsum ingest

Each run commits one atomic generation. Existing citations keep resolving to the revision they pinned.

Upgrading an alpha.1 index

Indexes created by alpha.1 use an older indexing pipeline. If a command reports PIPELINE_FINGERPRINT, rebuild the trusted index under the current rules:

hsum init --rebuild --dry-run
hsum init --rebuild

The dry run previews the replacement without writing. The rebuild creates a new index and trust binding, then removes the old index. Evidence and citations created by alpha.1 do not survive this replacement.

Alpha.2 and alpha.3 indexes do not need a rebuild for alpha.4. Existing citations continue to resolve; restart any in-flight MCP pagination after replacing the binary.

Next