T2Helix
Persistent recall and pre-action compass for Claude Code, running locally on your machine.
Install
Requires Node 20–26. better-sqlite3 is a native module compiled against your Node ABI — see Native module if recall/compass go quiet after a Node upgrade.
# Use Node 22 LTS (recommended)
nvm use 22
# Add the T2Helix marketplace and install
claude plugin marketplace add https://github.com/templetwo/t2helix
claude plugin install t2helix
That's it. Claude Code will handle hooks and MCP server registration automatically.
What it does
Two hooks integrated into Claude Code's agent loop:
- UserPromptSubmit → recall: searches a local SQLite chronicle for past insights related to your prompt, plus the current session goal, and injects the result as additional context. Writes the current
session_id to a state file so the MCP server can use the same signature.
- PreToolUse → compass: matches the proposed tool action against a rule set. WITNESS classifications (rm -rf wildcards,
git push --force, drop table, prod-context deploys, --no-verify) are hard-denied. PAUSE classifications (credential-shaped patterns) are soft-denied with an override token — see "PAUSE override flow" below. As of v0.2, any credential that reaches the chronicle is redacted to a fingerprint on the way in (lib/secrets.js), at the record() / logCompass() write chokepoints.
Plus an in-process MCP server exposing thirteen tools:
| Tool | Purpose |
|---|
recall | Search the chronicle for past insights by query (FTS5 + recency-weighted). Filters: layer (ground_truth/hypothesis/reflection, single or array), min_intensity, include_meta, since/until (epoch ms). Hook-generated entries (session-action, session-synthesis, compass-fire, method) are excluded by default; pass include_meta:true to see them. |
record | Write a new insight inline. |
record_method | (v0.3) Capture a reusable procedure keyed to a task shape (shape, steps, acceptance, tool_classes). Stored as a domain:'method' insight; surfaced only via the targeted method lookup, never the generic recall firehose. |
set_goal | Anchor a session goal. Archives any prior goal as a reflection-layer insight tagged archived-goal. (v0.3) Optionally takes acceptance_criteria; with none, returns a non-blocking decomposition_hint. |
open_thread | Capture an unresolved question to revisit later. |
resolve_thread | Close an open thread by id with a resolution. Stamps resolved_at + resolution; thread drops out of get_state.open_threads. |
get_state | Read current goal + recent open threads + recent insights. |
recall_compass | Query the compass log of past PreToolUse classifications (filter by classification, matched_only, limit). |
confirm_pending | Approve a pending PAUSE confirmation by token. Single-use; the retry consumes the approval. |
list_pending | Review unexpired pending/approved/used confirmation requests. |
list_method_candidates | (v0.4) Review the queue of auto-distilled method candidates the Stop hook produced from successful sessions. Quarantined — they never surface in recall until promoted. Filter by status (pending/promoted/dismissed). |
promote_method | (v0.4) Promote a candidate (by id) to a trusted, surfaceable domain:'method' insight (source:promoted). The only path from quarantine onto the recalled surface. |
dismiss_method_candidate | (v0.4) Reject a candidate (by id) so it leaves the review queue without becoming a method. |
PAUSE override flow
Under defaultMode: bypassPermissions (the typical Claude Code config), permissionDecision: ask is silently overridden by the harness. To preserve a real safety surface for PAUSE-classified actions, T2Helix routes PAUSE through deny with a token-based override:
- Tool call matches a PAUSE rule (e.g., a
-----BEGIN RSA PRIVATE KEY----- pattern in a Bash command).
- Hook creates a
pending_confirmations row keyed by (session_id, sha256(action_summary)), returns deny with the token in the reason text.
- To approve: call
mcp__t2helix__confirm_pending with the token.
- Retry the original action within 10 minutes. Hook finds the matching approval, consumes it, lets the call through, and re-logs in
compass_log as OPEN with reason: "approved via token X (consumed)".
- The approval is single-use. A new approval is needed for another retry.
WITNESS has no override path — those operations require manual rule edits.
Where state lives
Under Claude Code (the normal install path), data lives under:
~/.claude/plugins/data/t2helix-<marketplace>/ # e.g. t2helix-templetwo-t2helix
(Older Claude Code versions named this dir t2helix-inline; the exact suffix is chosen by Claude Code, not the plugin.)
The full resolution order (highest precedence first):
