feat: list_modules MCP tool, cache invalidation, table search, demo GIF

- Add list_modules MCP tool: returns all modules sorted by name
- MCP cache invalidation: check stacklit.json mtime on each call
- HTML table view: search/filter input for modules
- Demo GIF recorded with vhs for README

Author: thegdsks

README.md

@@ -27,8 +27,7 @@ $ stacklit init
 Opening visual map...
 ```
 
-<!-- TODO: replace with terminal recording GIF -->
-<!-- ![demo](https://github.com/glincker/stacklit/assets/demo.gif) -->
+![Stacklit demo](demo.gif)
 
 ### Without stacklit
 

assets/template.html

@@ -304,6 +304,28 @@
     padding: 16px;
   }
 
+  #table-search {
+    background: transparent;
+    border: none;
+    border-bottom: 1px solid var(--border);
+    color: var(--text);
+    font-family: var(--font-mono, monospace);
+    font-size: 11px;
+    outline: none;
+    padding: 4px 2px;
+    width: 100%;
+    margin-bottom: 12px;
+    display: block;
+  }
+
+  #table-search::placeholder {
+    color: var(--text-muted);
+  }
+
+  #table-search:focus {
+    border-bottom-color: var(--accent);
+  }
+
   #view-table::-webkit-scrollbar { width: 4px; }
   #view-table::-webkit-scrollbar-track { background: transparent; }
   #view-table::-webkit-scrollbar-thumb { background: var(--border); border-radius: 2px; }
@@ -761,6 +783,7 @@ <h1>stacklit <span id="proj-name">—</span></h1>
 
     <!-- View 3: Table -->
     <div id="view-table" class="view">
+      <input id="table-search" type="search" placeholder="Search modules..." autocomplete="off" spellcheck="false">
       <table id="mod-table">
         <thead>
           <tr>
@@ -1798,6 +1821,7 @@ <h2>Languages</h2>
   let tableSortCol = 'lines';
   let tableSortDir = -1; // -1 = desc
   let selectedTableRow = null;
+  let tableSearchQuery = '';
 
   function buildTableView() {
     renderTable();
@@ -1814,6 +1838,14 @@ <h2>Languages</h2>
         renderTable();
       });
     });
+
+    const searchInput = document.getElementById('table-search');
+    if (searchInput) {
+      searchInput.addEventListener('input', function () {
+        tableSearchQuery = searchInput.value;
+        renderTable();
+      });
+    }
   }
 
   function renderTable() {
@@ -1825,8 +1857,18 @@ <h2>Languages</h2>
       }
     });
 
+    // Filter nodes by search query
+    const needle = tableSearchQuery.trim().toLowerCase();
+    const filtered = needle
+      ? nodeArr.filter(function (n) {
+          const name = (n.id || '').toLowerCase();
+          const purpose = ((n.mod && n.mod.purpose) || '').toLowerCase();
+          return name.indexOf(needle) !== -1 || purpose.indexOf(needle) !== -1;
+        })
+      : nodeArr;
+
     // Sort nodes
-    const sorted = nodeArr.slice().sort(function (a, b) {
+    const sorted = filtered.slice().sort(function (a, b) {
       let av, bv;
       const col = tableSortCol;
       if (col === 'id')       { av = a.id; bv = b.id; }

demo.gif

@@ -0,0 +1,38 @@
+Output demo.gif
+
+Set Shell "bash"
+Set FontSize 14
+Set Width 900
+Set Height 500
+Set Theme { "name": "stacklit", "black": "#0d1117", "red": "#f85149", "green": "#56d364", "yellow": "#e3b341", "blue": "#58a6ff", "magenta": "#bc8cff", "cyan": "#39d2c0", "white": "#c9d1d9", "brightBlack": "#484f58", "brightRed": "#f85149", "brightGreen": "#56d364", "brightYellow": "#e3b341", "brightBlue": "#58a6ff", "brightMagenta": "#bc8cff", "brightCyan": "#39d2c0", "brightWhite": "#e6edf3", "background": "#0d1117", "foreground": "#c9d1d9", "selectionBackground": "#264f78", "cursorColor": "#c9d1d9" }
+Set Padding 20
+
+Type "# Stacklit: your codebase, in 1,500 tokens"
+Enter
+Sleep 1s
+
+Type "stacklit init"
+Enter
+Sleep 3s
+
+Type ""
+Sleep 1s
+
+Type "# stacklit.json is now committed to git"
+Enter
+Sleep 500ms
+
+Type "cat stacklit.json | head -25"
+Enter
+Sleep 3s
+
+Type ""
+Sleep 1s
+
+Type "# Start MCP server for AI agents"
+Enter
+Sleep 500ms
+
+Type "# stacklit serve"
+Enter
+Sleep 2s

demo.tape

@@ -5,20 +5,31 @@ import (
 	"encoding/json"
 	"fmt"
 	"os"
+	"sort"
 	"strings"
+	"time"
 
 	sdkmcp "github.com/modelcontextprotocol/go-sdk/mcp"
 
 	"github.com/glincker/stacklit/internal/schema"
 )
 
 var cachedIndex *schema.Index
+var cachedIndexModTime time.Time
 
 func loadIndex() (*schema.Index, error) {
-	if cachedIndex != nil {
+	const indexFile = "stacklit.json"
+
+	info, err := os.Stat(indexFile)
+	if err != nil {
+		return nil, fmt.Errorf("stacklit.json not found — run 'stacklit init' first")
+	}
+
+	if cachedIndex != nil && !info.ModTime().After(cachedIndexModTime) {
 		return cachedIndex, nil
 	}
-	data, err := os.ReadFile("stacklit.json")
+
+	data, err := os.ReadFile(indexFile)
 	if err != nil {
 		return nil, fmt.Errorf("stacklit.json not found — run 'stacklit init' first")
 	}
@@ -27,6 +38,7 @@ func loadIndex() (*schema.Index, error) {
 		return nil, fmt.Errorf("failed to parse stacklit.json: %w", err)
 	}
 	cachedIndex = &idx
+	cachedIndexModTime = info.ModTime()
 	return cachedIndex, nil
 }
 
@@ -154,6 +166,41 @@ func StartServer() error {
 		})
 	})
 
+	// list_modules — all modules with summary info, sorted by name
+	sdkmcp.AddTool(s, &sdkmcp.Tool{
+		Name:        "list_modules",
+		Description: "List all modules with their purpose, file/line counts, and activity — sorted by name",
+	}, func(ctx context.Context, req *sdkmcp.CallToolRequest, _ emptyArgs) (*sdkmcp.CallToolResult, any, error) {
+		idx, err := loadIndex()
+		if err != nil {
+			return errResult(err)
+		}
+		type moduleSummary struct {
+			Name     string `json:"name"`
+			Purpose  string `json:"purpose"`
+			Files    int    `json:"files"`
+			Lines    int    `json:"lines"`
+			Activity string `json:"activity,omitempty"`
+		}
+		names := make([]string, 0, len(idx.Modules))
+		for name := range idx.Modules {
+			names = append(names, name)
+		}
+		sort.Strings(names)
+		summaries := make([]moduleSummary, 0, len(names))
+		for _, name := range names {
+			mod := idx.Modules[name]
+			summaries = append(summaries, moduleSummary{
+				Name:     name,
+				Purpose:  mod.Purpose,
+				Files:    mod.Files,
+				Lines:    mod.Lines,
+				Activity: mod.Activity,
+			})
+		}
+		return textResult(summaries)
+	})
+
 	// get_hot_files — git churn list
 	sdkmcp.AddTool(s, &sdkmcp.Tool{
 		Name:        "get_hot_files",

internal/mcp/server.go

@@ -1,9 +1,9 @@
 {
   "$schema": "https://stacklit.dev/schema/v1.json",
   "version": "1",
-  "generated_at": "2026-04-09T22:21:13Z",
+  "generated_at": "2026-04-09T23:56:36Z",
   "stacklit_version": "dev",
-  "merkle_hash": "dbf1968b555b90f2eb497376531e8b6e6da14588b79e47ff5a836f9e4432287d",
+  "merkle_hash": "fdac4b84e691421e649f3523cb688eb24554439ade7ccea2f27a3d3cb3466ae9",
   "project": {
     "name": "stacklit",
     "root": ".",
@@ -14,15 +14,15 @@
     "languages": {
       "go": {
         "files": 48,
-        "lines": 5650
+        "lines": 5697
       },
       "java": {
         "files": 1,
         "lines": 16
       },
       "javascript": {
         "files": 3,
-        "lines": 137
+        "lines": 133
       },
       "python": {
         "files": 1,
@@ -47,7 +47,7 @@
       "cmd/stacklit/main.go"
     ],
     "total_files": 59,
-    "total_lines": 5866
+    "total_lines": 5909
   },
   "modules": {
     "assets": {
@@ -259,7 +259,7 @@
       "purpose": "MCP server for AI agents",
       "language": "go",
       "files": 1,
-      "lines": 187,
+      "lines": 234,
       "file_list": [
         "server.go"
       ],
@@ -386,15 +386,15 @@
       ],
       "type_defs": {
         "Architecture": "Pattern string, Summary string",
-        "Dependencies": "Edges [][]string, Entrypoints []string, MostDepended []string, Isolated []string",
         "GitInfo": "HotFiles []HotFile, Recent []string, Stable []string",
         "Hints": "AddFeature string, TestCmd string, EnvVars []string, DoNotTouch []string",
-        "HotFile": "Path string, Commits90d int",
         "Index": "Schema string, Version string, GeneratedAt string, StacklitVersion string, MerkleHash string, Project Project, Tech Tech, Structure Structure, Modules map[string]ModuleInfo, Dependencies Dependenci...",
+        "LangStats": "Files int, Lines int",
         "MultiIndex": "Schema string, Version string, Type string, GeneratedAt string, TotalFiles int, TotalLines int, TotalModules int, Repos []RepoSummary",
         "Project": "Name string, Root string, Type string, Workspaces []string",
         "RepoSummary": "Name string, Path string, PrimaryLanguage string, TotalFiles int, TotalLines int, Modules map[string]ModuleInfo, Frameworks []string, Entrypoints []string",
-        "Structure": "Entrypoints []string, TotalFiles int, TotalLines int, KeyDirectories map[string]string"
+        "Structure": "Entrypoints []string, TotalFiles int, TotalLines int, KeyDirectories map[string]string",
+        "Tech": "PrimaryLanguage string, Languages map[string]LangStats, Frameworks []string"
       },
       "depended_by": [
         "internal/cli",
@@ -456,7 +456,7 @@
       "purpose": "Bin",
       "language": "javascript",
       "files": 1,
-      "lines": 23,
+      "lines": 19,
       "file_list": [
         "stacklit.js"
       ],
@@ -578,38 +578,42 @@
     "hot_files": [
       {
         "path": "internal/engine/engine.go",
-        "commits_90d": 11
+        "commits_90d": 12
       },
       {
         "path": "stacklit.json",
-        "commits_90d": 9
+        "commits_90d": 10
       },
       {
         "path": "stacklit.mmd",
-        "commits_90d": 9
+        "commits_90d": 10
       },
       {
         "path": "assets/template.html",
-        "commits_90d": 7
+        "commits_90d": 9
       },
       {
         "path": "internal/graph/graph.go",
         "commits_90d": 7
       },
       {
         "path": "internal/schema/schema.go",
-        "commits_90d": 6
+        "commits_90d": 7
+      },
+      {
+        "path": "go.mod",
+        "commits_90d": 5
       },
       {
         "path": "internal/cli/init.go",
         "commits_90d": 5
       },
       {
-        "path": "go.mod",
+        "path": "go.sum",
         "commits_90d": 4
       },
       {
-        "path": "go.sum",
+        "path": "README.md",
         "commits_90d": 3
       },
       {
@@ -651,35 +655,31 @@
       {
         "path": "internal/walker/walker_test.go",
         "commits_90d": 3
-      },
-      {
-        "path": ".gitignore",
-        "commits_90d": 2
       }
     ],
     "recent": [
-      "stacklit.json",
-      "stacklit.mmd",
-      "internal/graph/graph_test.go",
-      "internal/cli/diff.go",
-      "internal/cli/init.go",
-      "internal/config/config.go",
-      "internal/config/config_test.go",
-      "internal/engine/engine.go",
-      "internal/graph/graph.go",
-      "internal/schema/schema.go"
-    ],
-    "stable": [
+      "npm/README.md",
+      "npm/bin/stacklit.js",
+      "npm/package.json",
+      "README.md",
+      "SKILL.md",
+      "assets/template.html",
       ".github/workflows/ci.yml",
       ".github/workflows/release.yml",
       ".goreleaser.yml",
+      "go.mod"
+    ],
+    "stable": [
       "LICENSE",
-      "README.md",
-      "SKILL.md",
       "action/action.yml",
       "assets/lang-icons.js",
       "internal/cli/serve.go",
-      "internal/config/config.go"
+      "internal/config/config.go",
+      "internal/config/config_test.go",
+      "internal/detect/envvars.go",
+      "internal/detect/frameworks.go",
+      "internal/detect/frameworks_test.go",
+      "internal/git/activity.go"
     ]
   },
   "hints": {