Personal code search engine · 100% local · citation-grounded

neus Your code project search engine with top-notch neus ask.

The speedy, local-first search engine for codebases, YAML specs, and architecture docs. High-precision ranking and Go AST parsing turn your index into an authoritative source of truth, enhanced by fast local LLMs and cloud fallbacks.

go install ubunatic.com/neus/cmd/neus@latest

Engineering story View source Product home

Project snapshot · measured 2026-10-26

Key facts

Commits 458Last commit 2026-10-26 Source receipt ↗ Commits · 7 days 229 Source receipt ↗ Tickets closed 70 / 100 Source receipt ↗ Studies 33 Source receipt ↗

12-week commit activity

2026-10-26

Aug 3

Aug 10

Aug 17

Aug 24

Aug 31

Sep 7

Sep 14

141

Sep 21

Sep 28

Oct 5

Oct 12

130

Oct 19

View 12-week data table

Week starting	Commits
2026-08-03	0
2026-08-10	0
2026-08-17	0
2026-08-24	0
2026-08-31	0
2026-09-07	0
2026-09-14	0
2026-09-21	141
2026-09-28	34
2026-10-05	9
2026-10-12	4
2026-10-19	130

Key Features

Top-notch neus ask: citation-grounded architecture and code question answering.
Speedy local index as the single source of truth, combining FTS5 lexical ranking and vector semantics.
Pure-Go AST symbol parsing (declarations, docstrings, struct receivers) and hierarchical YAML specs.
Secret-safe indexing ignoring 6 credential groups via spec/ignore.yaml.
Automated stale chunk pruning and truthful status telemetry with DB-backed vector backlogs.

Verified Engineering Milestones

