Skip to content

armgit / xerj

Public Imported from GitHub
0

AI search engine and MCP server for bots and agents. One Rust binary indexes code, docs, logs, JSONL/CSV and PDFs for BM25 full-text, vector and hybrid search, code search without grep, agent memory and RAG. Elasticsearch-compatible API; Corpus Hub serves hundreds of reference memory corpora.

feat(cli): xerj search — the binary as a query client; drop demo scripts

xerj-orgaf28e3606cda
diff --git a/engine/crates/xerj-autoindex/src/lib.rs b/engine/crates/xerj-autoindex/src/lib.rs
index d64207e09..9635ad658 100644
--- a/engine/crates/xerj-autoindex/src/lib.rs
+++ b/engine/crates/xerj-autoindex/src/lib.rs
@@ -12,6 +12,7 @@ pub mod dataset;
pub mod detect;
pub mod esclient;
pub mod estimate;
+pub mod search;
pub mod extract;
pub mod feedback;
pub mod gate;
diff --git a/engine/crates/xerj-autoindex/src/search.rs b/engine/crates/xerj-autoindex/src/search.rs
new file mode 100644
index 000000000..bf188119f
--- /dev/null
+++ b/engine/crates/xerj-autoindex/src/search.rs
@@ -0,0 +1,164 @@
+//! `xerj search "<query>"` — the binary as a query client.
+//!
+//! Reference coding is "index a repo, then retrieve the definition before you
+//! write". Indexing is already one command (`xerj autoindex`); this makes the
+//! retrieval side one command too, so the whole loop is the binary plus a
+//! running node — no wrapper scripts. It detects a node the same way the
+//! flagship path does (health-ping the ES-compat endpoint) and runs a
+//! `multi_match` biased toward symbol definitions, printing a passage to read
+//! rather than a JSON blob to parse.
+
+use crate::esclient::Es;
+use serde_json::{json, Value};
+
+const USAGE: &str = "\
+xerj search — retrieve code from a running XERJ node (reference coding, no scripts)
+
+USAGE:
+ xerj search [OPTIONS] \"<what you need, in plain words>\"
+
+OPTIONS:
+ --url <U> node endpoint (default $XERJ_URL or http://localhost:9200)
+ --prefix <P> index prefix to search (default \"ax\" — what `xerj autoindex` writes)
+ --api-key <K> Authorization (or $XERJ_API_KEY; --insecure nodes need none)
+ -k <N> number of passages to return (default 5)
+ --full <CHARS> max characters of each passage to print (default 600)
+ --json print the raw response instead of formatted passages
+
+EXAMPLE:
+ xerj --insecure -d ./.xerj-data & # a node, running
+ xerj autoindex ref/sled # index once
+ xerj search \"fsync the WAL segment on rotation\" # one line in, a passage out
+";
+
+/// Entry point for the `search` subcommand. Returns a process exit code.
+pub fn run_search_cli() -> i32 {
+ let mut url =
+ std::env::var("XERJ_URL").ok().filter(|s| !s.is_empty()).unwrap_or_default();
+ let mut api_key = std::env::var("XERJ_API_KEY").ok().filter(|s| !s.is_empty());
+ let mut prefix = "ax".to_string();
+ let mut k: usize = 5;
+ let mut full: usize = 600;
+ let mut as_json = false;
+ let mut query: Option<String> = None;
+
+ // Skip argv[0] (binary) + argv[1] ("search").
+ let mut it = std::env::args().skip(2);
+ while let Some(a) = it.next() {
+ match a.as_str() {
+ "-h" | "--help" => {
+ print!("{USAGE}");
+ return 0;
+ }
+ "--url" => url = it.next().unwrap_or_default(),
+ "--prefix" => prefix = it.next().unwrap_or(prefix),
+ "--api-key" => api_key = it.next(),
+ "-k" => k = it.next().and_then(|s| s.parse().ok()).unwrap_or(k),
+ "--full" => full = it.next().and_then(|s| s.parse().ok()).unwrap_or(full),
+ "--json" => as_json = true,
+ other if !other.starts_with('-') && query.is_none() => {
+ query = Some(other.to_string())
+ }
+ other => {
+ eprintln!("xerj search: unexpected argument '{other}'\n\n{USAGE}");
+ return 2;
+ }
+ }
+ }
+
+ let query = match query {
+ Some(q) if !q.trim().is_empty() => q,
+ _ => {
+ eprintln!("xerj search: a query is required.\n\n{USAGE}");
+ return 2;
+ }
+ };
+ if url.is_empty() {
+ url = "http://localhost:9200".to_string();
+ }
+
+ let es = match Es::new(&url, api_key) {
+ Ok(es) => es,
+ Err(e) => {
+ eprintln!("xerj search: could not build client for {url}: {e}");
+ return 2;
+ }
+ };
+
+ // Detect the node. If nothing answers, say exactly how to start one rather
+ // than dumping a transport error — this is the most common first-run miss.
+ if let Err(e) = es.ping() {
+ eprintln!(
+ "xerj search: no XERJ node reachable at {url} ({e}).\n\n\
+ Start one, then index a repo:\n \
+ xerj --insecure -d ./.xerj-data &\n \
+ xerj autoindex <folder>\n\n\
+ (or point at an existing node with --url / $XERJ_URL)"
+ );
+ return 2;
+ }
+
+ // Bias the match toward symbol definitions (defs), then body, then title —
+ // the same ranking the reference-coding wrapper used, now built in.
+ let body = json!({
+ "size": k,
+ "query": { "multi_match": {
+ "query": query,
+ "fields": ["defs^3", "body", "title"],
+ "type": "most_fields"
+ }},
+ "_source": ["ax_path", "start_line", "language", "body", "title"]
+ });
+
+ let pattern = format!("{prefix}-*");
+ let resp = match es.search(&pattern, &body) {
+ Ok(v) => v,
+ Err(e) => {
+ eprintln!(
+ "xerj search: query failed against {url}/{pattern}: {e}\n\
+ (is the prefix right? `xerj autoindex` writes 'ax' by default — \
+ pass --prefix if you indexed under another.)"
+ );
+ return 1;
+ }
+ };
+
+ if as_json {
+ println!("{}", serde_json::to_string_pretty(&resp).unwrap_or_default());
+ return 0;
+ }
+
+ let hits = resp
+ .pointer("/hits/hits")
+ .and_then(Value::as_array)
+ .cloned()
+ .unwrap_or_default();
+ if hits.is_empty() {
+ println!("no match in {pattern} for: {query}");
+ println!("(index a relevant repo first: xerj autoindex <folder>)");
+ return 0;
+ }
+
+ for h in &hits {
+ let src = h.get("_source").cloned().unwrap_or(Value::Null);
+ let path = src.get("ax_path").and_then(Value::as_str).unwrap_or("?");
+ let score = h.get("_score").and_then(Value::as_f64).unwrap_or(0.0);
+ let line = src.get("start_line").and_then(Value::as_u64);
+ let loc = match line {
+ Some(n) => format!("{path}:{n}"),
+ None => path.to_string(),
+ };
+ println!("\n─── {loc} (score {score:.2})");
+ if let Some(text) = src.get("body").and_then(Value::as_str) {
+ let snippet: String = text.chars().take(full).collect();
+ for l in snippet.lines() {
+ println!(" {l}");
+ }
+ if text.chars().count() > full {
+ println!(" … (--full {} to see more)", full * 2);
+ }
+ }
+ }
+ println!("\n{} passage(s) from '{pattern}'. Cite ax_path:line for anything you rely on.", hits.len());
+ 0
+}
diff --git a/engine/crates/xerj-server/src/main.rs b/engine/crates/xerj-server/src/main.rs
index 46b5f20ef..22e5dcf7b 100644
--- a/engine/crates/xerj-server/src/main.rs
+++ b/engine/crates/xerj-server/src/main.rs
@@ -273,6 +273,8 @@ fn help_text(feedback: bool) -> String {
xerj index <opts> direct NDJSON → engine ingest (see xerj index --help)\n\
xerj autoindex <folder> [opts] zero-config folder discovery + indexing (see xerj autoindex --help)\n\
xerj autoindex map print the discovered data map\n\
+ xerj search \"<text>\" retrieve code/passages from a running node — the\n\
+ query client, no wrapper scripts (see xerj search --help)\n\
xerj brain <folder> one command: index a folder into a running, browsable\n\
second brain in your browser (see xerj brain --help)\n\
xerj mcp [opts] Model Context Protocol stdio server: exposes 10 tools\n\
@@ -1921,6 +1923,12 @@ async fn async_main() -> Result<()> {
let cmd = parse_index_args();
return run_cli_index(cmd).await;
}
+ if matches!(argv1.as_deref(), Some("search")) {
+ let code = tokio::task::spawn_blocking(xerj_autoindex::search::run_search_cli)
+ .await
+ .unwrap_or(1);
+ std::process::exit(code);
+ }
if matches!(argv1.as_deref(), Some("autoindex")) {
// Zero-config folder discovery + indexing over the ES-compat API.
// Fully synchronous internally — run it off the async runtime.
diff --git a/landing/index.html b/landing/index.html
index c87e3c3b6..09a7b0da2 100644
--- a/landing/index.html
+++ b/landing/index.html
@@ -160,26 +160,23 @@
prompt above.
</p>
-<pre class="code">$ xerj --insecure --data-dir ./.xerj-data &amp; <span class="comment"># a node, running</span>
-$ tools/xerj-code/scripts/xc-corpus.sh sled https://github.com/spacejam/sled <span class="comment"># clone + pin the commit</span>
-$ tools/xerj-code/scripts/xc-index.sh sled <span class="comment"># autoindex — tree-sitter AST fields, once</span>
-$ tools/xerj-code/scripts/xc.py sled <span class="accent">"fsync the WAL segment on rotation"</span>
-→ the exact function, its file:line and contract — one plain-English line in, a passage to read out
-
-<span class="comment"># prefer zero extra tooling? the same query on the raw ES wire:</span>
-$ curl -sXPOST localhost:9200/ax-*/_search -H content-type:application/json \
- -d '{"query":{"multi_match":{"query":"fsync the WAL segment on rotation","fields":["defs^3","body"]}}}'</pre>
+<pre class="code">$ xerj --insecure --data-dir ./.xerj-data &amp; <span class="comment"># a node, running</span>
+$ git clone --depth 1 https://github.com/spacejam/sled ref/sled
+$ xerj autoindex ref/sled <span class="comment"># index once — tree-sitter AST fields</span>
+$ xerj search <span class="accent">"fsync the WAL segment on rotation"</span>
+→ the exact function, its file:line and contract — one plain-English line in, a passage to read out</pre>
<p class="wide" style="margin-top:var(--sp-3);">
- Optional convenience layer: the same four steps are wrapped by
- <code class="inline">xc-corpus.sh</code> / <code class="inline">xc-index.sh</code> /
- <code class="inline">xc.py</code>, which ship in the repo under
- <a class="mono" href="https://github.com/xerj-org/xerj/tree/main/tools/xerj-code" rel="external" style="color:var(--z-mute);">tools/xerj-code/</a>.
- They add one thing the plain commands don't have — a corpus definition, a
- few hundred bytes of URLs, pinned commit SHAs and licences, no source, so
- nothing to redistribute. Share that file, and
- <code class="inline">xc-corpus.sh --from</code> rebuilds the same commits on
- the other machine.
+ One binary, no wrapper scripts: <code class="inline">xerj search</code> is a
+ client — it detects the running node and queries it, ranking symbol
+ definitions first (<code class="inline">defs^3</code>) so you get the
+ function, not a grep list. For a whole team, the repeatable-corpus helpers
+ (<code class="inline">xc-corpus.sh</code> / <code class="inline">xc.py</code>)
+ still ship under
+ <a class="mono" href="https://github.com/xerj-org/xerj/tree/main/tools/xerj-code" rel="external" style="color:var(--z-mute);">tools/xerj-code/</a>:
+ they add a corpus definition — a few hundred bytes of pinned commit SHAs and
+ licences, no source — so <code class="inline">xc-corpus.sh --from</code>
+ rebuilds the exact same commits on another machine.
</p>
<p class="viz-caption"><a class="mono" href="/case-studies/reference-coding" style="color:var(--z-mute);">THE FULL CASE STUDY — EVERY NUMBER, EVERY TASK, THE EXACT PROMPT →</a><span class="dash" style="color:var(--z-mute);">·</span><a class="mono" href="https://github.com/xerj-org/xerj/blob/main/user-feedback/11-reference-coding-field-reports/2026-08-11-token-savings-reports.md" style="color:var(--z-mute);">WHERE THE USERS-REPORT ~5× FIGURE COMES FROM →</a></p>