@panchr/tyr 0.1.0

package/README.md

@@ -0,0 +1,276 @@
+# tyr
+
+> **Experimental** — tyr is under active development. The API, configuration schema, and CLI interface may change without notice.
+
+Intelligent permission management for [Claude Code](https://docs.anthropic.com/en/docs/claude-code) hooks. Tyr intercepts `PermissionRequest` events from Claude Code and evaluates them against your configured allow/deny patterns, so you can auto-approve safe commands and block dangerous ones without manual intervention.
+
+Named after the [Norse god of justice](https://en.wikipedia.org/wiki/T%C3%BDr).
+
+## How it works
+
+Tyr registers itself as a Claude Code [hook](https://docs.anthropic.com/en/docs/claude-code/hooks) on the `PermissionRequest` event. When Claude Code asks to run a shell command, tyr:
+
+1. Reads your Claude Code allow/deny permission patterns
+2. Parses compound commands (e.g. `git add . && git commit`) and checks each component
+3. Optionally asks an LLM to evaluate ambiguous commands against your patterns
+4. Returns allow/deny/abstain back to Claude Code
+
+## Why tyr?
+
+Claude Code's `--dangerously-skip-permissions` flag gives the agent full autonomy — it can run any command without asking. That's fast, but risky: a single bad tool call can delete files, leak secrets, or break your environment with no audit trail.
+
+Tyr gives you the same automation benefits with granular control and full observability. You choose how much autonomy to grant:
+
+| Mode | What happens | Use case |
+|------|-------------|----------|
+| **Audit** (`tyr install --audit`) | Logs every permission request without evaluating it | Understand what Claude Code is doing before changing anything |
+| **Shadow** (`tyr install --shadow`) | Runs the full allow/deny pipeline but always abstains to Claude Code | Validate your rules against real traffic before going live |
+| **Active** (`tyr install`) | Evaluates requests and enforces allow/deny decisions | Full automation with pattern-based guardrails |
+
+Every decision is logged to a SQLite database, so you can review what was allowed, denied, or abstained — and why.
+
+## Prerequisites
+
+- [Bun](https://bun.sh) runtime
+- Claude Code (for integration — tyr can be tested standalone)
+
+## Install
+
+```bash
+# Clone and install dependencies
+git clone git@github.com:panchr/tyr.git && cd tyr
+bun install
+
+# Build and install the binary to /usr/local/bin
+bun run build
+
+# Register the hook in your project (writes to .claude/settings.json)
+tyr install
+
+# Or install globally (writes to ~/.claude/settings.json)
+tyr install --global
+```
+
+To remove:
+
+```bash
+tyr uninstall
+tyr uninstall --global
+```
+
+Use `--dry-run` with either command to preview changes without modifying anything.
+
+## Usage
+
+Once installed, tyr runs automatically as a Claude Code hook. No manual invocation needed.
+
+### Commands
+
+```
+tyr install [--global] [--project] [--dry-run] [--shadow|--audit]
+tyr uninstall [--global] [--project] [--dry-run]
+tyr config show
+tyr config set <key> <value>
+tyr config path
+tyr config env set <key> <value>
+tyr config env show
+tyr config env path
+tyr log [--last N] [--json] [--since T] [--until T] [--decision D] [--provider P] [--cwd C] [--verbose]
+tyr log clear
+tyr db migrate
+tyr stats [--since T] [--json]
+tyr suggest [--apply] [--global|--project] [--min-count N] [--json]
+tyr debug claude-config [--cwd C]
+tyr version
+```
+
+### Configuration
+
+Tyr reads its own config from `~/.config/tyr/config.json` (overridable via `TYR_CONFIG_FILE`). The config file supports JSON with comments (JSONC).
+
+| Key | Type | Default | Description |
+|-----|------|---------|-------------|
+| `providers` | string[] | `["chained-commands"]` | Ordered list of providers to run |
+| `failOpen` | boolean | `false` | Approve on error instead of failing closed |
+| `claude.model` | string | `"haiku"` | Model identifier for the Claude CLI |
+| `claude.timeout` | number | `10` | Claude request timeout in seconds |
+| `claude.canDeny` | boolean | `false` | Whether Claude can deny requests |
+| `openrouter.model` | string | `"anthropic/claude-3.5-haiku"` | Model for OpenRouter API |
+| `openrouter.endpoint` | string | `"https://openrouter.ai/api/v1"` | OpenRouter API endpoint |
+| `openrouter.timeout` | number | `10` | OpenRouter request timeout in seconds |
+| `openrouter.canDeny` | boolean | `false` | Whether OpenRouter can deny requests |
+| `verboseLog` | boolean | `false` | Include LLM prompt/params in log entries |
+| `logRetention` | string | `"30d"` | Auto-prune logs older than this (`"0"` to disable) |
+
+All config values can be overridden per-invocation via CLI flags on the `judge` command (e.g. `--fail-open`, `--claude-model`). These flags are passed through the hook configuration in `.claude/settings.json`.
+
+### Environment variables
+
+Tyr loads environment variables from `~/.config/tyr/.env` (next to the config file). This is the recommended place to store API keys.
+
+```bash
+# Store your OpenRouter API key
+tyr config env set OPENROUTER_API_KEY sk-or-...
+
+# View stored variables (values masked)
+tyr config env show
+
+# Print .env file path
+tyr config env path
+```
+
+Existing process environment variables take precedence over `.env` values.
+
+### Providers
+
+Tyr uses a **pipeline architecture** where providers are evaluated in sequence. The first provider to return a definitive `allow` or `deny` wins — remaining providers are skipped. If all providers `abstain`, the request falls through to Claude Code's default behavior (prompting the user), unless `failOpen` is `true`, in which case the request is approved.
+
+Configure the pipeline via the `providers` array. **Order matters** — providers run left to right.
+
+Valid provider names: `cache`, `chained-commands`, `claude`, `openrouter`.
+
+#### `cache`
+
+Caches prior decisions in SQLite. If the same command was previously allowed or denied (with the same config and permission rules), returns the cached result immediately. The cache auto-invalidates when your config or Claude Code permission rules change.
+
+**Best practice:** Place first in the pipeline to skip expensive downstream evaluations.
+
+#### `chained-commands`
+
+Parses compound shell commands (`&&`, `||`, `|`, `;`, subshells, command substitution) and checks each sub-command against your Claude Code allow/deny permission patterns (merged from all settings files).
+
+- **Allow:** All sub-commands match an allow pattern
+- **Deny:** Any sub-command matches a deny pattern
+- **Abstain:** Any sub-command has no matching pattern
+
+Only evaluates `Bash` tool requests; abstains on all other tools.
+
+#### `claude`
+
+Sends ambiguous commands to a local Claude CLI for semantic evaluation. The LLM sees your permission rules, the command, and the working directory, then reasons about whether the command is safe.
+
+When `claude.canDeny` is `false` (the default), the LLM can only approve commands — deny decisions are converted to abstain, forcing the user to decide. Set `canDeny: true` for stricter enforcement.
+
+Requires a local `claude` CLI binary (installed with Claude Code). Timeouts and errors are treated as abstain.
+
+Only evaluates `Bash` tool requests; abstains on all other tools.
+
+#### `openrouter`
+
+Sends ambiguous commands to the OpenRouter API for evaluation. Same semantics as the `claude` provider but uses an HTTP API instead of the local CLI.
+
+Requires `OPENROUTER_API_KEY` set in your environment or `.env` file.
+
+Only evaluates `Bash` tool requests; abstains on all other tools.
+
+#### Pipeline examples
+
+```jsonc
+// Safe & fast (default) — pattern matching only
+{ "providers": ["chained-commands"] }
+
+// With caching — faster repeated evaluations
+{ "providers": ["cache", "chained-commands"] }
+
+// Full pipeline — patterns first, then Claude for ambiguous commands
+{ "providers": ["cache", "chained-commands", "claude"] }
+
+// Using OpenRouter instead of local Claude
+{ "providers": ["cache", "chained-commands", "openrouter"] }
+```
+
+### Viewing logs
+
+Every permission decision is logged to a SQLite database at `~/.local/share/tyr/tyr.db` (overridable via `TYR_DB_PATH`).
+
+```bash
+# View recent decisions (default: last 20)
+tyr log
+
+# Show more entries
+tyr log --last 50
+
+# Filter by decision type
+tyr log --decision allow
+tyr log --decision deny
+
+# Filter by time range (ISO or relative: 1h, 30m, 7d)
+tyr log --since 1h
+tyr log --since 2025-01-01 --until 2025-01-31
+
+# Filter by provider or working directory
+tyr log --provider chained-commands
+tyr log --cwd /path/to/project
+
+# JSON output
+tyr log --json
+
+# Show LLM prompts for verbose-logged entries
+tyr log --verbose
+
+# Clear all logs
+tyr log clear
+```
+
+Log entries are automatically pruned based on the `logRetention` config setting (default: 30 days).
+
+### Statistics
+
+```bash
+# View overall stats
+tyr stats
+
+# Stats for the last 7 days
+tyr stats --since 7d
+
+# Machine-readable JSON
+tyr stats --json
+```
+
+Shows: total checks, decision breakdown (allow/deny/abstain/error), cache hit rate, provider distribution, and auto-approval count.
+
+### Suggestions
+
+Tyr can analyze your decision history and recommend new allow rules to add to Claude Code's settings:
+
+```bash
+# View suggestions (commands approved >= 5 times by default)
+tyr suggest
+
+# Lower the threshold
+tyr suggest --min-count 3
+
+# Apply suggestions to global settings
+tyr suggest --apply --global
+
+# Apply to project settings
+tyr suggest --apply --project
+```
+
+### Debugging
+
+```bash
+# Print the merged Claude Code permission config for the current project
+tyr debug claude-config
+
+# Print for a different project directory
+tyr debug claude-config --cwd /path/to/project
+
+# Print tyr version and runtime info
+tyr version
+```
+
+### Database migrations
+
+```bash
+# Run pending schema migrations
+tyr db migrate
+```
+
+## Development
+
+```bash
+bun test              # Run all tests
+bun run typecheck     # Type-check without emitting
+bun run lint          # Lint with Biome
+```

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@panchr/tyr",
+  "description": "Intelligent permission management for Claude Code hooks",
+  "module": "src/index.ts",
+  "type": "module",
+  "version": "0.1.0",
+  "bin": {
+    "tyr": "src/index.ts"
+  },
+  "files": ["src/", "!src/__tests__/"],
+  "scripts": {
+    "start": "bun run src/index.ts",
+    "build": "bun run scripts/build.ts",
+    "lint": "biome check src/",
+    "lint:fix": "biome check --write src/",
+    "test": "bun test",
+    "test:smoke": "bun test ./src/__tests__/smoke.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.15",
+    "@types/bun": "latest"
+  },
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "dependencies": {
+    "citty": "^0.2.1",
+    "mvdan-sh": "^0.10.1",
+    "zod": "^4.3.6"
+  }
+}

package/src/agents/claude.ts

@@ -0,0 +1,143 @@
+import { type FSWatcher, watch } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { readSettings } from "../install.ts";
+
+/** Parse Bash permission rules into command patterns.
+ *  "Bash(npm run *)" → "npm run *", bare "Bash" → "*".
+ *  Non-Bash rules are ignored. */
+export function extractBashPatterns(rules: unknown[]): string[] {
+	const patterns: string[] = [];
+	for (const rule of rules) {
+		if (typeof rule !== "string") continue;
+		if (rule === "Bash") {
+			patterns.push("*");
+			continue;
+		}
+		const match = rule.match(/^Bash\((.+)\)$/);
+		if (match?.[1]) {
+			patterns.push(match[1]);
+		}
+	}
+	return patterns;
+}
+
+/** Check if a command matches a glob-style pattern.
+ *  `*` in the pattern matches any sequence of characters. */
+export function matchPattern(pattern: string, command: string): boolean {
+	const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+	const regex = new RegExp(`^${escaped.replace(/\*+/g, ".*")}$`);
+	return regex.test(command);
+}
+
+/** Return settings file paths in precedence order (highest first). */
+export function settingsPaths(cwd: string): string[] {
+	const configDir = process.env.CLAUDE_CONFIG_DIR ?? join(homedir(), ".claude");
+	const paths: string[] = [];
+
+	// 1. Managed (macOS)
+	if (process.platform === "darwin") {
+		paths.push("/Library/Application Support/ClaudeCode/managed-settings.json");
+	}
+
+	// 2. Local project
+	paths.push(join(cwd, ".claude", "settings.local.json"));
+
+	// 3. Project shared
+	paths.push(join(cwd, ".claude", "settings.json"));
+
+	// 4. User global
+	paths.push(join(configDir, "settings.json"));
+
+	return paths;
+}
+
+interface MergedPermissions {
+	allow: string[];
+	deny: string[];
+}
+
+/** Merge permissions from all settings files in precedence order. */
+async function loadPermissions(paths: string[]): Promise<MergedPermissions> {
+	const allow: string[] = [];
+	const deny: string[] = [];
+
+	for (const path of paths) {
+		const settings = await readSettings(path);
+		const perms = settings.permissions as Record<string, unknown> | undefined;
+		if (!perms) continue;
+
+		if (Array.isArray(perms.allow)) {
+			allow.push(...extractBashPatterns(perms.allow));
+		}
+		if (Array.isArray(perms.deny)) {
+			deny.push(...extractBashPatterns(perms.deny));
+		}
+	}
+
+	return { allow, deny };
+}
+
+export class ClaudeAgent {
+	private allow: string[] = [];
+	private deny: string[] = [];
+	private watchers: FSWatcher[] = [];
+	private paths: string[] = [];
+
+	/** Read all settings files and start watching for changes.
+	 *  If `paths` is provided, use those instead of auto-detected paths. */
+	async init(cwd?: string, paths?: string[]): Promise<void> {
+		this.paths = paths ?? settingsPaths(cwd ?? process.cwd());
+		await this.reload();
+
+		for (const path of this.paths) {
+			try {
+				const watcher = watch(path, () => {
+					void this.reload();
+				});
+				this.watchers.push(watcher);
+			} catch {
+				// File doesn't exist yet — skip watching
+			}
+		}
+	}
+
+	/** Return the resolved settings file paths and merged permissions. */
+	getDebugInfo(): {
+		paths: string[];
+		allow: string[];
+		deny: string[];
+	} {
+		return {
+			paths: [...this.paths],
+			allow: [...this.allow],
+			deny: [...this.deny],
+		};
+	}
+
+	/** Check if a command is allowed/denied/unknown per configured permissions. */
+	isCommandAllowed(cmd: string): "allow" | "deny" | "unknown" {
+		// Deny rules are evaluated first; first match wins.
+		for (const pattern of this.deny) {
+			if (matchPattern(pattern, cmd)) return "deny";
+		}
+		for (const pattern of this.allow) {
+			if (matchPattern(pattern, cmd)) return "allow";
+		}
+		return "unknown";
+	}
+
+	/** Stop watching settings files. */
+	close(): void {
+		for (const watcher of this.watchers) {
+			watcher.close();
+		}
+		this.watchers = [];
+	}
+
+	private async reload(): Promise<void> {
+		const perms = await loadPermissions(this.paths);
+		this.allow = perms.allow;
+		this.deny = perms.deny;
+	}
+}

package/src/args.ts

@@ -0,0 +1,55 @@
+import type { ArgsDef } from "citty";
+
+/** Parse a relative time string like '1h', '30m', '2d' into a Date, or parse ISO. */
+export function parseTime(value: string): Date | null {
+	const relativeMatch = value.match(/^(\d+)([smhd])$/);
+	if (relativeMatch) {
+		const amount = Number(relativeMatch[1]);
+		const unit = relativeMatch[2];
+		const multipliers: Record<string, number> = {
+			s: 1000,
+			m: 60_000,
+			h: 3_600_000,
+			d: 86_400_000,
+		};
+		const ms = multipliers[unit as string];
+		if (ms === undefined) return null;
+		return new Date(Date.now() - amount * ms);
+	}
+	const d = new Date(value);
+	return Number.isNaN(d.getTime()) ? null : d;
+}
+
+/**
+ * Reject unknown flags in rawArgs that aren't defined in argsDef.
+ * Citty parses with strict:false, so we validate manually.
+ */
+export function rejectUnknownArgs(rawArgs: string[], argsDef: ArgsDef): void {
+	const known = new Set<string>();
+	for (const [name, def] of Object.entries(argsDef)) {
+		known.add(`--${name}`);
+		if ("type" in def && def.type === "boolean") {
+			known.add(`--no-${name}`);
+		}
+		if ("alias" in def) {
+			const aliases = Array.isArray(def.alias) ? def.alias : [def.alias];
+			for (const a of aliases) {
+				if (a) known.add(a.length === 1 ? `-${a}` : `--${a}`);
+			}
+		}
+	}
+	// Always allow --help and --version
+	known.add("--help");
+	known.add("-h");
+	known.add("--version");
+
+	for (const arg of rawArgs) {
+		if (!arg.startsWith("-")) continue;
+		// Handle --flag=value
+		const flag = arg.split("=")[0] ?? arg;
+		if (!known.has(flag)) {
+			console.error(`Unknown option: ${flag}`);
+			process.exit(1);
+		}
+	}
+}

package/src/cache.ts

@@ -0,0 +1,84 @@
+import { createHash } from "node:crypto";
+import type { ClaudeAgent } from "./agents/claude.ts";
+import { getDb } from "./db.ts";
+import { extractToolInput } from "./log.ts";
+import type { PermissionRequest, TyrConfig } from "./types.ts";
+import { resolveProviders } from "./types.ts";
+
+interface CacheHit {
+	decision: "allow" | "deny";
+	provider: string;
+	reason: string | null;
+}
+
+/** Compute a config fingerprint covering both Claude's rules and tyr's config. */
+export function computeConfigHash(
+	agent: ClaudeAgent,
+	config: TyrConfig,
+): string {
+	const info = agent.getDebugInfo();
+	const data = JSON.stringify({
+		allow: [...info.allow].sort(),
+		deny: [...info.deny].sort(),
+		providers: resolveProviders(config),
+		failOpen: config.failOpen,
+		"claude.model": config.claude.model,
+		"claude.canDeny": config.claude.canDeny,
+		"openrouter.model": config.openrouter.model,
+		"openrouter.canDeny": config.openrouter.canDeny,
+	});
+	return createHash("sha256").update(data).digest("hex");
+}
+
+/** Look up a cached decision. Returns null on miss. */
+export function checkCache(
+	req: PermissionRequest,
+	configHash: string,
+): CacheHit | null {
+	const db = getDb();
+	const toolInput = extractToolInput(req.tool_name, req.tool_input);
+
+	const row = db
+		.query(
+			"SELECT decision, provider, reason FROM cache WHERE tool_name = ? AND tool_input = ? AND cwd = ? AND config_hash = ?",
+		)
+		.get(req.tool_name, toolInput, req.cwd, configHash) as {
+		decision: string;
+		provider: string;
+		reason: string | null;
+	} | null;
+
+	if (!row) return null;
+
+	return {
+		decision: row.decision as "allow" | "deny",
+		provider: row.provider,
+		reason: row.reason,
+	};
+}
+
+/** Store a definitive decision in the cache. Only allow/deny are cached. */
+export function writeCache(
+	req: PermissionRequest,
+	decision: "allow" | "deny",
+	provider: string,
+	reason: string | undefined,
+	configHash: string,
+): void {
+	const db = getDb();
+	const toolInput = extractToolInput(req.tool_name, req.tool_input);
+
+	db.query(
+		`INSERT OR REPLACE INTO cache (tool_name, tool_input, cwd, decision, provider, reason, config_hash, created_at)
+		 VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+	).run(
+		req.tool_name,
+		toolInput,
+		req.cwd,
+		decision,
+		provider,
+		reason ?? null,
+		configHash,
+		Date.now(),
+	);
+}