claudient 0.1.0

package/hooks/lifecycle/cost-tracker.sh

@@ -0,0 +1,59 @@
+#!/usr/bin/env bash
+# cost-tracker.sh — estimates and logs token costs per session
+#
+# Install: add to settings.json hooks.PostToolUse
+# {
+#   "matcher": "",
+#   "hooks": [{
+#     "type": "command",
+#     "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/cost-tracker.sh",
+#     "async": true
+#   }]
+# }
+#
+# Log location: .claude/logs/costs.log
+# Add .claude/logs/ to .gitignore
+
+set -euo pipefail
+
+INPUT=$(cat)
+LOG_FILE="${CLAUDE_PROJECT_DIR:-$(pwd)}/.claude/logs/costs.log"
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+SESSION_ID="${CLAUDE_SESSION_ID:-unknown}"
+
+mkdir -p "$(dirname "$LOG_FILE")"
+
+# Extract token usage if available in the event payload
+USAGE=$(echo "$INPUT" | python3 -c "
+import sys, json
+try:
+    d = json.load(sys.stdin)
+    usage = d.get('usage', {})
+    inp_tokens = usage.get('input_tokens', 0)
+    out_tokens = usage.get('output_tokens', 0)
+    cache_read = usage.get('cache_read_input_tokens', 0)
+    cache_write = usage.get('cache_creation_input_tokens', 0)
+
+    # Approximate costs (Sonnet 4.6 pricing as baseline — update as needed)
+    # Input: \$3/MTok, Output: \$15/MTok, Cache read: \$0.30/MTok, Cache write: \$3.75/MTok
+    cost = (
+        (inp_tokens / 1_000_000) * 3.0 +
+        (out_tokens / 1_000_000) * 15.0 +
+        (cache_read / 1_000_000) * 0.30 +
+        (cache_write / 1_000_000) * 3.75
+    )
+    print(f'input={inp_tokens} output={out_tokens} cache_read={cache_read} est_cost_usd={cost:.6f}')
+except Exception as e:
+    print(f'parse_error={e}')
+" 2>/dev/null || echo "usage=unavailable")
+
+TOOL_NAME=$(echo "$INPUT" | python3 -c "
+import sys, json
+try:
+    d = json.load(sys.stdin)
+    print(d.get('tool_name', 'unknown'))
+except:
+    print('unknown')
+" 2>/dev/null || echo "unknown")
+
+echo "${TIMESTAMP} | session=${SESSION_ID} | tool=${TOOL_NAME} | ${USAGE}" >> "$LOG_FILE"

package/hooks/lifecycle/pre-compact-save.md

@@ -0,0 +1,56 @@
+# Hook: Pre-Compact Save
+
+Saves session state to a temporary file before Claude Code compacts the conversation history, preserving context that would otherwise be lost.
+
+## Event
+`PreCompact` — fires before the context compaction step
+
+## settings.json entry
+
+```json
+{
+  "hooks": {
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/pre-compact-save.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+`PreCompact` has no `matcher` field — it always fires before compaction.
+
+## What it does
+
+Before Claude compacts the conversation, this hook:
+1. Writes the current working directory, open files, and recent bash commands to `.claude/tmp/session-state.md`
+2. The file is included in the compaction summary prompt, helping Claude retain what it was working on
+
+Output format:
+```markdown
+# Session State (pre-compact snapshot)
+**Time:** 2026-05-13T10:45:00Z
+**CWD:** /Users/dev/myproject
+**Recent files touched:** src/api/users.py, tests/test_users.py
+**Last command:** pytest tests/ -x
+```
+
+## Why this matters
+
+Without this hook, compaction can cause Claude to lose track of which files it was editing, what tests were passing, and what the current task was. This hook gives the compaction model a structured anchor.
+
+## Setup
+
+```bash
+cp hooks/lifecycle/pre-compact-save.sh .claude/hooks/
+chmod +x .claude/hooks/pre-compact-save.sh
+mkdir -p .claude/tmp
+echo ".claude/tmp/" >> .gitignore
+```

package/hooks/lifecycle/pre-compact-save.sh

@@ -0,0 +1,37 @@
+#!/usr/bin/env bash
+# pre-compact-save.sh — saves session state before compaction fires
+#
+# Install: add to settings.json hooks.PreCompact
+# {
+#   "matcher": "",
+#   "hooks": [{
+#     "type": "command",
+#     "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/pre-compact-save.sh"
+#   }]
+# }
+#
+# Also add to CLAUDE.md:
+# "When PreCompact fires, summarize: current task state, files modified,
+#  open decisions, next steps. Append to .claude/memory/session-state.md
+#  with a timestamp header."
+
+set -euo pipefail
+
+MEMORY_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}/.claude/memory"
+STATE_FILE="${MEMORY_DIR}/session-state.md"
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+mkdir -p "$MEMORY_DIR"
+
+# Create or append a timestamped section for Claude to fill in
+cat >> "$STATE_FILE" << EOF
+
+---
+## Session snapshot — ${TIMESTAMP}
+
+*[Claude: append your summary here — current task, files modified, open decisions, next steps]*
+
+EOF
+
+# Output to stdout so Claude sees the instruction
+echo "PreCompact triggered at ${TIMESTAMP}. Append your session summary to .claude/memory/session-state.md before compaction."

package/hooks/lifecycle/session-start.md

@@ -0,0 +1,50 @@
+# Hook: Session Start
+
+Runs setup tasks when a Claude Code session begins — prints a welcome banner, checks for uncommitted changes, and reminds Claude of the project context.
+
+## Event
+`Notification` — fires on session start (and other lifecycle notifications)
+
+## settings.json entry
+
+```json
+{
+  "hooks": {
+    "Notification": [
+      {
+        "matcher": "session_start",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/session-start.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## What it does
+
+On session start:
+1. Prints project name and current branch to stdout (visible in Claude's context)
+2. Runs `git status --short` — if there are uncommitted changes, outputs a summary
+3. Checks for a `.claude/session-notes.md` file and prints it if present (use this for per-project reminders)
+
+Example output injected into context:
+```
+=== Session Start: myproject (branch: feature/auth) ===
+Uncommitted changes: 3 files (M src/auth.py, M tests/test_auth.py, ?? .env.local)
+Session notes: Working on JWT refresh token implementation. Tests failing on line 42.
+```
+
+## Setup
+
+```bash
+cp hooks/lifecycle/session-start.sh .claude/hooks/
+chmod +x .claude/hooks/session-start.sh
+```
+
+Optionally create `.claude/session-notes.md` with notes for Claude at the start of each session. Update it as context changes.

package/hooks/lifecycle/session-start.sh

@@ -0,0 +1,47 @@
+#!/usr/bin/env bash
+# session-start.sh — loads context reminders at the start of each session
+#
+# Install: add to settings.json hooks.SessionStart
+# {
+#   "matcher": "",
+#   "hooks": [{
+#     "type": "command",
+#     "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/session-start.sh"
+#   }]
+# }
+
+set -euo pipefail
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+
+REMINDERS=()
+
+# Check for previous session state
+if [ -f "${PROJECT_DIR}/.claude/memory/session-state.md" ]; then
+  REMINDERS+=("Previous session state found at .claude/memory/session-state.md — read it before starting work.")
+fi
+
+# Check for current task file
+if [ -f "${PROJECT_DIR}/.claude/memory/current-task.md" ]; then
+  REMINDERS+=("Active task context found at .claude/memory/current-task.md — read it to understand what's in progress.")
+fi
+
+# Check for CONTEXT.md
+if [ -f "${PROJECT_DIR}/CONTEXT.md" ]; then
+  REMINDERS+=("Domain glossary available at CONTEXT.md — use it for project terminology.")
+fi
+
+# Check for ADRs
+if [ -d "${PROJECT_DIR}/docs/adr" ] && [ "$(ls -A "${PROJECT_DIR}/docs/adr" 2>/dev/null)" ]; then
+  ADR_COUNT=$(find "${PROJECT_DIR}/docs/adr" -name "*.md" | wc -l | tr -d ' ')
+  REMINDERS+=("${ADR_COUNT} architectural decisions recorded in docs/adr/ — check before making architectural choices.")
+fi
+
+# Output reminders
+if [ ${#REMINDERS[@]} -gt 0 ]; then
+  echo "=== Session context ==="
+  for reminder in "${REMINDERS[@]}"; do
+    echo "• $reminder"
+  done
+  echo "======================"
+fi

package/hooks/post-tool-use/audit-log.md

@@ -0,0 +1,53 @@
+# Hook: Audit Log
+
+Records every tool call to a structured JSONL log file for review, compliance, and debugging.
+
+## Event
+`PostToolUse` — fires after every tool call completes
+
+## settings.json entry
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/audit-log.sh",
+            "async": true
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Empty `matcher` means it fires for every tool, not just Bash. `async: true` means it runs in the background without blocking Claude.
+
+## What it does
+
+Appends a JSON line to `.claude/logs/audit.log` for every tool call:
+
+```json
+{"timestamp":"2026-05-13T10:23:45Z","tool":"Write","input":{"file_path":"/src/app.py"},"exit_code":0}
+```
+
+Fields logged: `timestamp`, `tool_name`, `tool_input` (sanitized — secrets stripped), `exit_code`, `duration_ms`.
+
+Useful for:
+- Auditing what Claude changed during a session
+- Debugging unexpected file modifications
+- Compliance requirements that mandate change logging
+
+## Setup
+
+```bash
+cp hooks/post-tool-use/audit-log.sh .claude/hooks/
+chmod +x .claude/hooks/audit-log.sh
+mkdir -p .claude/logs
+echo ".claude/logs/" >> .gitignore
+```

package/hooks/post-tool-use/audit-log.sh

@@ -0,0 +1,53 @@
+#!/usr/bin/env bash
+# audit-log.sh — logs every tool call with timestamp and tool name
+#
+# Install: add to settings.json hooks.PostToolUse
+# {
+#   "matcher": "",
+#   "hooks": [{
+#     "type": "command",
+#     "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/audit-log.sh",
+#     "async": true
+#   }]
+# }
+#
+# Log location: .claude/logs/audit.log
+# Add .claude/logs/ to .gitignore
+
+set -euo pipefail
+
+INPUT=$(cat)
+LOG_FILE="${CLAUDE_PROJECT_DIR:-$(pwd)}/.claude/logs/audit.log"
+TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+mkdir -p "$(dirname "$LOG_FILE")"
+
+TOOL_NAME=$(echo "$INPUT" | python3 -c "
+import sys, json
+try:
+    d = json.load(sys.stdin)
+    print(d.get('tool_name', 'unknown'))
+except:
+    print('unknown')
+" 2>/dev/null || echo "unknown")
+
+TOOL_SUMMARY=$(echo "$INPUT" | python3 -c "
+import sys, json
+try:
+    d = json.load(sys.stdin)
+    inp = d.get('tool_input', {})
+    # Summarize without exposing sensitive values
+    if 'command' in inp:
+        print(f\"cmd: {str(inp['command'])[:120]}\")
+    elif 'file_path' in inp:
+        print(f\"file: {inp['file_path']}\")
+    elif 'url' in inp:
+        print(f\"url: {inp['url']}\")
+    else:
+        keys = list(inp.keys())[:3]
+        print(f\"keys: {keys}\")
+except:
+    print('(parse error)')
+" 2>/dev/null || echo "(error)")
+
+echo "${TIMESTAMP} | ${TOOL_NAME} | ${TOOL_SUMMARY}" >> "$LOG_FILE"

package/hooks/post-tool-use/prettier.md

@@ -0,0 +1,53 @@
+# Hook: Auto-Prettier
+
+Runs Prettier on any file written or edited by Claude, keeping formatting consistent without a separate format step.
+
+## Event
+`PostToolUse` — fires after `Write` and `Edit` tool calls
+
+## settings.json entry
+
+```json
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/prettier.sh",
+            "async": true
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Matcher `Write|Edit` limits this to file-writing tools only — no overhead on Bash or Read calls.
+
+## What it does
+
+Extracts the `file_path` from the tool input JSON, checks if Prettier supports that file extension (`.ts`, `.tsx`, `.js`, `.jsx`, `.json`, `.css`, `.md`), and runs:
+
+```bash
+npx prettier --write "$FILE_PATH"
+```
+
+Runs async so it doesn't block Claude's next action. If Prettier isn't installed or fails, the hook exits silently — it never blocks Claude.
+
+## Requirements
+
+- Node.js ≥ 18
+- `prettier` in the project's `node_modules` or globally installed
+- A `.prettierrc` or `prettier.config.js` in the project root (optional — uses Prettier defaults otherwise)
+
+## Setup
+
+```bash
+cp hooks/post-tool-use/prettier.sh .claude/hooks/
+chmod +x .claude/hooks/prettier.sh
+npm install --save-dev prettier   # if not already installed
+```

package/hooks/post-tool-use/prettier.sh

@@ -0,0 +1,49 @@
+#!/usr/bin/env bash
+# prettier.sh — auto-formats files after Claude writes or edits them
+#
+# Install: add to settings.json hooks.PostToolUse
+# {
+#   "matcher": "Write|Edit",
+#   "hooks": [{
+#     "type": "command",
+#     "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/prettier.sh",
+#     "async": true
+#   }]
+# }
+#
+# Requires: prettier installed (npx prettier or local node_modules)
+
+set -euo pipefail
+
+INPUT=$(cat)
+
+FILE_PATH=$(echo "$INPUT" | python3 -c "
+import sys, json
+try:
+    d = json.load(sys.stdin)
+    print(d.get('tool_input', {}).get('file_path', ''))
+except:
+    print('')
+" 2>/dev/null || echo "")
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Only format files prettier supports
+SUPPORTED_EXTENSIONS=("js" "jsx" "ts" "tsx" "json" "css" "scss" "html" "md" "yaml" "yml")
+EXTENSION="${FILE_PATH##*.}"
+
+for ext in "${SUPPORTED_EXTENSIONS[@]}"; do
+  if [ "$EXTENSION" = "$ext" ]; then
+    # Use local prettier if available, fall back to npx
+    if [ -f "${CLAUDE_PROJECT_DIR:-$(pwd)}/node_modules/.bin/prettier" ]; then
+      "${CLAUDE_PROJECT_DIR:-$(pwd)}/node_modules/.bin/prettier" --write "$FILE_PATH" 2>/dev/null || true
+    else
+      npx prettier --write "$FILE_PATH" 2>/dev/null || true
+    fi
+    exit 0
+  fi
+done
+
+exit 0

package/hooks/pre-tool-use/block-dangerous.md

@@ -0,0 +1,48 @@
+# Hook: Block Dangerous Commands
+
+Intercepts `Bash` tool calls before they execute and blocks or warns on destructive shell patterns.
+
+## Event
+`PreToolUse` — fires before every tool call, matcher set to `Bash`
+
+## settings.json entry
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-dangerous.sh",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## What it does
+
+Reads the `tool_input.command` field from the JSON payload on stdin and matches it against two pattern lists:
+
+- **Blocked patterns** (exit 2 — hard block): `rm -rf /`, `rm -rf ~`, `mkfs`, `dd if=/dev/zero`, fork bomb, `chmod -R 777 /`
+- **Warning patterns** (exit 1 — Claude sees warning, user decides): `rm -rf`, pipe to `bash`/`sh`, `sudo`, `git push --force`, `git reset --hard`, `DROP TABLE`, `TRUNCATE`
+
+Exit code semantics:
+- `0` — allow
+- `1` — warn (Claude reports the warning and asks for confirmation)
+- `2` — block (Claude refuses to run the command)
+
+## Setup
+
+```bash
+cp hooks/pre-tool-use/block-dangerous.sh .claude/hooks/
+chmod +x .claude/hooks/block-dangerous.sh
+```
+
+Then add the `settings.json` entry above to `.claude/settings.json` or `~/.claude/settings.json`.

package/hooks/pre-tool-use/block-dangerous.sh

@@ -0,0 +1,76 @@
+#!/usr/bin/env bash
+# block-dangerous.sh — blocks destructive shell commands before they execute
+#
+# Install: add to settings.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, 2=block
+
+set -euo pipefail
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | python3 -c "
+import sys, json
+try:
+    d = json.load(sys.stdin)
+    print(d.get('tool_input', {}).get('command', ''))
+except:
+    print('')
+" 2>/dev/null || echo "")
+
+if [ -z "$COMMAND" ]; then
+  exit 0
+fi
+
+# Patterns that are always blocked
+BLOCKED_PATTERNS=(
+  "rm -rf /"
+  "rm -rf ~"
+  "rm -rf \$HOME"
+  "> /dev/sda"
+  "mkfs"
+  "dd if=/dev/zero"
+  ":(){ :|:& };:"          # Fork bomb
+  "chmod -R 777 /"
+  "chown -R"
+)
+
+for pattern in "${BLOCKED_PATTERNS[@]}"; do
+  if echo "$COMMAND" | grep -qF "$pattern" 2>/dev/null; then
+    echo "BLOCKED: '${pattern}' is not permitted." >&2
+    exit 2
+  fi
+done
+
+# Patterns that require warning (exit 1 — Claude sees warning, user decides)
+WARN_PATTERNS=(
+  "rm -rf"
+  "| bash"
+  "| sh"
+  "| zsh"
+  "curl.*| "
+  "wget.*| "
+  "sudo "
+  "git push --force"
+  "git reset --hard"
+  "git clean -f"
+  "DROP TABLE"
+  "DROP DATABASE"
+  "TRUNCATE"
+)
+
+for pattern in "${WARN_PATTERNS[@]}"; do
+  if echo "$COMMAND" | grep -qi "$pattern" 2>/dev/null; then
+    echo "WARNING: command matches potentially dangerous pattern '${pattern}'. Proceed only if intentional." >&2
+    exit 1
+  fi
+done
+
+exit 0

package/hooks/pre-tool-use/git-push-confirm.md

@@ -0,0 +1,46 @@
+# Hook: Git Push Confirmation
+
+Intercepts `git push` calls and requires explicit confirmation before proceeding, preventing accidental pushes to remote branches.
+
+## Event
+`PreToolUse` — fires before every Bash tool call, checks for `git push` in the command
+
+## settings.json entry
+
+```json
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/git-push-confirm.sh",
+            "timeout": 10
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## What it does
+
+When a `Bash` command contains `git push`, the hook:
+1. Extracts the remote and branch from the command
+2. Checks if the target is `main` or `master` — exits 2 (hard block) for force pushes to protected branches
+3. Exits 1 (warning) for all other `git push` commands, giving Claude a message to surface to the user
+
+Regular `git push` to feature branches: user sees a warning and can confirm.
+Force push to main/master: always blocked.
+
+## Setup
+
+```bash
+cp hooks/pre-tool-use/git-push-confirm.sh .claude/hooks/
+chmod +x .claude/hooks/git-push-confirm.sh
+```
+
+Add the `settings.json` entry above. Can be combined with `block-dangerous.sh` — both run as separate entries in the `PreToolUse` array.

package/hooks/pre-tool-use/git-push-confirm.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+# git-push-confirm.sh — warns before any git push operation
+#
+# Install: add to settings.json hooks.PreToolUse
+# {
+#   "matcher": "Bash",
+#   "hooks": [{
+#     "type": "command",
+#     "command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/git-push-confirm.sh",
+#     "timeout": 5
+#   }]
+# }
+
+set -euo pipefail
+
+INPUT=$(cat)
+COMMAND=$(echo "$INPUT" | python3 -c "
+import sys, json
+try:
+    d = json.load(sys.stdin)
+    print(d.get('tool_input', {}).get('command', ''))
+except:
+    print('')
+" 2>/dev/null || echo "")
+
+if echo "$COMMAND" | grep -q "git push"; then
+  # Extract branch info if possible
+  BRANCH=$(git rev-parse --abbrev-ref HEAD 2>/dev/null || echo "unknown")
+  REMOTE=$(echo "$COMMAND" | grep -oP '(?<=git push )\S+' 2>/dev/null || echo "origin")
+
+  echo "⚠️  About to push branch '${BRANCH}' to '${REMOTE}'." >&2
+  echo "Confirm this is intentional before proceeding." >&2
+  exit 1
+fi
+
+exit 0

package/mcp/configs/github.json

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "github": {
+      "command": "npx",
+      "args": ["-y", "@modelcontextprotocol/server-github"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_PERSONAL_ACCESS_TOKEN}"
+      }
+    }
+  }
+}