tl-mcp: persistent HTTP daemon, expanded hooks, MCP tools, cache, pi + codex support

[carlkibler]

Summary

This branch adds a persistent HTTP daemon mode to tl-mcp, expands hook coverage for Claude Code, Codex, and the Pi coding agent, and improves MCP tool surface and performance.

Rebased onto upstream main (v0.39.4) — all 396 tests pass.

---

tl-mcp: Persistent HTTP daemon (bin/tl-mcp.mjs)

Upstream's tl-mcp is 48 lines of stdio-only. This adds a full daemon layer:

• tl-mcp start / stop / status — detached background daemon on port 3742, PID/port files in ~/.tokenlean/
• tl-mcp serve — foreground HTTP server (StreamableHTTPServerTransport)
• tl-mcp install-service — generates and installs a launchd plist (macOS) or systemd user unit (Linux), ready to run
• tl-mcp --session-daemon — auto-spawns an HTTP sidecar for the session lifetime; cleans up on exit
• --idle-timeout N — auto-shutdown after N minutes of inactivity
• Prefers a manually-started daemon over launchd/systemd when both exist
• Single McpServer instance per daemon (was rebuilt per HTTP request)

Agent config after tl-mcp start:

{ "mcpServers": { "tokenlean": { "type": "http", "url": "http://127.0.0.1:3742/mcp" } } }

---

tl-hook: Expanded patterns + Codex fix + Pi support (bin/tl-hook.mjs, src/pi-extension.ts)

Codex format fix — hooks were returning {"decision":"allow"} (wrong format); Codex uses the same hookSpecificOutput schema as Claude Code. Fixed. Codex auto-detected from transcript_path in payload when env vars aren't set.

New Bash patterns caught:

Pattern	Nudge
git log/diff/show (no truncation flags)	tl-diff / tl-history
ls -R/la, tree	tl-structure / Glob
sed -i, awk > file	Edit tool
cat > file, echo >>, tee	Write tool
Read on JSON/YAML > 50KB	tl-snippet

Persuasive messages — large file nudges now include size and estimated savings: "[tl] 47KB — tl-symbols + tl-snippet saves ~40KB".

Per-category TTL dedup: 5 min (high-impact), 15 min (medium), 30 min (informational).

Pi coding agent — tl-hook install pi writes ~/.pi/agent/extensions/tokenlean-hook.ts. Uses pi-specific tool names in messages (grep tool, find tool, read tool). Pi detected via PI_CODING_AGENT env var.

---

MCP tool surface: 8 → 12 tools (src/mcp-tools.mjs)

New tool	Purpose
tl_structure	Project overview with token estimates; replaces ls -R
tl_audit	Mid-session token waste analysis with savings breakdown
tl_deps	File dependency tree without reading implementations
tl_exports	Public API surface of a module or directory

---

Result cache (src/mcp-cache.mjs)

256-entry LRU, 60s TTL, keyed on sha1(tool + sorted args + file mtimes). Active in HTTP daemon mode; opt-out with TL_MCP_CACHE=0.

Measured: repeated tl_symbols call — 205ms → 0ms (cache hit).

---

tl-audit: MCP namespace support (src/audit-analyze.mjs)

tl-audit --savings now counts namespaced MCP tool calls (mcp__tokenlean__tl_symbols) as tokenlean usage. Also fixes Claude session discovery for symlinked project dirs. Includes new tests.

---

Test plan

• npm test — 396 tests, all passing
• tl-mcp start && tl-mcp status — daemon starts on port 3742
• tl-mcp stop — daemon stops cleanly
• tl-mcp install-service | bash — installs launchd/systemd service
• MCP call tl_structure via agent — returns project tree
• MCP call tl_audit — returns session token analysis
• echo '{"tool_name":"Bash","tool_input":{"command":"git log"},...}' | tl-hook run — returns git-verbose nudge
• Same with transcript_path containing /.codex/ — confirms codex detection
• tl-hook install pi — installs extension to ~/.pi/agent/extensions/
• tl-audit --savings on a session with MCP usage — counts mcp__tokenlean__* calls

🤖 Generated with Claude Code