@panchr/tyr 0.2.0 → 0.2.2

package/README.md

@@ -54,37 +54,15 @@ tyr uninstall          # project
 tyr uninstall --global # global
 ```
 
-Use `--dry-run` with either command to preview changes without modifying anything.
+Use `--dry-run` with either command to preview changes without modifying anything. Run `tyr --help` for the full command reference.
 
-## Usage
-
-### 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 [--global|--project] [--min-count N] [--all]
-tyr debug claude-config [--cwd C]
-tyr version
-```
-
-### Configuration
+## 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", "claude"]` | Ordered list of providers to run |
+| `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 |
@@ -97,40 +75,25 @@ Tyr reads its own config from `~/.config/tyr/config.json` (overridable via `TYR_
 | `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`.
+Use `tyr config show` to view the current config, `tyr config set <key> <value>` to update a value, `tyr config example` to print a recommended starter config, and `tyr config schema` to print the JSON Schema.
 
 ### 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.
+Tyr loads environment variables from `~/.config/tyr/.env` (next to the config file). This is the recommended place to store API keys (e.g., `OPENROUTER_API_KEY`). Use `tyr config env set <key> <value>` to manage them. Existing process environment variables take precedence.
 
-### Providers
+## 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 in order.
 
-Valid providers are listed below.
-
-#### `cache`
+### `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`
+### `chained-commands`
 
 Parses compound shell commands (`&&`, `||`, `|`, `;`, subshells, command substitution) and checks each sub-command against your Claude Code allow/deny permission patterns.
 
