v1.3: /code-history command and history tools

Author: locasioperez

README.md

@@ -32,6 +32,7 @@ Works in Hermes CLI, Telegram, and Hermes Desktop.
 | `/code-search <repo> "query"` | Hybrid semantic + literal search |
 | `/code-context <repo> "query"` | Retrieve a compact context pack |
 | `/code-ask <repo> "question"` | Retrieve + answer with citations (add an optional `"query"` before the question to steer retrieval) |
+| `/code-history <repo> "question"` | Search indexed git commit history (SourceVault v1.8+; index every commit via the dashboard's Full git history setting) |
 
 Telegram uses underscore forms (`/code_ask`, …).
 
@@ -41,8 +42,9 @@ Telegram uses underscore forms (`/code_ask`, …).
 > `/code-repos` to see the exact names.
 
 **LLM-callable tools** (for models that handle structured tool use):
-`code_search`, `code_read_file`, plus `sourcevault_search` / `sourcevault_read`
-aliases for Hermes Tool Search discoverability.
+`code_search`, `code_read_file`, and `code_history`, plus `sourcevault_search` /
+`sourcevault_read` / `sourcevault_history` aliases for Hermes Tool Search
+discoverability.
 
 ## Requires a SourceVault backend
 
@@ -97,6 +99,7 @@ Point the gateway at your SourceVault instance
 ```env
 CODE_SEARCH_URL=http://127.0.0.1:9000/api/search-codebase
 CODE_READ_FILE_URL=http://127.0.0.1:9000/api/read-file
+CODE_HISTORY_URL=http://127.0.0.1:9000/api/history-search
 CODE_SEARCH_HMAC_SECRET=<same value as the SourceVault server>
 ```
 
@@ -147,6 +150,7 @@ Usage notes:
 |---|---|---|
 | `CODE_SEARCH_URL` | `http://127.0.0.1:9000/api/search-codebase` | SourceVault search endpoint |
 | `CODE_READ_FILE_URL` | `http://127.0.0.1:9000/api/read-file` | SourceVault file-read endpoint |
+| `CODE_HISTORY_URL` | `http://127.0.0.1:9000/api/history-search` | SourceVault history-search endpoint (v1.8+) |
 | `CODE_SEARCH_HMAC_SECRET` | — | Request-signing secret (required) |
 | `REPO_ROOT` | `~/.hermes/repos` | Local repo mirrors for `/code-repos`, `/code-sync` |
 | `SOURCEVAULT_CODE_TOOLS_DEBUG` | off | Log argument shapes (no secrets) |

__init__.py

@@ -15,6 +15,7 @@
     _handle_code_context_command,
     _handle_code_help_command,
     _handle_code_read_command,
+    _handle_code_history_command,
     _handle_code_repos_command,
     _handle_code_search_command,
     _handle_code_status_command,
@@ -43,8 +44,10 @@
 )
 from .transport import DEFAULT_READ_FILE_URL, DEFAULT_SEARCH_URL, _debug, _post_signed_json
 from .tools import (
+    _register_code_history_tool,
     _register_code_read_tool,
     _register_code_search_tool,
+    handle_code_history,
     handle_code_read_file,
     handle_code_search,
 )
@@ -62,6 +65,8 @@ def register(ctx):
     _register_code_read_tool(ctx, "code_read_file")
     _register_code_read_tool(ctx, "code_read")
     _register_code_read_tool(ctx, "sourcevault_read")
+    _register_code_history_tool(ctx, "code_history")
+    _register_code_history_tool(ctx, "sourcevault_history")
 
     _register_code_command(
         ctx,
@@ -87,6 +92,12 @@ def register(ctx):
         lambda raw_args: _handle_code_ask_command(raw_args, ctx),
         "Build a SourceVault code context prompt for a repo question.",
     )