Batched embeddings across files and throughput scaling (#030, 979fba9)
Public neus classify CLI with deterministic matching (#041, b4b582f)
Epic 097: Chunk pruning, secret ignore catalog, and truthful status telemetry (#093, #094, #096, 2abe792)

Stack

Go 1.25.0, Cobra, Goldmark, SQLite/FTS5, HTTP inference APIs, Qwen/Nomic, llama-server fallback

Personal Search Engine

Google-grade discovery for your code projects

Think of neus as a personal search engine for your repositories: combining keyword matching and vector semantics, with the speedy local index remaining the absolute source of truth. Everything else—from AST symbol resolution to local and cloud LLM answers—flows from this solid index baseline.

The core runs 100% locally in pure Go and SQLite without bundled Python dependencies, querying local inference backends for embeddings and using intelligent cloud fallback (such as Codex CLI) only when needed.

Architecture & Invariants

Evidence-driven code intelligence

Top-Notch neus ask

Answers complex architecture and implementation questions with strictly numbered, verifiable source citations. Declines to invent facts when passages are missing.

Index as Source of Truth

A blazing-fast SQLite FTS5 and vector index storing parsed Go AST symbols (structs, receiver methods) and hierarchical YAML spec keys.

Reciprocal Rank Fusion (RRF)

Blends lexical BM25 hits and semantic vector cosine distances into an optimal rank formula, surfacing the exact defining code rather than vague matches.

Secret-Safe Indexing (Epic 097)

Automatically filters 6 secret categories (tokens, keys, .env, statefiles) using spec/ignore.yaml, with hardened symlink protection.

Live Chunk Pruning (Epic 097)

Prunes orphaned code and spec chunks automatically as files are deleted or moved, keeping database footprint lean and search results fresh.

Truthful Telemetry & Status

neus status provides real-time vector queue progress, DB-backed backlogs, scan timestamps, and persistent state across restarts.

CLI Workflow

Search, ask & evaluate

# Index the current repository
$ neus index .

# Inspect indexing status and vector queue
$ neus status

# Search Go AST declarations and specs by meaning
$ neus search --root . --kind code "Go AST receiver methods"

# Ask grounded questions with numbered source citations
$ neus ask --root . "How does RRF calculate fusion scores?"

Project details

Stack

Go 1.25.0, Cobra, Goldmark, SQLite/FTS5, HTTP inference APIs, Qwen/Nomic, llama-server fallback

Milestones

Batched embeddings across files and throughput scaling (#030, 979fba9) · Public neus classify CLI with deterministic matching (#041, b4b582f) · Epic 097: Chunk pruning, secret ignore catalog, and truthful status telemetry (#093, #094, #096, 2abe792)

Source

https://codeberg.org/ubunatic/neus ↗

Architecture

Layer composition

Terminal: CLI, TTY status layout, streaming responses
Desktop: Linux
Inference / AI: nomic-embed-text, Qwen2.5/Qwen3, llama-server, GBNF
Containers / VM: —
Web: —

Engineering story

neus: the story behind the project

Neus began as a practical search tool: help an agent find the right passage in a large repository when the query and the code use different words. It combines ordinary keyword retrieval with vector similarity, then groups results by file. O…

Read the engineering story

Measurement source · 2026-10-26

Verification receipts

Commits: 458 · Last commit 2026-10-26
git -C <repo> rev-list --count HEAD; git -C <repo> rev-list --count --since=<ISO-week-Monday> --until=<ISO-week-Sunday> HEAD; git -C <repo> rev-list --count --since=<measured-date-6-days>T00:00:00 --until=<measured-date>T23:59:59 HEAD; git -C <repo> log -1 --format=%cs HEAD; ls <repo>/issues | grep '^[0-9].*\.md$'; grep -l -E '^\*\*Status\*\*: *(Closed|Done|Resolved|Fixed|Complete)' <repo>/issues/*.md | wc -l; ls <repo>/docs/studies/*.md
repositories behind spec project ids in ~/projects; private-repo filter is a safety net and matches no spec project today; missing repos reported separately; seven calendar days ending on measured date in the measuring host's local timezone; commit counts include all authors and merge commits reachable from HEAD · measured 2026-10-26
Commits · 7 days: 229
git -C <repo> rev-list --count HEAD; git -C <repo> rev-list --count --since=<ISO-week-Monday> --until=<ISO-week-Sunday> HEAD; git -C <repo> rev-list --count --since=<measured-date-6-days>T00:00:00 --until=<measured-date>T23:59:59 HEAD; git -C <repo> log -1 --format=%cs HEAD; ls <repo>/issues | grep '^[0-9].*\.md$'; grep -l -E '^\*\*Status\*\*: *(Closed|Done|Resolved|Fixed|Complete)' <repo>/issues/*.md | wc -l; ls <repo>/docs/studies/*.md
repositories behind spec project ids in ~/projects; private-repo filter is a safety net and matches no spec project today; missing repos reported separately; seven calendar days ending on measured date in the measuring host's local timezone; commit counts include all authors and merge commits reachable from HEAD · measured 2026-10-26
Tickets closed: 70 / 100
git -C <repo> rev-list --count HEAD; git -C <repo> rev-list --count --since=<ISO-week-Monday> --until=<ISO-week-Sunday> HEAD; git -C <repo> rev-list --count --since=<measured-date-6-days>T00:00:00 --until=<measured-date>T23:59:59 HEAD; git -C <repo> log -1 --format=%cs HEAD; ls <repo>/issues | grep '^[0-9].*\.md$'; grep -l -E '^\*\*Status\*\*: *(Closed|Done|Resolved|Fixed|Complete)' <repo>/issues/*.md | wc -l; ls <repo>/docs/studies/*.md
repositories behind spec project ids in ~/projects; private-repo filter is a safety net and matches no spec project today; missing repos reported separately; seven calendar days ending on measured date in the measuring host's local timezone; commit counts include all authors and merge commits reachable from HEAD · measured 2026-10-26
Studies: 33
git -C <repo> rev-list --count HEAD; git -C <repo> rev-list --count --since=<ISO-week-Monday> --until=<ISO-week-Sunday> HEAD; git -C <repo> rev-list --count --since=<measured-date-6-days>T00:00:00 --until=<measured-date>T23:59:59 HEAD; git -C <repo> log -1 --format=%cs HEAD; ls <repo>/issues | grep '^[0-9].*\.md$'; grep -l -E '^\*\*Status\*\*: *(Closed|Done|Resolved|Fixed|Complete)' <repo>/issues/*.md | wc -l; ls <repo>/docs/studies/*.md
repositories behind spec project ids in ~/projects; private-repo filter is a safety net and matches no spec project today; missing repos reported separately; seven calendar days ending on measured date in the measuring host's local timezone; commit counts include all authors and merge commits reachable from HEAD · measured 2026-10-26
12-week commit activity
git rev-list --count --since=<Monday> --until=<Sunday> HEAD
12 latest complete ISO weeks; weekly values are from spec/metrics.yaml.