@@ -138,7 +101,7 @@ Parses compound shell commands (`&&`, `||`, `|`, `;`, subshells, command substit
 - **Deny:** _Any_ sub-command matches a deny pattern
 - **Abstain:** Any sub-command has no matching pattern
 
-#### `claude`
+### `claude`
 
 Sends ambiguous commands to the 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.
 
@@ -146,19 +109,13 @@ When `claude.canDeny` is `false` (the default), the LLM can only approve command
 
 When `conversationContext` is enabled, the LLM also sees recent conversation messages from the Claude Code session. This lets it allow commands that don't match any configured pattern if the user clearly requested the action and it's a typical, safe development command. The deny list is always checked first -- no amount of context overrides a denied pattern.
 
-Requires a local `claude` CLI binary. While this is somewhat slow due to the subprocess required to run `claude` (generally a decision is made in about 5 seconds), this slowness is acceptable given that it will still be faster than a human understanding and approving a command.
-
-The main benefit of this provider is that it reuses the authentication that `claude` is already configured with, whether that's an Anthropic API key or a subscription.
-
-#### `openrouter`
+Note: this provider adds ~5 seconds of latency per evaluation due to the subprocess overhead, but this is still faster than a human reviewing and approving a command. It also reuses whatever authentication `claude` is already configured with.
 
-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. Supports `conversationContext` in the same way.
+### `openrouter`
 
-Requires `OPENROUTER_API_KEY` set in your environment or `.env` file.
+Same semantics as the `claude` provider but uses the OpenRouter HTTP API instead of the local CLI. Supports `conversationContext` in the same way. Requires `OPENROUTER_API_KEY`.
 
-Only evaluates `Bash` tool requests; abstains on all other tools.
-
-#### Pipeline examples
+### Pipeline examples
 
 ```jsonc
 // Safe & fast (default) -- pattern matching only
@@ -174,82 +131,20 @@ Only evaluates `Bash` tool requests; abstains on all other tools.
 { "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.
+### Permission prompt delay
 
-### Suggestions
+When tyr is installed as a hook, Claude Code shows the permission prompt and calls the hook concurrently. You'll see the prompt appear immediately while tyr evaluates the command in the background. If the hook decides to allow or deny, the prompt is automatically resolved; if the hook abstains, the prompt remains for you to decide manually.
 
-Tyr can analyze your decision history and start an interactive Claude session to help you refine and apply allow rules:
+## Database management
 
-```bash
-# Start an interactive session with suggested rules (commands approved >= 5 times)
-tyr suggest
-
-# Lower the threshold for which commands are surfaced
-tyr suggest --min-count 3
+Tyr stores all decision logs and cached results in a SQLite database at `~/.local/share/tyr/tyr.db` (overridable via `TYR_DB_PATH`).
 
-# Target project settings instead of global
-tyr suggest --project
+| Command | Description |
+|---------|-------------|
+| `tyr db migrate` | Run pending schema migrations after upgrading tyr |
+| `tyr db rename <old> <new>` | Update stored project paths after moving a directory |
 
-# Include commands from all projects, not just the current directory
-tyr suggest --all
-```
-
-### Database migrations
-
-When upgrading from one `tyr` version to another, run
-
-```bash
-# Run pending schema migrations
-tyr db migrate
-```
+`tyr db rename` is useful when you relocate a project on disk. It rewrites the `cwd` column in both the logs and cache tables (including subpaths) so that `tyr log`, `tyr stats`, and cache lookups continue to work for the moved project.
 
 ## Development
 

package/package.json

@@ -3,7 +3,7 @@
   "description": "Intelligent permission management for Claude Code hooks",
   "module": "src/index.ts",
   "type": "module",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "bin": {
     "tyr": "src/index.ts"
   },

package/src/commands/config.ts

@@ -1,4 +1,5 @@
 import { defineCommand } from "citty";
+import { z } from "zod/v4";
 import {
 	getConfigPath,
 	getEnvPath,
@@ -167,6 +168,51 @@ const env = defineCommand({
 	},
 });
 
+const EXAMPLE_CONFIG = `{
+  // Pattern matching with caching for fast repeated evaluations.
+  // Add "claude" or "openrouter" after "chained-commands" to use an
+  // LLM for commands that don't match any allow/deny pattern.
+  "providers": ["cache", "chained-commands"],
+
+  // Fail closed: deny on error rather than auto-approving.
+  "failOpen": false,
+
+  // Auto-prune log entries older than 30 days.
+  "logRetention": "30d"
+}
+`;
+
+const example = defineCommand({
+	meta: {
+		name: "example",
+		description: "Print a recommended example config",
+	},
+	run() {
+		process.stdout.write(EXAMPLE_CONFIG);
+	},
+});
+
+const schema = defineCommand({
+	meta: {
+		name: "schema",
+		description: "Print the config JSON Schema",
+	},
+	run() {
+		const jsonSchema = z.toJSONSchema(TyrConfigSchema, {
+			target: "draft-2020-12",
+		});
+		// z.toJSONSchema cannot represent .refine() constraints;
+		// manually add the pattern for logRetention.
+		const props = (jsonSchema as { properties?: Record<string, object> })
+			.properties;
+		if (props?.logRetention) {
+			(props.logRetention as Record<string, unknown>).pattern =
+				"^(0|\\d+[smhd])$";
+		}
+		console.log(JSON.stringify(jsonSchema, null, 2));
+	},
+});
+
 export default defineCommand({
 	meta: {
 		name: "config",
@@ -176,6 +222,8 @@ export default defineCommand({
 		show,
 		set,
 		path,
+		example,
+		schema,
 		env,
 	},
 });

package/src/commands/db.ts

@@ -1,3 +1,4 @@
+import { resolve } from "node:path";
 import { defineCommand } from "citty";
 import {
 	CURRENT_SCHEMA_VERSION,
@@ -55,6 +56,62 @@ const migrate = defineCommand({
 	},
 });
 
+const rename = defineCommand({
+	meta: {
+		name: "rename",
+		description:
+			"Rename a project directory in the database (e.g. after moving a project)",
+	},
+	args: {
+		oldPath: {
+			type: "positional",
+			description: "Current project directory path",
+			required: true,
+		},
+		newPath: {
+			type: "positional",
+			description: "New project directory path",
+			required: true,
+		},
+	},
+	async run({ args }) {
+		const oldPath = resolve(args.oldPath as string);
+		const newPath = resolve(args.newPath as string);
+
+		if (oldPath === newPath) {
+			console.error("Old and new paths are the same.");
+			process.exit(1);
+		}
+
+		const db = openRawDb();
+
+		if (!hasMetaTable(db)) {
+			console.error("Database is uninitialized. Nothing to rename.");
+			db.close();
+			process.exit(1);
+		}
+
+		const escapedOld = oldPath.replace(/[\\%_]/g, "\\$&");
+
+		const updated = db.transaction(() => {
+			let total = 0;
+			for (const table of ["logs", "cache"] as const) {
+				const result = db
+					.query(
+						`UPDATE ${table} SET cwd = ? || substr(cwd, length(?) + 1)
+						 WHERE cwd = ? OR cwd LIKE ? || '/%' ESCAPE '\\'`,
+					)
+					.run(newPath, oldPath, oldPath, escapedOld);
+				total += result.changes;
+			}
+			return total;
+		})();
+
+		console.log(`Renamed ${oldPath} → ${newPath} (${updated} row(s) updated)`);
+		db.close();
+	},
+});
+
 export default defineCommand({
 	meta: {
 		name: "db",
@@ -62,5 +119,6 @@ export default defineCommand({
 	},
 	subCommands: {
 		migrate,
+		rename,
 	},
 });

package/src/commands/debug.ts

@@ -1,5 +1,6 @@
 import { defineCommand } from "citty";
 import { ClaudeAgent } from "../agents/claude.ts";
+import { getRepoRoot } from "../repo.ts";
 
 const claudeConfig = defineCommand({
 	meta: {
@@ -13,7 +14,7 @@ const claudeConfig = defineCommand({
 		},
 	},
 	async run({ args }) {
-		const cwd = (args.cwd as string | undefined) ?? process.cwd();
+		const cwd = (args.cwd as string | undefined) ?? getRepoRoot();
 		const agent = new ClaudeAgent();
 		await agent.init(cwd);
 		const info = agent.getDebugInfo();

package/src/commands/log.ts

@@ -10,6 +10,7 @@ import {
 	readLogEntries,
 	truncateOldLogs,
 } from "../log.ts";
+import { getRepoRoot } from "../repo.ts";
 
 function formatTime(ts: number): string {
 	const d = new Date(ts);
@@ -145,7 +146,7 @@ export default defineCommand({
 		}
 
 		// Default to current directory unless --all or --cwd is provided
-		const cwdFilter = args.all ? undefined : (args.cwd ?? process.cwd());
+		const cwdFilter = args.all ? undefined : (args.cwd ?? getRepoRoot());
 
 		const entries = readLogEntries({
 			last: last > 0 ? last : undefined,

package/src/commands/suggest.ts

@@ -1,3 +1,4 @@
+import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { defineCommand } from "citty";
@@ -9,6 +10,7 @@ import {
 import { rejectUnknownArgs } from "../args.ts";
 import { closeDb, getDb } from "../db.ts";
 import { readSettings } from "../install.ts";
+import { getRepoRoot } from "../repo.ts";
 
 const suggestArgs = {
 	global: {
@@ -92,35 +94,43 @@ export function getSuggestions(
 	return suggestions;
 }
 
-function buildSuggestSystemPrompt(
+export function buildSuggestPrompt(
 	suggestions: Suggestion[],
-	settingsPath: string,
+	targetPath: string,
+	allPaths: string[],
 ): string {
 	const commandList = suggestions
 		.map((s) => `- \`${s.command}\` (approved ${s.count} times)`)
 		.join("\n");
 