+    _register_code_command(
+        ctx,
+        ("code-history", "code_history"),
+        _handle_code_history_command,
+        "Search an indexed repo's git commit history.",
+    )
     _register_code_command(
         ctx,
         ("code-status", "code_status"),

commands.py

@@ -12,14 +12,15 @@
     _extract_json_object,
     _format_ask_command_output,
     _format_context_command_output,
+    _format_history_command_output,
     _format_search_command_output,
     _merge_search_results,
     _parse_successful_search_result,
     _read_file_command_output,
 )
 from .helpers import _clean_repo_name
 from .transport import DEFAULT_READ_FILE_URL, DEFAULT_SEARCH_URL, _debug
-from .tools import handle_code_read_file, handle_code_search
+from .tools import handle_code_history, handle_code_read_file, handle_code_search
 
 
 def _register_code_command(ctx, names, handler, description):
@@ -49,6 +50,8 @@ def _handle_code_help_command(raw_args):
             "/code-ask <repo_name> \"question\" [n_results]",
             "/code_ask <repo_name> \"question\" [n_results]",
             "/code-ask <repo_name> \"retrieval query\" \"question\" [n_results]",
+            "/code-history <repo_name> \"question\" [n_results]",
+            "/code_history <repo_name> \"question\" [n_results]",
             "/code-read <repo_name> <relative_path> [max_bytes]",
             "/code_read <repo_name> <relative_path> [max_bytes]",
             "",
@@ -80,6 +83,26 @@ def _handle_code_read_command(raw_args):
     return _read_file_command_output(result)
 
 
+def _handle_code_history_command(raw_args):
+    try:
+        args = shlex.split(raw_args or "")
+    except ValueError as error:
+        return f'Usage: /code-history <repo_name> "question" [n_results]\nError: {error}'
+
+    if len(args) < 2:
+        return 'Usage: /code-history <repo_name> "question" [n_results]'
+
+    result = handle_code_history(
+        {
+            "repo_name": args[0],
+            "question": args[1],
+            "n_results": args[2] if len(args) > 2 else 5,
+        }
+    )
+
+    return _format_history_command_output(result)
+
+
 def _handle_code_search_command(raw_args):
     try:
         args = shlex.split(raw_args or "")

formatting.py

@@ -69,6 +69,44 @@ def _read_file_command_output(result):
     return result
 
 
+def _format_history_command_output(result):
+    try:
+        parsed = json.loads(result)
+    except (TypeError, json.JSONDecodeError):
+        return result
+
+    if not isinstance(parsed, dict):
+        return result
+
+    if parsed.get("ok") is False or parsed.get("success") is False:
+        return result
+
+    results = parsed.get("results") or []
+    lines = [
+        parsed.get("summary")
+        or f"Found {len(results)} matching commit(s)",
+    ]
+
+    for index, item in enumerate(results, start=1):
+        short = item.get("short") or str(item.get("commit") or "")[:7] or "<unknown>"
+        meta = f"#{index} {short} ({item.get('date') or '?'}) {item.get('author') or ''}".rstrip()
+        if item.get("ai_authored"):
+            meta += " [ai]"
+        lines.append(meta)
+
+        subject = " ".join(str(item.get("subject") or "").split())
+        if subject:
+            lines.append(f"  {subject}")
+
+        preview = " ".join(str(item.get("preview") or "").split())
+        if preview and preview != subject:
+            if len(preview) > 180:
+                preview = f"{preview[:177]}..."
+            lines.append(f"  {preview}")
+
+    return "\n".join(lines)
+
+
 def _format_search_command_output(result):
     try:
         parsed = json.loads(result)

plugin.yaml

@@ -1,3 +1,3 @@
 name: sourcevault-code-tools
-version: "1.2"
+version: "1.3"
 description: Adds signed sourcevault code tools and slash commands.

test_plugin.py

