claudient 0.1.0

package/guides/hooks-cookbook.md

@@ -0,0 +1,423 @@
+# Hooks Cookbook
+
+Real, ready-to-use hook patterns for automating quality, safety, and observability in Claude Code.
+
+---
+
+## Hook Fundamentals
+
+Hooks are shell scripts or commands that Claude Code executes automatically in response to events. They run outside Claude's context — they are real shell processes, not Claude instructions.
+
+**Hook events:**
+| Event | When it fires |
+|---|---|
+| `SessionStart` | When a Claude Code session begins |
+| `PreToolUse` | Before any tool call executes |
+| `PostToolUse` | After any tool call completes |
+| `PreCompact` | Before context compaction fires |
+| `PostCompact` | After context compaction completes |
+| `Stop` | When Claude finishes responding |
+| `Notification` | When Claude sends a desktop notification |
+
+**Hook configuration location:** `.claude/settings.json` (project) or `~/.claude/settings.json` (user-level)
+
+**Basic hook structure:**
+```json
+{
+  "hooks": {
+    "EventName": [
+      {
+        "matcher": "ToolName",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/your-script.sh",
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Matcher:** Filters which tool calls trigger the hook. Empty string `""` matches all. `"Bash"` matches only Bash tool calls. `"Write|Edit"` matches Write or Edit.
+
+---
+
+## Recipe 1 — Prettier Auto-Format on File Write
+
+Automatically formats files after Claude writes or edits them. No more "please run prettier" prompts.
+
+**settings.json:**
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "npx prettier --write ${tool_input.file_path}",
+            "async": true
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Notes:**
+- `async: true` runs formatting in the background — Claude doesn't wait for it
+- Only runs on Write and Edit tool calls
+- `${tool_input.file_path}` is the path of the file that was written
+
+---
+
+## Recipe 2 — Block Dangerous Shell Commands
+
+Prevent Claude from running destructive commands even if it decides to try.
+
+**.claude/hooks/block-dangerous.sh:**
+```bash
+#!/usr/bin/env bash
+# Reads the tool input from stdin as JSON
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('command',''))")
+
+# Block patterns
+BLOCKED_PATTERNS=("rm -rf" "sudo " "| bash" "| sh" "curl.*| " "wget.*| " "git push --force" "git reset --hard" "DROP TABLE" "truncate ")
+
+for pattern in "${BLOCKED_PATTERNS[@]}"; do
+  if echo "$COMMAND" | grep -qi "$pattern"; then
+    echo "BLOCKED: command matches dangerous pattern '$pattern'" >&2
+    exit 2  # Exit code 2 = block the tool call
+  fi
+done
+
+exit 0  # Allow
+```
+
+**settings.json:**
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-dangerous.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**Exit codes:** `0` = allow, `1` = warn (Claude sees the output but continues), `2` = block (tool call is cancelled).
+
+---
+
+## Recipe 3 — Audit Log Every Tool Call
+
+Log every tool call with timestamp, tool name, and input summary. Essential for debugging and security auditing.
+
+**.claude/hooks/audit-log.sh:**
+```bash
+#!/usr/bin/env bash
+INPUT=$(cat)
+TOOL_NAME=$(echo "$INPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); print(d.get('tool_name','unknown'))" 2>/dev/null)
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+LOG_FILE="${CLAUDE_PROJECT_DIR}/.claude/logs/audit.log"
+
+mkdir -p "$(dirname "$LOG_FILE")"
+echo "${TIMESTAMP} | ${TOOL_NAME} | $(echo "$INPUT" | python3 -c "import sys,json; d=json.load(sys.stdin); inp=d.get('tool_input',{}); print(str(inp)[:200])" 2>/dev/null)" >> "$LOG_FILE"
+```
+
+**settings.json:**
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/audit-log.sh",
+            "async": true
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Add `.claude/logs/` to `.gitignore`.
+
+---
+
+## Recipe 4 — Pre-Compact Session Saver
+
+Before compaction fires, save the current session state so context survives.
+
+**.claude/hooks/pre-compact-save.sh:**
+```bash
+#!/usr/bin/env bash
+MEMORY_FILE="${CLAUDE_PROJECT_DIR}/.claude/memory/session-state.md"
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+mkdir -p "$(dirname "$MEMORY_FILE")"
+
+cat >> "$MEMORY_FILE" << EOF
+
+---
+## Session snapshot: ${TIMESTAMP}
+[Claude will append a summary here during PreCompact]
+EOF
+```
+
+**settings.json:**
+```json
+{
+  "hooks": {
+    "PreCompact": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/pre-compact-save.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Pair this with a CLAUDE.md instruction: "When PreCompact fires, summarize: current task, files changed, open decisions, next steps — append to `.claude/memory/session-state.md`."
+
+---
+
+## Recipe 5 — Cost Tracker
+
+Estimate token costs per session and log them.
+
+**.claude/hooks/cost-tracker.sh:**
+```bash
+#!/usr/bin/env bash
+INPUT=$(cat)
+COST_FILE="${CLAUDE_PROJECT_DIR}/.claude/logs/costs.log"
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+mkdir -p "$(dirname "$COST_FILE")"
+
+# Extract usage data if available
+USAGE=$(echo "$INPUT" | python3 -c "
+import sys, json
+d = json.load(sys.stdin)
+usage = d.get('usage', {})
+inp = usage.get('input_tokens', 0)
+out = usage.get('output_tokens', 0)
+print(f'input={inp} output={out}')
+" 2>/dev/null || echo "usage=unavailable")
+
+echo "${TIMESTAMP} | ${USAGE}" >> "$COST_FILE"
+```
+
+**settings.json:**
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/cost-tracker.sh",
+            "async": true
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Recipe 6 — TypeScript Type Check on Edit
+
+Run `tsc --noEmit` after Claude edits TypeScript files. Catch type errors before they compound.
+
+**settings.json:**
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash -c 'echo \"${tool_input.file_path}\" | grep -q \"\\.tsx\\?$\" && npx tsc --noEmit 2>&1 | head -20 || true'",
+            "async": false,
+            "timeout": 30
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Set `async: false` so Claude sees the type errors and can fix them immediately.
+
+---
+
+## Recipe 7 — Git Push Reminder
+
+Remind Claude to confirm before any git push operation.
+
+**.claude/hooks/git-push-confirm.sh:**
+```bash
+#!/usr/bin/env bash
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | python3 -c "import sys,json; print(json.load(sys.stdin).get('command',''))" 2>/dev/null)
+
+if echo "$COMMAND" | grep -q "git push"; then
+  echo "⚠️  About to push to remote. Confirm this is intentional." >&2
+  exit 1  # Warn — Claude sees this and should ask user before proceeding
+fi
+
+exit 0
+```
+
+**settings.json:**
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/git-push-confirm.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Recipe 8 — Session Start Context Loader
+
+At session start, automatically remind Claude to read key context files.
+
+**.claude/hooks/session-start.sh:**
+```bash
+#!/usr/bin/env bash
+# Output text that gets prepended to Claude's context at session start
+MEMORY_FILE="${CLAUDE_PROJECT_DIR}/.claude/memory/session-state.md"
+
+if [ -f "$MEMORY_FILE" ]; then
+  echo "Previous session state found at .claude/memory/session-state.md — read it before starting work."
+fi
+
+if [ -f "${CLAUDE_PROJECT_DIR}/CONTEXT.md" ]; then
+  echo "Domain glossary available at CONTEXT.md — read it for project terminology."
+fi
+```
+
+**settings.json:**
+```json
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/session-start.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Combining Hooks
+
+Hooks compose — you can have multiple hooks on the same event, each with different matchers.
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          { "type": "command", "command": "npx prettier --write ${tool_input.file_path}", "async": true }
+        ]
+      },
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          { "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/tsc-check.sh", "async": false }
+        ]
+      },
+      {
+        "matcher": "",
+        "hooks": [
+          { "type": "command", "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/audit-log.sh", "async": true }
+        ]
+      }
+    ]
+  }
+}
+```
+
+This runs: prettier (async) + TypeScript check (sync, Claude waits) + audit log (async) on every file write.
+
+---
+
+## Troubleshooting Hooks
+
+**Hook not firing:**
+- Check the event name is exact: `PreToolUse`, `PostToolUse`, `SessionStart`, `PreCompact`
+- Check the script is executable: `chmod +x .claude/hooks/your-script.sh`
+- Check the path uses `${CLAUDE_PROJECT_DIR}` correctly
+
+**Hook blocking everything:**
+- If your hook exits with `2` on every call, all tool calls are blocked
+- Add logging to the hook to see what input it's receiving
+- Test the hook manually: `echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | bash .claude/hooks/your-script.sh`
+
+**Hook running but output not visible:**
+- Stdout from async hooks is discarded. Use stderr (`>&2`) for messages you want to see.
+- For sync hooks, stdout is shown to Claude; stderr is shown to the user.
+
+---
+
+## Work With Us
+
+Claudient is backed by [Uitbreiden](https://uitbreiden.com/) — we build AI products with developer communities and deliver B2B AI solutions. If you need custom hook systems, automated quality gates, or production-grade Claude Code automation for your team — we build this for clients.
+
+**[uitbreiden.com](https://uitbreiden.com/)**

package/guides/memory-management.md

@@ -0,0 +1,192 @@
+# Memory Management Guide
+
+How to persist context across sessions, survive compaction, and keep Claude's working memory sharp.
+
+---
+
+## The Memory Problem
+
+Claude Code has no persistent memory between sessions by default. Every new session starts fresh. Within a session, context grows until compaction fires — at which point the conversation history is compressed and some detail is lost.
+
+The result without a memory strategy: Claude re-asks questions you've already answered, forgets project conventions you've explained, and loses track of decisions made earlier in long sessions.
+
+Memory management is the practice of explicitly controlling what Claude knows, when it knows it, and how that knowledge survives across session boundaries.
+
+---
+
+## The Four Memory Layers
+
+| Layer | Where | Persists across sessions | Persists across compaction |
+|---|---|---|---|
+| **CLAUDE.md** | Project root | Yes | Yes |
+| **Session files** | `.claude/memory/` or `.tmp/` | Yes (if you save) | Yes (if saved before compact) |
+| **Context window** | In-session only | No | No (compressed) |
+| **Subagent context** | Per-subagent | No | No |
+
+---
+
+## 1. CLAUDE.md as Permanent Memory
+
+`CLAUDE.md` is read at the start of every session. It is the most reliable memory layer — anything here is always available.
+
+**What belongs in CLAUDE.md:**
+- Project architecture overview (one paragraph, not exhaustive)
+- Conventions that Claude would get wrong without guidance (naming, patterns, stack choices)
+- Decisions that have already been made and should not be relitigated
+- Things Claude should never do in this project
+
+**What does NOT belong in CLAUDE.md:**
+- In-progress work or task state (changes too fast, becomes stale)
+- Long explanations of how technologies work (Claude knows this already)
+- Everything — CLAUDE.md over 500 lines starts costing more than it saves
+
+**Example CLAUDE.md memory section:**
+```markdown
+## Decisions (do not re-discuss)
+- Auth: JWT with 15-minute access tokens, 7-day refresh tokens. Not sessions.
+- ORM: raw SQL with pg. No Prisma, no Drizzle — decided March 2026.
+- Error format: `{ error: string, code: string }` — never change shape.
+
+## Conventions
+- All API routes return 204 (not 200) for successful mutations with no body.
+- Database column names are snake_case; JS/TS properties are camelCase.
+- No barrel files (index.ts re-exports). Import directly from the source file.
+```
+
+---
+
+## 2. Session Files for Working Memory
+
+For in-progress context that doesn't belong in CLAUDE.md permanently, use session files.
+
+**Pattern:**
+```
+.claude/
+└── memory/
+    ├── current-task.md       ← what you're working on right now
+    ├── decisions.md          ← decisions made this week (rotate out to CLAUDE.md or delete)
+    └── context-dump.md       ← background Claude needed for a long task
+```
+
+At the start of a session, tell Claude: "Read `.claude/memory/current-task.md` first."
+
+At the end of a session or before compaction: update the file with what was accomplished and what's next.
+
+**Compressing session files:** Use the caveman-compress pattern (see [token-optimization.md](token-optimization.md)) — rewriting session memory files to compressed prose saves ~46% on input tokens read every session.
+
+---
+
+## 3. Pre-Compact Hook for Survival
+
+When compaction fires automatically, any working context in the session that hasn't been saved to a file is gone. A `PreCompact` hook runs before compaction — use it to save critical state.
+
+```json
+{
+  "hooks": {
+    "PreCompact": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/pre-compact-save.sh"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+**What `pre-compact-save.sh` should do:**
+1. Ask Claude to summarize: current task state, open decisions, files modified, next steps
+2. Write that summary to `.claude/memory/session-state.md` with a timestamp
+3. This file survives compaction and can be read at the start of the next session
+
+See `hooks/lifecycle/pre-compact-save.sh` for a ready implementation.
+
+---
+
+## 4. Subagent Memory Isolation
+
+Subagents get a clean context window. This is a feature for performance, but it means a subagent has no memory of the parent session by default.
+
+**Passing memory to subagents:**
+- Include the relevant CLAUDE.md sections in the subagent prompt explicitly
+- Pass the specific file paths and decisions the subagent needs — don't rely on it inheriting session state
+- Keep subagent prompts self-contained: "Here is the context: [...]. Your task: [...]."
+
+**Returning memory from subagents:**
+- Have the subagent write its findings to a file
+- Read that file back in the parent session
+- Don't rely on the subagent's return message alone — files persist, messages don't
+
+---
+
+## 5. CONTEXT.md for Domain Language
+
+Beyond project conventions, complex projects benefit from a `CONTEXT.md` — a glossary of domain-specific terms that shapes how Claude reasons about your codebase.
+
+**Structure:**
+```markdown
+# Project Context
+
+One or two sentence description of what this project does.
+
+## Language
+**Order**: A customer's intent to purchase one or more Products.
+**Cart**: Temporary pre-order state. Distinct from Order — do not conflate.
+**Fulfillment**: The downstream process of physically sending an Order. Outside this repo's scope.
+
+## Relationships
+- An Order contains one or more OrderLines
+- A Cart belongs to exactly one User
+- A Fulfillment belongs to exactly one Order
+
+## Decisions
+- "Basket" was used in early code — resolved: always use "Cart"
+```
+
+`CONTEXT.md` is not CLAUDE.md — it's domain knowledge, not behavioral rules. Put it at the project root and reference it in CLAUDE.md: "Read CONTEXT.md for domain terminology."
+
+---
+
+## 6. Memory Compaction Strategy
+
+**Proactive compaction beats reactive compaction.**
+
+Automatic compaction fires when the context window fills (~95% capacity). By that point:
+- Response quality has already degraded
+- Compaction may cut context you still need
+- You lose control over what gets preserved
+
+**When to compact manually (`/compact`):**
+- Before starting a new major task in the same session
+- After finishing a long debugging session (clear the dead context)
+- When you notice Claude starting to repeat questions or lose track of decisions
+- Before spawning a subagent for a related but distinct task
+
+**What `/compact` preserves:** The summary Claude generates during compaction. Make it good — before compacting, tell Claude what matters: "When you compact, make sure to preserve: the auth decision, the three files we changed, and the bug we found in the parser."
+
+---
+
+## Quick Reference
+
+| Situation | Action |
+|---|---|
+| Decisions that should never change | Put in CLAUDE.md |
+| Current task state | `.claude/memory/current-task.md` |
+| Domain terminology | `CONTEXT.md` at project root |
+| Survive compaction | `PreCompact` hook → session-state.md |
+| Starting a new major task | `/compact` first |
+| Passing context to a subagent | Include it explicitly in the prompt |
+| Session memory files are bloated | Compress with caveman-compress pattern |
+| Claude re-asks things it should know | Add the answer to CLAUDE.md |
+
+---
+
+## Work With Us
+
+Claudient is backed by [Uitbreiden](https://uitbreiden.com/) — we build AI products with developer communities and deliver B2B AI solutions. If you're building long-running AI workflows, autonomous agents, or need help designing memory architectures for production Claude Code deployments — we can help.
+
+**[uitbreiden.com](https://uitbreiden.com/)**