-	return `You are helping configure permission rules for Claude Code.
+	const pathList = allPaths.map((p) => `- \`${p}\``).join("\n");
 
-The user has been manually approving shell commands while using Claude Code. Tyr has identified frequently-approved commands that could be added as permanent allow rules.
+	return `I've been manually approving shell commands while using Claude Code. Tyr has identified frequently-approved commands that could be added as permanent allow rules.
 
 ## Frequently Approved Commands (not yet in allow rules)
 
 ${commandList}
 
-## Settings File
-- Path: ${settingsPath}
+## Settings Files
+
+Claude Code reads permissions from multiple settings files:
+
+${pathList}
+
+## Target Settings File
+- Write new rules to: \`${targetPath}\`
 - Format: JSON with a \`permissions.allow\` array of strings
-- Each rule is a string like \`Bash(pattern)\` where \`pattern\` can use \`*\` as a glob wildcard
+- Each rule MUST use the exact format \`Bash(pattern)\` where \`pattern\` can use \`*\` as a glob wildcard
 - Example: \`Bash(bun *)\` allows any command starting with \`bun \`
+- IMPORTANT: Before writing rules, read the settings files listed above (those that exist) to understand existing permissions, then merge new rules into the target file's \`permissions.allow\` array
 
-## Your Task
-Help the user decide which commands to add as allow rules:
+## Instructions
+Help me decide which commands to add as allow rules:
 1. Suggest generalized glob patterns that group similar commands (e.g., "bun test" and "bun lint" → "Bash(bun *)")
 2. Explain what each pattern would match
-3. When the user is ready, write the rules to the settings file at the path above
+3. When I'm ready, write the rules to the target settings file
 
-Be concise. Start by presenting your suggested rules and ask if the user wants to adjust them.`;
+Be concise. Start by presenting your suggested rules and ask if I want to adjust them.`;
 }
 
 export default defineCommand({
@@ -146,7 +156,8 @@ export default defineCommand({
 			return;
 		}
 
-		const allPaths = settingsPaths(process.cwd());
+		const repoRoot = getRepoRoot();
+		const allPaths = settingsPaths(repoRoot);
 		const allowPatterns: string[] = [];
 		for (const path of allPaths) {
 			const settings = await readSettings(path);
@@ -156,7 +167,7 @@ export default defineCommand({
 			}
 		}
 
-		const cwdFilter = args.all ? undefined : process.cwd();
+		const cwdFilter = args.all ? undefined : repoRoot;
 		const suggestions = getSuggestions(minCount, allowPatterns, cwdFilter);
 		closeDb();
 
@@ -165,17 +176,18 @@ export default defineCommand({
 			return;
 		}
 
-		const scope: "global" | "project" = args.project ? "project" : "global";
+		const scope: "global" | "project" = args.global ? "global" : "project";
 		const configDir =
 			process.env.CLAUDE_CONFIG_DIR ?? join(homedir(), ".claude");
-		const settingsPath =
+		const targetPath =
 			scope === "global"
 				? join(configDir, "settings.json")
-				: join(process.cwd(), ".claude", "settings.json");
+				: join(repoRoot, ".claude", "settings.json");
 
-		const systemPrompt = buildSuggestSystemPrompt(suggestions, settingsPath);
+		const existingPaths = allPaths.filter((p) => existsSync(p));
+		const prompt = buildSuggestPrompt(suggestions, targetPath, existingPaths);
 
-		const proc = Bun.spawn(["claude", "--append-system-prompt", systemPrompt], {
+		const proc = Bun.spawn(["claude", prompt], {
 			stdin: "inherit",
 			stdout: "inherit",
 			stderr: "inherit",

package/src/install.ts

@@ -1,6 +1,7 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+import { getRepoRoot } from "./repo.ts";
 
 export type JudgeMode = "shadow" | "audit" | undefined;
 
@@ -20,7 +21,7 @@ export function getSettingsPath(scope: "global" | "project"): string {
 	if (scope === "global") {
 		return join(homedir(), ".claude", "settings.json");
 	}
-	return join(process.cwd(), ".claude", "settings.json");
+	return join(getRepoRoot(), ".claude", "settings.json");
 }
 
 /** Read and parse a settings.json, returning {} if it doesn't exist. */

package/src/repo.ts

@@ -0,0 +1,24 @@
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+/**
+ * Walk up from `startDir` looking for a `.git` directory.
+ * Returns the repo root or `null` if not inside a git repository.
+ */
+export function findRepoRoot(startDir: string): string | null {
+	let dir = resolve(startDir);
+	for (;;) {
+		if (existsSync(join(dir, ".git"))) return dir;
+		const parent = dirname(dir);
+		if (parent === dir) return null;
+		dir = parent;
+	}
+}
+
+/**
+ * Returns the repo root for the current directory, falling back to
+ * `process.cwd()` when not inside a git repository.
+ */
+export function getRepoRoot(): string {
+	return findRepoRoot(process.cwd()) ?? process.cwd();
+}