@@ -53,7 +53,7 @@ def test_registers_expected_commands_and_tools(self):
 
         base_commands = [
             "code-help", "code-read", "code-search", "code-context",
-            "code-ask", "code-status", "code-repos", "code-sync",
+            "code-ask", "code-history", "code-status", "code-repos", "code-sync",
         ]
         for name in base_commands:
             self.assertIn(name, ctx.commands, f"missing hyphen command {name}")
@@ -293,3 +293,118 @@ def test_numeric_question_is_not_eaten_as_count(self):
 
 if __name__ == "__main__":
     unittest.main(verbosity=2)
+
+
+class HistoryToolTests(unittest.TestCase):
+    def test_history_tools_registered(self):
+        ctx = StubCtx()
+        plugin.register(ctx)
+        for name in ("code_history", "sourcevault_history"):
+            self.assertIn(name, ctx.tools, f"missing history tool {name}")
+            schema = ctx.tools[name]["schema"]
+            self.assertEqual(schema["parameters"]["required"], ["repo_name", "question"])
+
+    def test_handle_code_history_posts_expected_body(self):
+        captured = {}
+
+        def fake_post(url, body):
+            captured["url"] = url
+            captured["body"] = body
+            return json.dumps({"success": True, "ok": True, "results": []})
+
+        original = plugin.tools._post_signed_json
+        plugin.tools._post_signed_json = fake_post
+        try:
+            plugin.handle_code_history(
+                {"repo_name": "myrepo", "question": "when did auth change", "n_results": "3"}
+            )
+        finally:
+            plugin.tools._post_signed_json = original
+
+        self.assertTrue(captured["url"].endswith("/api/history-search"))
+        self.assertEqual(
+            captured["body"],
+            {"repo_name": "myrepo", "question": "when did auth change", "n_results": 3},
+        )
+
+    def test_handle_code_history_accepts_query_alias(self):
+        captured = {}
+
+        def fake_post(url, body):
+            captured["body"] = body
+            return json.dumps({"success": True, "ok": True, "results": []})
+
+        original = plugin.tools._post_signed_json
+        plugin.tools._post_signed_json = fake_post
+        try:
+            plugin.handle_code_history({"repo_name": "myrepo", "query": "why refactor"})
+        finally:
+            plugin.tools._post_signed_json = original
+
+        self.assertEqual(captured["body"]["question"], "why refactor")
+
+    def test_handle_code_history_translates_missing_route(self):
+        original = plugin.tools._post_signed_json
+        plugin.tools._post_signed_json = lambda url, body: "<html>Cannot POST /api/history-search</html>"
+        try:
+            result = json.loads(plugin.handle_code_history({"repo_name": "r", "question": "q"}))
+        finally:
+            plugin.tools._post_signed_json = original
+
+        self.assertFalse(result["success"])
+        self.assertEqual(result["error"], "history_search_unsupported")
+        self.assertIn("v1.8", result["detail"])
+
+    def test_format_history_command_output(self):
+        payload = json.dumps({
+            "success": True,
+            "ok": True,
+            "summary": "Found 2 matching commits",
+            "results": [
+                {
+                    "short": "abc1234",
+                    "date": "2026-01-02",
+                    "author": "Dev One",
+                    "subject": "fix: tighten header parsing",
+                    "preview": "commit abc1234 (2026-01-02) by Dev One fix: tighten header parsing",
+                    "ai_authored": True,
+                },
+                {
+                    "commit": "def5678901234",
+                    "date": "2026-01-01",
+                    "author": "Dev Two",
+                    "subject": "refactor router",
+                    "preview": "",
+                },
+            ],
+        })
+        text = plugin.formatting._format_history_command_output(payload)
+        self.assertIn("Found 2 matching commits", text)
+        self.assertIn("#1 abc1234 (2026-01-02) Dev One [ai]", text)
+        self.assertIn("  fix: tighten header parsing", text)
+        self.assertIn("#2 def5678 (2026-01-01) Dev Two", text)
+        self.assertNotIn("def5678 (2026-01-01) Dev Two [ai]", text)
+
+    def test_history_command_usage_and_wiring(self):
+        usage = plugin.commands._handle_code_history_command("")
+        self.assertIn("Usage: /code-history", usage)
+
+        captured = {}
+
+        def fake_post(url, body):
+            captured["body"] = body
+            return json.dumps({
+                "success": True, "ok": True, "summary": "Found 1 matching commit",
+                "results": [{"short": "aaa1111", "date": "2026-02-03", "author": "A", "subject": "s"}],
+            })
+
+        original = plugin.tools._post_signed_json
+        plugin.tools._post_signed_json = fake_post
+        try:
+            out = plugin.commands._handle_code_history_command('myrepo "when did tests move" 2')
+        finally:
+            plugin.tools._post_signed_json = original
+
+        self.assertEqual(captured["body"]["n_results"], 2)
+        self.assertIn("Found 1 matching commit", out)
+        self.assertIn("#1 aaa1111", out)

