sgrep

Name: sgrep
Author: XiaoConstantine

15stars2forks

How to install sgrep?

xiaoconstantine/sgrep

$npx -y skills add XiaoConstantine/sgrep

Installs into the current project.

Summary

semantic grep

Files · 1

View on GitHub

README.md

1	# sgrep
2
3	Local semantic and hybrid search for codebases and coding-agent history.
4
5	Find implementation by intent, then recover the decisions and fixes that led
6	to it across Claude Code, Codex, Cursor, OpenCode, and Pi sessions.
7
8	[Documentation](https://xiaocui.me/sgrep/) ·
9	[Getting started](https://xiaocui.me/sgrep/guides/getting-started/) ·
10	[CLI reference](https://xiaocui.me/sgrep/reference/cli/) ·
11	[Agent skill](SKILL.md)
12
13	## Why sgrep?
14
15	- Search code by meaning instead of guessing identifiers.
16	- Search prior agent sessions without reopening transcripts one by one.
17	- Keep source, conversations, models, and indexes on your machine.
18	- Give coding agents compact file-and-line results instead of large context dumps.
19
20	```bash
21	sgrep "where do we validate authentication tokens"
22	sgrep conv "why did we change the authentication cache key"
23	```
24
25	## Install
26
27	```bash
28	brew tap XiaoConstantine/tap
29	brew install sgrep
30
31	# Download the local embedding model and verify llama.cpp.
32	sgrep setup
33	```
34
35	See the [installation guide](https://xiaocui.me/sgrep/guides/getting-started/)
36	for curl, Go, source builds, and sqlite-vec.
37
38	## Search a Codebase
39
40	```bash
41	cd your-repository
42	sgrep index .
43
44	sgrep "database connection error handling" # balanced, the default
45	sgrep --profile fast "request routing" # lowest latency
46	sgrep --profile quality "JWT validation middleware" # optional ColBERT reranking
47	```
48
49	\| Profile \| Pipeline \| Use it for \|
50	\|---------\|----------\|------------\|
51	\| `fast` \| Semantic \| Quick exploration \|
52	\| `balanced` \| Semantic + BM25 \| Recommended everyday profile; default \|
53	\| `quality` \| Semantic + BM25 + ColBERT \| Optional reranking experiments \|
54
55	[Code-search guide →](https://xiaocui.me/sgrep/guides/code-search/)
56
57	## Search Agent Conversations
58
59	```bash
60	sgrep conv index
61
62	sgrep conv "embedding server ownership bug"
63	sgrep conv "session compaction" --agent codex --since 7d
64	sgrep conv resume <session_id>
65	```
66
67	Conversation search supports Claude Code, Codex CLI, Cursor, OpenCode, and Pi,
68	with semantic, hybrid, and exact retrieval.
69
70	[Conversation-search guide →](https://xiaocui.me/sgrep/guides/conversation-search/)
71
72	## Built for Coding Agents
73
74	`sgrep` complements structural and exact search:
75
76	\| Tool \| Finds \| Example \|
77	\|------\|-------\|---------\|
78	\| `sgrep` \| Intent \| `sgrep "authentication logic"` \|
79	\| `ast-grep` \| Structure \| `sg -p '$fn($args)'` \|
80	\| `ripgrep` \| Exact text \| `rg "JWT_SECRET"` \|
81
82	Install the shared agent skill:
83
84	```bash
85	npx skills add XiaoConstantine/sgrep --skill sgrep -g
86	```
87
88	Claude Code users can also install automatic project indexing and watch hooks:
89
90	```bash
91	sgrep install-claude-code
92	```
93
94	[Agent-integration guide →](https://xiaocui.me/sgrep/guides/agent-integration/)
95
96	## Architecture
97
98	[![sgrep architecture: code and conversation sources feed a shared local embedding service and separate retrieval pipelines](docs/static/architecture.jpg)](docs/static/architecture.jpg)
99
100	The managed local llama.cpp service is shared, while code and conversation
101	indexes retain separate retrieval controls. The editable diagram source is at
102	[docs/static/architecture.tldr](docs/static/architecture.tldr).
103
104	[Architecture details →](https://xiaocui.me/sgrep/architecture/)
105
106	## Final Pooled Local Benchmark
107
108	In the final controlled local-only comparison, `sgrep balanced` is the
109	strongest overall local quality-latency tradeoff and the strongest normalized
110	implementation-code retriever by point estimate. It is not universally best,
111	and the bootstrap confidence intervals overlap competing tools.
112
113	\| Evaluation track \| Point-estimate result \|
114	\|------------------\|-----------------------\|
115	\| Normalized implementation code \| `sgrep balanced`: MRR 0.792, NDCG@10 0.589, R@10 0.413 at 54.4ms median \|
116	\| Normalized all files \| `osgrep` wins MRR (0.867); `sgrep balanced`/`quality` win NDCG@10 and R@10 (0.607 / 0.340) \|
117	\| Native product output \| `osgrep` wins MRR (0.858) and ChunkHound wins R@10 (0.236); `sgrep balanced`'s small NDCG@10 lead is pool-sensitive \|
118
119	The benchmark used 20 queries, model-judged pooled qrels, sgrep source
120	`19ebec1`, and the pinned `dspy-go` corpus at `87cb50f`. Query-bootstrap 95%
121	confidence intervals overlap, so these are point-estimate verdicts rather than
122	significance claims. `balanced` is recommended over `quality`: it was faster
123	and matched or beat it on the final normalized metrics. Cloud-backed mgrep is
124	kept in a separate, quota-interrupted exploratory track and is not part of the
125	local comparison.
126
127	See the [benchmark methodology and full tables](https://xiaocui.me/sgrep/benchmarks/).
128
129	## Documentation
130
131	\| Guide \| Covers \|
132	\|-------\|--------\|
133	\| [Getting started](https://xiaocui.me/sgrep/guides/getting-started/) \| Installation, setup, first searches \|
134	\| [Code search](https://xiaocui.me/sgrep/guides/code-search/) \| Profiles, output, watch mode, reranking \|
135	\| [Conversation search](https://xiaocui.me/sgrep/guides/conversation-search/) \| Sources, filters, vie

People who liked this also viewed

6 picks

Type

hyperframes-cliUse the HyperFrames CLI development loop: init, add, catalog, capture, lint, check, snapshot, compare, grade-compare, preview, play, present, beats, keyframes, single or batch render, publish, cloud, SkillsJul 2026262k37k
request-refactor-planSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026165k181k
analyze-projectRigor Analyze / Rigor Audit read-only skill for deep learning research repositories. Use when the user wants to read and understand a repository, inspect model structure and training or inference entrSkillsMay 2026161k507
explore-codeRigor Improve implementation leaf skill for auditable candidate implementation in deep learning research repositories. Use when the researcher explicitly authorizes exploratory work on an isolated braSkillsMay 2026161k507
ubiquitous-languageSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026160k181k
scaffold-exercisesSkills for Real Engineers. Straight from my .agents directory.SkillsJul 2026149k181k

sgrep

15stars2forks

View on GitHub

How to install sgrep?

xiaoconstantine/sgrep

$npx -y skills add XiaoConstantine/sgrep

Installs into the current project.

Summary

semantic grep

Files · 1

View on GitHub

README.md

1	# sgrep
2
3	Local semantic and hybrid search for codebases and coding-agent history.
4
5	Find implementation by intent, then recover the decisions and fixes that led
6	to it across Claude Code, Codex, Cursor, OpenCode, and Pi sessions.
7
8	[Documentation](https://xiaocui.me/sgrep/) ·
9	[Getting started](https://xiaocui.me/sgrep/guides/getting-started/) ·
10	[CLI reference](https://xiaocui.me/sgrep/reference/cli/) ·
11	[Agent skill](SKILL.md)
12
13	## Why sgrep?
14
15	- Search code by meaning instead of guessing identifiers.
16	- Search prior agent sessions without reopening transcripts one by one.
17	- Keep source, conversations, models, and indexes on your machine.
18	- Give coding agents compact file-and-line results instead of large context dumps.
19
20	```bash
21	sgrep "where do we validate authentication tokens"
22	sgrep conv "why did we change the authentication cache key"
23	```
24
25	## Install
26
27	```bash
28	brew tap XiaoConstantine/tap
29	brew install sgrep
30
31	# Download the local embedding model and verify llama.cpp.
32	sgrep setup
33	```
34
35	See the [installation guide](https://xiaocui.me/sgrep/guides/getting-started/)
36	for curl, Go, source builds, and sqlite-vec.
37
38	## Search a Codebase
39
40	```bash
41	cd your-repository
42	sgrep index .
43
44	sgrep "database connection error handling" # balanced, the default
45	sgrep --profile fast "request routing" # lowest latency
46	sgrep --profile quality "JWT validation middleware" # optional ColBERT reranking
47	```
48
49	\| Profile \| Pipeline \| Use it for \|
50	\|---------\|----------\|------------\|
51	\| `fast` \| Semantic \| Quick exploration \|
52	\| `balanced` \| Semantic + BM25 \| Recommended everyday profile; default \|
53	\| `quality` \| Semantic + BM25 + ColBERT \| Optional reranking experiments \|
54
55	[Code-search guide →](https://xiaocui.me/sgrep/guides/code-search/)
56
57	## Search Agent Conversations
58
59	```bash
60	sgrep conv index
61
62	sgrep conv "embedding server ownership bug"
63	sgrep conv "session compaction" --agent codex --since 7d
64	sgrep conv resume <session_id>
65	```
66
67	Conversation search supports Claude Code, Codex CLI, Cursor, OpenCode, and Pi,
68	with semantic, hybrid, and exact retrieval.
69
70	[Conversation-search guide →](https://xiaocui.me/sgrep/guides/conversation-search/)
71
72	## Built for Coding Agents
73
74	`sgrep` complements structural and exact search:
75
76	\| Tool \| Finds \| Example \|
77	\|------\|-------\|---------\|
78	\| `sgrep` \| Intent \| `sgrep "authentication logic"` \|
79	\| `ast-grep` \| Structure \| `sg -p '$fn($args)'` \|
80	\| `ripgrep` \| Exact text \| `rg "JWT_SECRET"` \|
81
82	Install the shared agent skill:
83
84	```bash
85	npx skills add XiaoConstantine/sgrep --skill sgrep -g
86	```
87
88	Claude Code users can also install automatic project indexing and watch hooks:
89
90	```bash
91	sgrep install-claude-code
92	```
93
94	[Agent-integration guide →](https://xiaocui.me/sgrep/guides/agent-integration/)
95
96	## Architecture
97
98	[![sgrep architecture: code and conversation sources feed a shared local embedding service and separate retrieval pipelines](docs/static/architecture.jpg)](docs/static/architecture.jpg)
99
100	The managed local llama.cpp service is shared, while code and conversation
101	indexes retain separate retrieval controls. The editable diagram source is at
102	[docs/static/architecture.tldr](docs/static/architecture.tldr).
103
104	[Architecture details →](https://xiaocui.me/sgrep/architecture/)
105
106	## Final Pooled Local Benchmark
107
108	In the final controlled local-only comparison, `sgrep balanced` is the
109	strongest overall local quality-latency tradeoff and the strongest normalized
110	implementation-code retriever by point estimate. It is not universally best,
111	and the bootstrap confidence intervals overlap competing tools.
112
113	\| Evaluation track \| Point-estimate result \|
114	\|------------------\|-----------------------\|
115	\| Normalized implementation code \| `sgrep balanced`: MRR 0.792, NDCG@10 0.589, R@10 0.413 at 54.4ms median \|
116	\| Normalized all files \| `osgrep` wins MRR (0.867); `sgrep balanced`/`quality` win NDCG@10 and R@10 (0.607 / 0.340) \|
117	\| Native product output \| `osgrep` wins MRR (0.858) and ChunkHound wins R@10 (0.236); `sgrep balanced`'s small NDCG@10 lead is pool-sensitive \|
118
119	The benchmark used 20 queries, model-judged pooled qrels, sgrep source
120	`19ebec1`, and the pinned `dspy-go` corpus at `87cb50f`. Query-bootstrap 95%
121	confidence intervals overlap, so these are point-estimate verdicts rather than
122	significance claims. `balanced` is recommended over `quality`: it was faster
123	and matched or beat it on the final normalized metrics. Cloud-backed mgrep is
124	kept in a separate, quota-interrupted exploratory track and is not part of the
125	local comparison.
126
127	See the [benchmark methodology and full tables](https://xiaocui.me/sgrep/benchmarks/).
128
129	## Documentation
130
131	\| Guide \| Covers \|
132	\|-------\|--------\|
133	\| [Getting started](https://xiaocui.me/sgrep/guides/getting-started/) \| Installation, setup, first searches \|
134	\| [Code search](https://xiaocui.me/sgrep/guides/code-search/) \| Profiles, output, watch mode, reranking \|
135	\| [Conversation search](https://xiaocui.me/sgrep/guides/conversation-search/) \| Sources, filters, vie

People who liked this also viewed

6 picks

Type