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.
Rust agent-memoryai-agentsbm25claude-codeclicode-searchcursordatabaseelasticsearchfull-text-searchhybrid-searchjsonllocal-firstmcpmcp-servermodel-context-protocolragrustsearch-enginevector-search
feat: add Herdr integration (#2891)
Gokulraj K G4ce1fbb5503b
diff --git a/integrations/herdr/README.md b/integrations/herdr/README.mdnew file mode 100644index 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.tomlnew file mode 100644index 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-workspacenew file mode 100644index 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"+ ;;+esacdiff --git a/integrations/herdr/scripts/on-worktree-created b/integrations/herdr/scripts/on-worktree-creatednew file mode 100644index 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.shnew file mode 100644index 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.htmlindex 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) | mcpServersCursor | .cursor/mcp.json (project) or ~/.cursor/mcp.json | mcpServersCodex | ~/.codex/config.toml or .codex/config.toml (trusted) | [mcp_servers.xerj]