tools.py

@@ -5,7 +5,13 @@
 
 from .formatting import _read_file_content_or_result
 from .helpers import _params, _positive_int, _relative_path, _repo_name
-from .transport import DEFAULT_READ_FILE_URL, DEFAULT_SEARCH_URL, _debug, _post_signed_json
+from .transport import (
+    DEFAULT_HISTORY_URL,
+    DEFAULT_READ_FILE_URL,
+    DEFAULT_SEARCH_URL,
+    _debug,
+    _post_signed_json,
+)
 
 
 def _register_code_search_tool(ctx, name):
@@ -110,6 +116,73 @@ def _register_code_read_tool(ctx, name):
     )
 
 
+def _register_code_history_tool(ctx, name):
+    description = (
+        "SourceVault git-history search. Answers questions about a repo's commit history "
+        "(when something changed, why, by whom) from the locally indexed history. "
+        "Requires SourceVault v1.8 or newer."
+    )
+    ctx.register_tool(
+        name=name,
+        toolset="sourcevault_code_tools",
+        schema={
+            "name": name,
+            "description": description,
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "repo_name": {
+                        "type": "string",
+                        "description": "SourceVault repository name under REPO_ROOT, for example hello-world.",
+                    },
+                    "question": {
+                        "type": "string",
+                        "description": "Natural-language question about the repo's commit history.",
+                    },
+                    "n_results": {
+                        "type": "integer",
+                        "description": "Maximum number of matching commits to return.",
+                        "default": 5,
+                    },
+                },
+                "required": ["repo_name", "question"],
+            },
+        },
+        handler=handle_code_history,
+        description=description,
+    )
+
+
+def handle_code_history(params=None, **kwargs):
+    _debug("code_history raw params=", params, " kwargs=", kwargs)
+    params = _params(params, kwargs)
+    _debug("code_history normalized params=", params)
+
+    body = {
+        "repo_name": _repo_name(params),
+        "question": str(params.get("question") or params.get("query") or "").strip(),
+        "n_results": _positive_int(params.get("n_results") or params.get("max_results"), 5),
+    }
+
+    result = _post_signed_json(
+        os.environ.get("CODE_HISTORY_URL", DEFAULT_HISTORY_URL),
+        body,
+    )
+    # An older SourceVault has no /api/history-search; express answers with a
+    # "Cannot POST" page instead of JSON. Translate that into advice.
+    if isinstance(result, str) and "Cannot POST" in result:
+        return json.dumps(
+            {
+                "success": False,
+                "ok": False,
+                "error": "history_search_unsupported",
+                "detail": "This SourceVault does not serve /api/history-search. Upgrade to v1.8 or newer.",
+            },
+            separators=(",", ":"),
+        )
+    return result
+
+
 def handle_code_search(params=None, **kwargs):
     _debug("code_search raw params=", params, " kwargs=", kwargs)
     params = _params(params, kwargs)