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: add Herdr integration (#2891)

Gokulraj K G4ce1fbb5503b
diff --git a/integrations/herdr/README.md b/integrations/herdr/README.md
new file mode 100644
index 000000000..e757edb17
--- /dev/null
+++ b/integrations/herdr/README.md
@@ -0,0 +1,72 @@
+# XERJ for Herdr
+
+This plugin connects Herdr worktrees to XERJ. When Herdr creates a worktree, the `worktree.created` hook runs `xerj init` from that checkout. This lets XERJ generate project-local agent configuration such as `.mcp.json`. The **Index this workspace** pane action is separate: it runs `xerj autoindex .` from the focused pane's workspace.
+
+The manifest is currently Linux-scoped because the entrypoints use Bash. The plugin requires Herdr 0.7.0 or newer and an installed `xerj` executable available on `PATH`.
+
+## Install
+
+From a Herdr session, install the plugin from the repository checkout or a published GitHub subdirectory:
+
+```sh
+herdr plugin install xerj-org/xerj/integrations/herdr
+```
+
+For local development, link the directory instead:
+
+```sh
+herdr plugin link ./integrations/herdr
+```
+
+The plugin does not install XERJ. Install XERJ separately and confirm it is available with `command -v xerj`.
+
+## Verify
+
+Create a new Herdr worktree and inspect its checkout. If a supported project agent surface is present, the hook should create or update `.mcp.json` there:
+
+```sh
+herdr worktree create --cwd /absolute/path/to/repository --branch herdr-test
+cat /absolute/path/to/worktree/.mcp.json
+```
+
+The plugin action can be invoked from a focused pane through Herdr's action UI, or directly while testing:
+
+```sh
+herdr plugin action invoke xerj.herdr.index-workspace
+```
+
+The action indexes the pane's workspace with `xerj autoindex .`. Check recent plugin logs if a command fails:
+
+```sh
+herdr plugin log list --plugin xerj.herdr
+```
+
+Restart the coding-agent session after initialization. A successful MCP setup is confirmed when `xerj_search` appears in the agent's tool list and a search call returns a result. Tested end-to-end with Herdr 0.9.5 and Claude Code 2.1.316 against XERJ v1.0.0-rc.100 on Linux (WSL2), confirming worktree initialization, `.mcp.json` generation, pane action workspace indexing, and `xerj_search` tool invocation.
+
+## Remove
+
+Disable the plugin without removing its files:
+
+```sh
+herdr plugin disable xerj.herdr
+```
+
+Unregister it completely:
+
+```sh
+herdr plugin uninstall xerj.herdr
+```
+
+For a locally linked plugin, use `herdr plugin unlink xerj.herdr`. These commands unregister the plugin but leave the repository checkout in place. Files written by `xerj init`, including `.mcp.json`, remain under the worktree and should be removed or edited according to the project's normal configuration policy.
+
+## Without Herdr
+
+Herdr is optional. To configure the current project directly, run:
+
+```sh
+cd /absolute/path/to/project
+xerj init
+xerj autoindex .
+```
+
+`xerj init` is the standalone XERJ setup command: it detects supported agent surfaces and writes the smallest project-local configuration it needs. The plugin only automates that command for newly created Herdr worktrees and adds a manual indexing action.
diff --git a/integrations/herdr/herdr-plugin.toml b/integrations/herdr/herdr-plugin.toml
new file mode 100644
index 000000000..581dd4614
--- /dev/null
+++ b/integrations/herdr/herdr-plugin.toml
@@ -0,0 +1,16 @@
+id = "xerj.herdr"
+name = "XERJ for Herdr"
+version = "0.1.0"
+min_herdr_version = "0.7.0"
+description = "Initialize Herdr worktrees with XERJ and expose a one-command workspace indexing action."
+platforms = ["linux"]
+
+[[events]]
+on = "worktree.created"
+command = ["bash", "scripts/on-worktree-created"]
+
+[[actions]]
+id = "index-workspace"
+title = "Index this workspace"
+contexts = ["pane"]
+command = ["bash", "scripts/index-workspace"]
diff --git a/integrations/herdr/scripts/index-workspace b/integrations/herdr/scripts/index-workspace
new file mode 100644
index 000000000..f18f4dd04
--- /dev/null
+++ b/integrations/herdr/scripts/index-workspace
@@ -0,0 +1,105 @@
+#!/usr/bin/env bash
+set -u
+
+usage() {
+ printf 'usage: %s [WORKSPACE_DIR]\n' "${0##*/}" >&2
+ printf ' With no argument, use Herdr focused_pane_cwd or workspace_cwd context.\n' >&2
+}
+
+fail() {
+ printf 'herdr-xerj: %s\n' "$1" >&2
+ exit "${2:-64}"
+}
+
+if (( $# > 1 )); then
+ usage
+ exit 64
+fi
+
+workspace_path=""
+if (( $# == 1 )); then
+ workspace_path=$1
+elif [[ -n "${HERDR_PLUGIN_CONTEXT_JSON:-}" ]]; then
+ workspace_path=$(
+ CONTEXT_JSON="$HERDR_PLUGIN_CONTEXT_JSON" python3 - <<'PY'
+import json
+import os
+import sys
+
+try:
+ context = json.loads(os.environ["CONTEXT_JSON"])
+except (KeyError, json.JSONDecodeError) as exc:
+ print(f"invalid HERDR_PLUGIN_CONTEXT_JSON: {exc}", file=sys.stderr)
+ raise SystemExit(65)
+
+if not isinstance(context, dict):
+ print("plugin context must be a JSON object", file=sys.stderr)
+ raise SystemExit(65)
+
+path = context.get("focused_pane_cwd") or context.get("workspace_cwd")
+if not isinstance(path, str) or not path:
+ print(
+ "plugin context is missing focused_pane_cwd and workspace_cwd",
+ file=sys.stderr,
+ )
+ raise SystemExit(65)
+print(path)
+PY
+ )
+ context_status=$?
+ if (( context_status != 0 )); then
+ exit "$context_status"
+ fi
+else
+ fail "a workspace argument or Herdr plugin context is required" 65
+fi
+
+if [[ -z "$workspace_path" ]]; then
+ usage
+ exit 64
+fi
+
+if [[ "$workspace_path" != /* ]]; then
+ fail "workspace path must be absolute: $workspace_path" 64
+fi
+
+if [[ ! -d "$workspace_path" ]]; then
+ fail "workspace path is not an existing directory: $workspace_path" 66
+fi
+
+if [[ ! -r "$workspace_path" || ! -x "$workspace_path" ]]; then
+ fail "workspace path is not readable: $workspace_path" 66
+fi
+
+xerj_bin=${XERJ_BIN:-xerj}
+if [[ "$xerj_bin" == */* ]]; then
+ [[ -x "$xerj_bin" ]] || fail "XERJ executable is not executable: $xerj_bin" 67
+else
+ command -v "$xerj_bin" >/dev/null 2>&1 || fail "XERJ executable not found on PATH: $xerj_bin" 67
+fi
+
+printf 'herdr-xerj: running %s autoindex . in %s\n' "$xerj_bin" "$workspace_path" >&2
+(
+ cd -- "$workspace_path" || exit 66
+ "$xerj_bin" autoindex .
+)
+status=$?
+
+case "$status" in
+ 0)
+ printf 'herdr-xerj: workspace indexed successfully: %s\n' "$workspace_path" >&2
+ exit 0
+ ;;
+ 3)
+ printf 'herdr-xerj: workspace indexed with skipped/junk files (XERJ exit 3): %s\n' "$workspace_path" >&2
+ exit 3
+ ;;
+ 1|2|4)
+ printf 'herdr-xerj: XERJ indexing failed or needs a decision (exit %s): %s\n' "$status" "$workspace_path" >&2
+ exit "$status"
+ ;;
+ *)
+ printf 'herdr-xerj: XERJ indexing exited unexpectedly with status %s: %s\n' "$status" "$workspace_path" >&2
+ exit "$status"
+ ;;
+esac
diff --git a/integrations/herdr/scripts/on-worktree-created b/integrations/herdr/scripts/on-worktree-created
new file mode 100644
index 000000000..dc0ab3adc
--- /dev/null
+++ b/integrations/herdr/scripts/on-worktree-created
@@ -0,0 +1,110 @@
+#!/usr/bin/env bash
+set -u
+
+if [[ "${HERDR_PLUGIN_EVENT:-}" != "worktree.created" ]]; then
+ printf 'herdr-xerj: refusing unexpected event %s\n' "${HERDR_PLUGIN_EVENT:-<unset>}" >&2
+ exit 64
+fi
+
+if [[ -z "${HERDR_PLUGIN_EVENT_JSON:-}" ]]; then
+ printf 'herdr-xerj: HERDR_PLUGIN_EVENT_JSON is required\n' >&2
+ exit 65
+fi
+
+workspace_path=$(
+ EVENT_JSON="$HERDR_PLUGIN_EVENT_JSON" python3 - <<'PY'
+import json
+import os
+import pathlib
+import sys
+
+try:
+ payload = json.loads(os.environ["EVENT_JSON"])
+except (KeyError, json.JSONDecodeError) as exc:
+ print(f"invalid HERDR_PLUGIN_EVENT_JSON: {exc}", file=sys.stderr)
+ raise SystemExit(65)
+
+if not isinstance(payload, dict):
+ print("event payload must be a JSON object", file=sys.stderr)
+ raise SystemExit(65)
+if payload.get("event") != "worktree_created":
+ print("event payload is not worktree_created", file=sys.stderr)
+ raise SystemExit(65)
+
+data = payload.get("data")
+if not isinstance(data, dict) or data.get("type") != "worktree_created":
+ print("event payload data is not worktree_created", file=sys.stderr)
+ raise SystemExit(65)
+
+workspace = data.get("workspace")
+worktree = data.get("worktree")
+workspace_worktree = workspace.get("worktree") if isinstance(workspace, dict) else None
+checkout_path = (
+ workspace_worktree.get("checkout_path")
+ if isinstance(workspace_worktree, dict)
+ else None
+)
+worktree_path = worktree.get("path") if isinstance(worktree, dict) else None
+
+if not isinstance(checkout_path, str) or not checkout_path:
+ print("event payload is missing data.workspace.worktree.checkout_path", file=sys.stderr)
+ raise SystemExit(65)
+if not isinstance(worktree_path, str) or not worktree_path:
+ print("event payload is missing data.worktree.path", file=sys.stderr)
+ raise SystemExit(65)
+
+checkout = pathlib.Path(checkout_path)
+worktree_dir = pathlib.Path(worktree_path)
+if not checkout.is_absolute() or not worktree_dir.is_absolute():
+ print("worktree paths must be absolute", file=sys.stderr)
+ raise SystemExit(65)
+
+try:
+ same_path = checkout.resolve(strict=False) == worktree_dir.resolve(strict=False)
+except OSError as exc:
+ print(f"cannot resolve worktree path: {exc}", file=sys.stderr)
+ raise SystemExit(65)
+if not same_path:
+ print(
+ "event payload workspace and worktree paths disagree: "
+ f"{checkout} != {worktree_dir}",
+ file=sys.stderr,
+ )
+ raise SystemExit(65)
+if not checkout.is_dir():
+ print(f"worktree path is not an existing directory: {checkout}", file=sys.stderr)
+ raise SystemExit(66)
+
+print(checkout)
+PY
+)
+parse_status=$?
+if (( parse_status != 0 )); then
+ exit "$parse_status"
+fi
+
+xerj_bin=${XERJ_BIN:-xerj}
+if [[ "$xerj_bin" == */* ]]; then
+ [[ -x "$xerj_bin" ]] || {
+ printf 'herdr-xerj: XERJ executable is not executable: %s\n' "$xerj_bin" >&2
+ exit 67
+ }
+else
+ command -v "$xerj_bin" >/dev/null 2>&1 || {
+ printf 'herdr-xerj: XERJ executable not found on PATH: %s\n' "$xerj_bin" >&2
+ exit 67
+ }
+fi
+
+printf 'herdr-xerj: initializing created worktree %s\n' "$workspace_path" >&2
+(
+ cd -- "$workspace_path" || exit 66
+ "$xerj_bin" init
+)
+status=$?
+if (( status == 0 )); then
+ printf 'herdr-xerj: worktree initialization completed: %s\n' "$workspace_path" >&2
+else
+ printf 'herdr-xerj: xerj init failed with exit %s: %s\n' "$status" "$workspace_path" >&2
+fi
+exit "$status"
diff --git a/integrations/herdr/tests/smoke.sh b/integrations/herdr/tests/smoke.sh
new file mode 100644
index 000000000..477aaf233
--- /dev/null
+++ b/integrations/herdr/tests/smoke.sh
@@ -0,0 +1,123 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+repo_root=$(CDPATH= cd -- "$(dirname -- "$0")/../../.." && pwd)
+plugin_root="$repo_root/integrations/herdr"
+workdir=$(mktemp -d)
+trap 'rm -rf "$workdir"' EXIT
+workspace="$workdir/worktree"
+mkdir -p "$workspace"
+hook="$plugin_root/scripts/on-worktree-created"
+indexer="$plugin_root/scripts/index-workspace"
+
+mock_xerj="$workdir/mock-xerj"
+cat > "$mock_xerj" <<'MOCK'
+#!/usr/bin/env bash
+printf '%s\n' "$PWD" > "$MOCK_CWD"
+printf '%s\n' "$*" > "$MOCK_ARGS"
+case "${1:-}" in
+ init)
+ printf '{"mcpServers":{"xerj":{"command":"xerj","args":["mcp"]}}}\n' > .mcp.json
+ ;;
+ autoindex)
+ ;;
+ *)
+ exit 64
+ ;;
+esac
+MOCK
+chmod +x "$mock_xerj"
+
+payload=$(python3 - "$workspace" <<'PY'
+import json
+import sys
+
+path = sys.argv[1]
+print(json.dumps({
+ "event": "worktree_created",
+ "data": {
+ "type": "worktree_created",
+ "workspace": {
+ "workspace_id": "w-test",
+ "number": 1,
+ "label": "herdr-test",
+ "focused": False,
+ "pane_count": 1,
+ "tab_count": 1,
+ "active_tab_id": "w-test:t1",
+ "agent_status": "idle",
+ "worktree": {
+ "repo_key": "test-repo",
+ "repo_name": "xerj",
+ "repo_root": path,
+ "checkout_path": path,
+ "is_linked_worktree": True,
+ },
+ },
+ "worktree": {
+ "path": path,
+ "branch": "herdr-test",
+ "is_bare": False,
+ "is_detached": False,
+ "is_prunable": False,
+ "is_linked_worktree": True,
+ "open_workspace_id": "w-test",
+ "label": "herdr-test",
+ },
+ },
+}))
+PY
+)
+
+MOCK_CWD="$workdir/init-cwd" MOCK_ARGS="$workdir/init-args" XERJ_BIN="$mock_xerj" \
+ HERDR_PLUGIN_EVENT=worktree.created HERDR_PLUGIN_EVENT_JSON="$payload" \
+ "$hook" >/dev/null
+
+test "$(cat "$workdir/init-cwd")" = "$workspace"
+test "$(cat "$workdir/init-args")" = "init"
+test -s "$workspace/.mcp.json"
+
+expect_hook_rejection() {
+ local event_json=$1
+ local expected_status=$2
+ if HERDR_PLUGIN_EVENT=worktree.created HERDR_PLUGIN_EVENT_JSON="$event_json" \
+ XERJ_BIN="$mock_xerj" "$hook" >/dev/null 2>/dev/null; then
+ printf 'expected hook rejection, but it succeeded\n' >&2
+ return 1
+ else
+ test "$?" -eq "$expected_status"
+ fi
+}
+
+expect_hook_rejection '{not-json' 65
+expect_hook_rejection '{"event":"worktree_created","data":{"type":"worktree_created","workspace":{},"worktree":{}}}' 65
+mismatched_payload=$(python3 - "$workspace" "$workdir/other-worktree" <<'PY'
+import json
+import sys
+
+print(json.dumps({
+ "event": "worktree_created",
+ "data": {
+ "type": "worktree_created",
+ "workspace": {"worktree": {"checkout_path": sys.argv[1]}},
+ "worktree": {"path": sys.argv[2]},
+ },
+}))
+PY
+)
+expect_hook_rejection "$mismatched_payload" 65
+
+MOCK_CWD="$workdir/index-cwd" MOCK_ARGS="$workdir/index-args" XERJ_BIN="$mock_xerj" \
+HERDR_PLUGIN_CONTEXT_JSON="$(python3 - "$workspace" <<'PY'
+import json
+import sys
+print(json.dumps({"workspace_id": "w-test", "focused_pane_cwd": sys.argv[1]}))
+PY
+)" \
+ "$indexer" >/dev/null
+
+test "$(cat "$workdir/index-cwd")" = "$workspace"
+test "$(cat "$workdir/index-args")" = "autoindex ."
+
+printf 'PASS: worktree.created runs xerj init and creates .mcp.json\n'
+printf 'PASS: pane action runs xerj autoindex . in the focused workspace\n'
diff --git a/landing/docs/cli.html b/landing/docs/cli.html
index 2f707df18..dddd787c9 100644
--- a/landing/docs/cli.html
+++ b/landing/docs/cli.html
@@ -484,6 +484,7 @@ OPTIONS:
<p>Twenty-six clients can register <code class="inline">xerj mcp</code> as a local stdio server. The entry is the absolute path to the binary plus <code class="inline">mcp</code>; only the file it lives in and the key wrapping it differ. One row has been run end to end (OpenCode 2.1.2 on Windows against <code class="inline">xerj</code> v1.0.0-rc.97, which answered <code class="inline">initialize</code> and <code class="inline">tools/list</code> with its full tool list); the rest are transcribed from each client's own documentation and are not marked as tested.</p>
<pre class="code">OpenCode | opencode.json (project) or ~/.config/opencode/opencode.json | mcp.servers [tested]
+Herdr (XERJ plugin) | herdr-plugin.toml: worktree.created + pane action | plugin manifest [tested]
Claude Code | .mcp.json (project) or ~/.claude.json (user) | mcpServers
Cursor | .cursor/mcp.json (project) or ~/.cursor/mcp.json | mcpServers
Codex | ~/.codex/config.toml or .codex/config.toml (trusted) | [mcp_servers.xerj]