eminiar 0.11.0 → 0.12.0

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "eminiar",
   "displayName": "Eminiar",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Local-first context, memory and knowledge graph for Claude Code: sandboxed execution, FTS5 + vector search, session continuity, code graph.",
   "author": {
     "name": "Ryan Dick"

package/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "eminiar",
   "displayName": "Eminiar",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Local-first context, memory and knowledge graph for coding agents: sandboxed execution, FTS5 + vector search, session continuity, code graph.",
   "author": {
     "name": "Ryan Dick"

package/README.md

@@ -40,7 +40,7 @@ Claude Code is very capable, but three things slow it down on a real project:
 
 ## The solution
 
-eminiar is a Claude Code plugin that also installs into Cursor. It adds an MCP server with 23
+eminiar is a Claude Code plugin that also installs into Cursor. It adds an MCP server with 24
 `em_*` tools and a set of hooks.
 Everything runs locally in one SQLite database per project.
 
@@ -49,9 +49,10 @@ Everything runs locally in one SQLite database per project.
 | **Large output** | The full output goes into context | Output is indexed. Only the sections that match your `intent` come back |
 | **Memory** | Lost at `/compact` or a new session | Markdown memories in your repo, given back to Claude when they are relevant |
 | **Code structure** | `grep` and full-file reads | A knowledge graph of files, symbols, calls, routes and hotspots |
-| **Git history** | Raw `git log` / `git blame` | Classified commits, with each fix traced back to the commit that caused it |
+| **Git history** | Raw `git log` / `git blame` | Classified commits, fix tracing, and a graph from branches to the files, memories and docs they touched |
 | **Library docs** | Web search on each question | A local, searchable index of the docs your project uses |
 | **Getting knowledge** | Claude must remember to ask | Hooks push the relevant knowledge to Claude **automatically** |
+| **Cost** | A guess, one session at a time | Tokens, cache hits and estimated cost for every model call, with insights |
 
 ## What you get
 
@@ -63,6 +64,12 @@ indexed. Claude gets back only the sections that match its `intent`. Snippets ob
 Code `Bash` deny rules, and `em_execute_file` refuses a `path` that one of your `Read` deny rules
 matches ([which rule forms](docs/how-it-works.md#sandbox)).
 
+Hooks route noisy commands for Claude. A Bash line is judged one command at a time: output that
+is already bounded (`| head`, `| wc`, `grep -l`, `cat` of a small file) and commands that change
+files stay native. `git log`, `git blame` and `git show` go to `em_history`, and a `Grep` for a
+symbol the graph knows goes to `em_symbols`. `em_stats` shows each routing decision and the rule
+behind it, so you can see what was sent where.
+
 ### 🔎 Hybrid search — keyword and meaning together
 
 SQLite FTS5 (porter + trigram, BM25, typo correction) is fused with local ONNX embeddings
@@ -77,6 +84,10 @@ and commit them. Decisions have an ADR-style status (`proposed`, `accepted`, `su
 attach matching memories to your prompts, to file reads and edits, to failed commands and to
 subagent briefs. **Claude does not have to remember to look.**
 
+Recall matches a memory when the prompt names it, one of its tags, a file it mentions or a
+symbol from that file. A memory can come back later in a long session. To see why a memory did
+or did not appear, run `eminiar recall --explain "<prompt>"`.
+
 ### 🕸️ Code knowledge graph — a map before an edit
 
 tree-sitter parses TypeScript, JavaScript, Python, Go and PHP into files, symbols, imports, calls,
@@ -85,12 +96,20 @@ Python decorator routes, Go routers, Laravel, Symfony and Slim). eminiar
 adds fan-in, complexity, churn, a hotspot score, module clusters, import cycles and git co-change
 coupling. Ask *"what breaks if I change this?"* with `em_graph_impact`.
 
+Memories and documentation share the same graph. Each memory links to the files and symbols it
+mentions, and each doc source links to the code that uses it. One graph answers *"what do we
+know about this file?"*
+
 ### 📜 Git history, read for Claude
 
 `em_history` classifies every commit (feat, fix, refactor, perf …). It traces each fix back to
 the commit that wrote the broken lines. Files get a risk score with reasons. Before Claude edits
 a bug-prone file, it sees the record.
 
+The history graph connects branches to their commits, commits to the files they changed, and
+those files to the memories and docs about them. Merged and deleted branches keep their commits.
+A fix points at the commit it repairs.
+
 ### 📚 Documentation knowledge base
 
 `em_docs` finds your local docs (READMEs, ADRs, OpenAPI, Postman) and the libraries, services
@@ -106,18 +125,29 @@ session with its compactions, which tools fill the context, insights with recomm
 what eminiar's own tools saved in dollars. Everything stays local; cost is an estimate at list
 price ([details](docs/usage.md)).
 
+### 🐝 Agent swarms (opt-in)
+
+Declare worker roles in `.eminiar/swarm.yaml`, with their prompts, models, tools, skills and
+hooks. eminiar generates a Claude Code agent file per role. `/eminiar:em-swarm <swarm> <goal>`
+makes the main session the coordinator: it plans small tasks, fans workers out in parallel and
+reviews what comes back. Every worker starts with the memories, history risk and hot files for
+its task. Capacity limits, a shared blackboard and a live Swarms tab in the dashboard come with
+it. Nothing changes until you run `eminiar swarm init` ([details](docs/swarms.md)).
+
 ### 📊 Local dashboard
 
 `eminiar ui` opens a local web app with token savings, usage and cost, a source explorer with
-impact analysis, a graph "galaxy", an architecture map, a history explorer, a memory editor and
-a docs manager.
+impact analysis, a graph "galaxy", an architecture map, a history explorer with a history
+graph, a memory editor with a memory graph, and a docs manager.
 
 | | |
 |:---:|:---:|
-| [<img alt="Galaxy: the knowledge graph around a file" src="docs/images/dashboard-galaxy-dark.webp" width="430">](docs/dashboard.md#galaxy) | [<img alt="History: commits classified by kind, with the branch graph" src="docs/images/dashboard-history-dark.webp" width="430">](docs/dashboard.md#history) |
-| **Galaxy:** the knowledge graph | **History:** classified commits and fix tracing |
-| [<img alt="Memory: a decision with its linked files" src="docs/images/dashboard-memory-dark.webp" width="430">](docs/dashboard.md#memory) | [<img alt="Hotspots: fan-in, churn and complexity per file" src="docs/images/dashboard-hotspots-dark.webp" width="430">](docs/dashboard.md#architecture) |
-| **Memory:** decisions linked to code | **Hotspots:** where change is risky |
+| [<img alt="Galaxy: the knowledge graph around a file" src="docs/images/dashboard-galaxy-dark.webp" width="430">](docs/dashboard.md#galaxy) | [<img alt="Usage: cost per day by model, cache hit rate, burn rate and session scores" src="docs/images/dashboard-usage-dark.webp" width="430">](docs/dashboard.md#usage) |
+| **Galaxy:** the knowledge graph | **Usage:** cost, cache and burn rate |
+| [<img alt="History graph: branches, their commits, and the files, memories and docs they touched" src="docs/images/dashboard-history-graph-dark.webp" width="430">](docs/dashboard.md#history) | [<img alt="Memory graph: memories linked to the files, tags and topics they are about" src="docs/images/dashboard-memory-graph-dark.webp" width="430">](docs/dashboard.md#memory) |
+| **History graph:** branches to files and memories | **Memory graph:** what each memory is about |
+| [<img alt="History: commits classified by kind, with the branch graph" src="docs/images/dashboard-history-dark.webp" width="430">](docs/dashboard.md#history) | [<img alt="Hotspots: fan-in, churn and complexity per file" src="docs/images/dashboard-hotspots-dark.webp" width="430">](docs/dashboard.md#architecture) |
+| **History:** classified commits and fix tracing | **Hotspots:** where change is risky |
 
 ## What Claude sees
 
@@ -134,6 +164,17 @@ eminiar graph: src/cli.ts is imported by 6 files; em_graph_impact {node:"file:sr
 them before you change an exported signature.
 ```
 
+When a command would flood the context, routing names the tool to use instead:
+
+```text
+eminiar: `git diff .claude-plugin/plugin.json package.json README.md` usually prints a lot;
+em_execute {language:"shell", code, intent} keeps the output out of context and returns only
+matching sections. Retry with em_execute.
+
+eminiar history: this commit includes files that deserve a second look:
+- package.json is bug-prone (3/25 commits were fixes; 2 earlier changes later needed fixing)
+```
+
 Each note appears once per context window. After a `/compact`, notes come back when they are
 relevant again.
 
@@ -168,7 +209,7 @@ flowchart LR
     CC["Claude Code"]
     subgraph eminiar ["eminiar (local)"]
         H["Hooks<br/>recall · routing · capture"]
-        S["MCP server<br/>23 em_* tools"]
+        S["MCP server<br/>24 em_* tools"]
         SB["Sandbox<br/>shell · JS · TS · Python …"]
         DB[("SQLite per project<br/>FTS5 · vectors · graph")]
         M["Memory files<br/>.eminiar/memories/*.md"]
@@ -202,6 +243,7 @@ Read more in [How it works](docs/how-it-works.md).
 | [Knowledge graph and history](docs/knowledge-graph.md) | Graph, symbols, impact analysis, git history |
 | [Documentation knowledge base](docs/documentation-kb.md) | Discover, index and look up docs |
 | [Usage insights](docs/usage.md) | Tokens, cache, cost, billing blocks, insights and savings per session |
+| [Agent swarms](docs/swarms.md) | Opt-in worker swarms: the swarm file, topologies, the tool and CLI |
 | [Dashboard](docs/dashboard.md) | The `eminiar ui` web app |
 | [Configuration](docs/configuration.md) | Every config key with its default |
 | [CLI](docs/cli.md) | The `eminiar` command |

package/bin/em-hook

@@ -2,14 +2,87 @@
 # Hook entry shim. Node and package-root resolution live in _resolve.sh.
 # A hook must never block Claude: if nothing can run, print an empty JSON object.
 . "$(dirname "$0")/_resolve.sh"
+# Swarm enforcement fails closed: when nothing can run, an Agent/Task call in a project whose
+# .eminiar/swarm.yaml says `enforce: true` is denied. Reads stdin only here; every other call
+# (and every other project) gets the empty answer below.
+swarm_gate() {
+  case " $* " in *" cursor "*) return 0 ;; esac
+  payload=$(cat 2>/dev/null) || return 0
+  case "$payload" in *'"PreToolUse"'*) ;; *) return 0 ;; esac
+  printf '%s' "$payload" | grep -Eq '"tool_name"[[:space:]]*:[[:space:]]*"(Agent|Task)"' || return 0
+  # Payloads with "agent_id" (a call made inside a subagent) are denied too: the Node path
+  # allows nested calls only for allow-listed agents, and this shim cannot read allowed_agents,
+  # so a nested call gets the same deny text as a main-session one.
+  # Root order matches the hooks: CLAUDE_PROJECT_DIR (set by Claude Code per hook command)
+  # before EMINIAR_PROJECT_ROOT (may be inherited from an outer session).
+  root="${CLAUDE_PROJECT_DIR:-${EMINIAR_PROJECT_ROOT:-$PWD}}"
+  # Walk up to the first directory with a project marker (src/project.ts ROOT_MARKERS), else
+  # stay on the start dir, so this checks the root resolveProjectRoot would.
+  d=$root
+  while :; do
+    for m in .git package.json pnpm-workspace.yaml go.mod Cargo.toml pyproject.toml; do
+      [ -e "$d/$m" ] && break 2
+    done
+    p=${d%/*}
+    [ -n "$p" ] || p=/
+    [ "$p" != "$d" ] || { d=$root; break; }
+    d=$p
+  done
+  root=$d
+  main=
+  # A `claude --worktree` session: .git is a file ("gitdir: <main>/.git/worktrees/<n>"), and the
+  # uncommitted swarm file lives in the main checkout. Follow gitdir -> commondir to it. A .git
+  # file without a gitdir line, or a gitdir without commondir (a submodule), is not followed.
+  if [ -f "$root/.git" ]; then
+    cr=$(printf '\r')
+    gd=$(grep -m1 '^gitdir:' "$root/.git" 2>/dev/null)
+    gd=${gd#gitdir:}
+    gd=${gd# }
+    gd=${gd%"$cr"}
+    if [ -n "$gd" ]; then
+      case "$gd" in /*) ;; *) gd="$root/$gd" ;; esac
+      cdir=
+      [ -f "$gd/commondir" ] && read -r cdir < "$gd/commondir"
+      cdir=${cdir%"$cr"}
+      if [ -n "$cdir" ]; then
+        case "$cdir" in /*) ;; *) cdir="$gd/$cdir" ;; esac
+        main=$(cd "$cdir/.." 2>/dev/null && pwd)
+        [ "$main" = "$root" ] && main=
+      fi
+    fi
+  fi
+  # The same rule as enforceIntent (src/swarm/config.ts): top-level `enforce: true|True|TRUE`
+  # (plain or quoted key, BOM, CRLF, space before the colon, trailing comment), and not
+  # `enabled: false|False|FALSE`. Flow-style or indented documents are not recognised here; a
+  # parsing Node reader decides those.
+  bom=$(printf '\357\273\277')
+  tail='[[:space:]]*:[[:space:]]+'
+  end='([[:space:]]+#.*)?[[:space:]]*$'
+  for r in "$root" "$main"; do
+    [ -n "$r" ] || continue
+    for f in "$r/.eminiar/swarm.yaml" "$r/.eminiar/swarm.yml"; do
+      [ -f "$f" ] || continue
+      grep -Eq "^($bom)?(enforce|\"enforce\"|'enforce')${tail}(true|True|TRUE)${end}" "$f" 2>/dev/null || return 0
+      grep -Eq "^($bom)?(enabled|\"enabled\"|'enabled')${tail}(false|False|FALSE)${end}" "$f" 2>/dev/null && return 0
+      echo '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"eminiar swarm enforcement: eminiar'"'"'s hook cannot run (no Node.js or no installed copy; npx eminiar install fixes it), so this subagent is denied. Do the work in this session, or ask the user to fix the install or set enforce: false in .eminiar/swarm.yaml."}}'
+      return 1
+    done
+  done
+  return 0
+}
+# --gate: decide-only mode for a project-level onFailure:"block" entry. Nothing to run means
+# failure (exit 1), so that entry blocks; the swarm_gate fallback below is for the plugin hook.
+case " $* " in *" --gate "*) EM_GATE=1 ;; *) EM_GATE= ;; esac
 if [ ! -x "$NODE" ]; then
   echo "eminiar hook: no node binary found (run: npx eminiar install)" >&2
-  echo '{}'
+  [ -n "$EM_GATE" ] && exit 1
+  swarm_gate "$@" && echo '{}'
   exit 0
 fi
 if [ -z "$RUN" ]; then
   echo "eminiar hook: $DIR has no node_modules and no stable copy is pinned (run: npx eminiar install)" >&2
-  echo '{}'
+  [ -n "$EM_GATE" ] && exit 1
+  swarm_gate "$@" && echo '{}'
   exit 0
 fi
 exec "$NODE" "$RUN/dist/hook.js" "$@"