@panchr/tyr 0.1.1 → 0.2.2

package/README.md

@@ -1,90 +1,62 @@
 # tyr
 
-> **Experimental** — tyr is under active development. The API, configuration schema, and CLI interface may change without notice.
+> **Experimental** — tyr is under active development. The API, configuration schema, and CLI interface may change without notice. If upgrading between minor versions, it's highly possible that a previous configuration needs some manual update.
 
-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.
+Tyr is a CLI for intelligently managing permissions for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). It is added as a hook on `PermissionRequest` events and evaluates them against configured allow/deny patterns. In the standard mode, this evaluation is done by Claude (or another LLM) by comparing the requested Bash command to the user's configuration. The hook will auto-approve commands that fuzzily match the configuration, without manual intervention.
 
-Named after the [Norse god of justice](https://en.wikipedia.org/wiki/T%C3%BDr).
+The goal is to reduce the number of permission prompts sent to the user. As of now, Tyr only evaluates `Bash` tool requests; it abstains on all other tools.
 
-## 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
+It is named after the [Norse god of justice](https://en.wikipedia.org/wiki/T%C3%BDr).
 
 ## 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.
+Claude Code's `--dangerously-skip-permissions` flag gives the agent full autonomy -- it can run any command without asking. That's risky: a single bad tool call can delete files, leak secrets, or break your environment.
 
-Tyr gives you the same automation benefits with granular control and full observability. You choose how much autonomy to grant:
+Tyr gives a configurable degree of autonomy to Claude:
 
 | 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 |
+| **Audit** (`tyr install --audit`) | Logs every permission request without evaluating it | Understand what Claude Code is doing without performing any of tyr's logic on the request |
+| **Shadow** (`tyr install --shadow`) | Runs the full allow/deny pipeline but always abstains to Claude Code | Validate your rules against real requests, before an impact |
 | **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
+## Quickstart
 
-- [Bun](https://bun.sh) runtime
-- Claude Code (for integration — tyr can be tested standalone)
-
-## Install
+Requires [Bun](https://bun.sh) and [Claude Code](https://docs.anthropic.com/en/docs/claude-code).
 
 ```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
+# Install tyr
+bun install -g @panchr/tyr
 
-# Register the hook in your project (writes to .claude/settings.json)
+# Register the hook (run this inside your project directory)
 tyr install
 
-# Or install globally (writes to ~/.claude/settings.json)
-tyr install --global
+# Start a Claude Code session and work as usual — tyr runs automatically.
+# When you're done, review what happened:
+tyr log
+tyr stats
 ```
 
-To remove:
+That's it. Tyr evaluates every permission request against your Claude Code allow/deny patterns and logs the result. Commands that match an allowed pattern are auto-approved; everything else falls through to Claude Code's normal prompt.
+
+To install globally (applies to all projects):
 
 ```bash
-tyr uninstall
-tyr uninstall --global
+tyr install --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
+To remove:
 
-```
-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
+```bash
+tyr uninstall          # project
+tyr uninstall --global # global
 ```
 
-### Configuration
+Use `--dry-run` with either command to preview changes without modifying anything. Run `tyr --help` for the full command reference.
+
+## Configuration
 
 Tyr reads its own config from `~/.config/tyr/config.json` (overridable via `TYR_CONFIG_FILE`). The config file supports JSON with comments (JSONC).
 
@@ -99,173 +71,80 @@ Tyr reads its own config from `~/.config/tyr/config.json` (overridable via `TYR_
 | `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 |
+| `conversationContext` | boolean | `false` | Give LLM providers recent conversation context to judge intent (can allow commands beyond configured patterns) |
 | `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.
-
-### Providers
+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.
 
-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.
+## Providers
 
-Configure the pipeline via the `providers` array. **Order matters** — providers run left to right.
+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.
 
-Valid provider names: `cache`, `chained-commands`, `claude`, `openrouter`.
+Configure the pipeline via the `providers` array. **Order matters** -- providers run in order.
 
-#### `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 (merged from all settings files).
+Parses compound shell commands (`&&`, `||`, `|`, `;`, subshells, command substitution) and checks each sub-command against your Claude Code allow/deny permission patterns.
 
 - **Allow:** All sub-commands match an allow pattern
-- **Deny:** Any sub-command matches a deny 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`
 
-#### `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.
 
-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.
 
-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.
+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 (installed with Claude Code). Timeouts and errors are treated as abstain.
+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.
 
-Only evaluates `Bash` tool requests; abstains on all other tools.
+### `openrouter`
 
-#### `openrouter`
+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`.
 
-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
+### Pipeline examples
 
 ```jsonc
-// Safe & fast (default) — pattern matching only
+// Safe & fast (default) -- pattern matching only
 { "providers": ["chained-commands"] }
 
-// With caching — faster repeated evaluations
+// With caching -- faster repeated evaluations
 { "providers": ["cache", "chained-commands"] }
 
-// Full pipeline — patterns first, then Claude for ambiguous 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
+### Permission prompt delay
 
-# Show more entries
-tyr log --last 50
+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.
 
-# Filter by decision type
-tyr log --decision allow
-tyr log --decision deny
+## Database management
 
-# Filter by time range (ISO or relative: 1h, 30m, 7d)
-tyr log --since 1h
-tyr log --since 2025-01-01 --until 2025-01-31
+Tyr stores all decision logs and cached results in a SQLite database at `~/.local/share/tyr/tyr.db` (overridable via `TYR_DB_PATH`).
 
-# Filter by provider or working directory
-tyr log --provider chained-commands
-tyr log --cwd /path/to/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 |
 
-# 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
-```
+`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.1.1",
+  "version": "0.2.2",
   "bin": {
     "tyr": "src/index.ts"
   },

package/src/cache.ts

@@ -26,6 +26,7 @@ export function computeConfigHash(
 		"claude.canDeny": config.claude.canDeny,
 		"openrouter.model": config.openrouter.model,
 		"openrouter.canDeny": config.openrouter.canDeny,
+		conversationContext: config.conversationContext,
 	});
 	return createHash("sha256").update(data).digest("hex");
 }

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/judge.ts

@@ -18,9 +18,12 @@ import { CacheProvider } from "../providers/cache.ts";
 import { ChainedCommandsProvider } from "../providers/chained-commands.ts";
 import { ClaudeProvider } from "../providers/claude.ts";
 import { OpenRouterProvider } from "../providers/openrouter.ts";
+import { formatTranscriptForPrompt, readTranscript } from "../transcript.ts";
 import type { HookResponse, Provider, TyrConfig } from "../types.ts";
 import { resolveProviders } from "../types.ts";
 
+const MAX_TRANSCRIPT_MESSAGES = 10;
+
 const judgeArgs = {
 	verbose: {
 		type: "boolean" as const,
@@ -77,6 +80,11 @@ const judgeArgs = {
 		type: "boolean" as const,
 		description: "Include LLM prompt and parameters in log entries",
 	},
+	"conversation-context": {
+		type: "boolean" as const,
+		description:
+			"Override conversationContext config (include transcript in LLM prompts)",
+	},
 };
 
 export default defineCommand({
@@ -224,6 +232,8 @@ export default defineCommand({
 			config.openrouter.canDeny = args["openrouter-can-deny"];
 		if (args["verbose-log"] !== undefined)
 			config.verboseLog = args["verbose-log"];
+		if (args["conversation-context"] !== undefined)
+			config.conversationContext = args["conversation-context"];
 
 		const agent = new ClaudeAgent();
 		try {
@@ -232,6 +242,21 @@ export default defineCommand({
 			if (verbose) console.error("[tyr] failed to init agent config:", err);
 		}
 
+		// Read conversation context from transcript if enabled
+		let transcriptContext: string | undefined;
+		if (config.conversationContext) {
+			const messages = await readTranscript(
+				req.transcript_path,
+				MAX_TRANSCRIPT_MESSAGES,
+			);
+			transcriptContext = formatTranscriptForPrompt(messages) || undefined;
+			if (verbose && transcriptContext) {
+				console.error(
+					`[tyr] conversation context (${messages.length} messages):\n${transcriptContext}`,
+				);
+			}
+		}
+
 		// Build provider pipeline from config
 		const providers: Provider[] = [];
 		let cacheProvider: CacheProvider | null = null;
@@ -248,11 +273,23 @@ export default defineCommand({
 					providers.push(new ChainedCommandsProvider(agent, verbose));
 					break;
 				case "claude":
-					providers.push(new ClaudeProvider(agent, config.claude, verbose));
+					providers.push(
+						new ClaudeProvider(
+							agent,
+							config.claude,
+							verbose,
+							transcriptContext,
+						),
+					);
 					break;
 				case "openrouter":
 					providers.push(
-						new OpenRouterProvider(agent, config.openrouter, verbose),
+						new OpenRouterProvider(
+							agent,
+							config.openrouter,
+							verbose,
+							transcriptContext,
+						),
 					);
 					break;
 			}
@@ -319,12 +356,22 @@ export default defineCommand({
 		if (config.verboseLog) {
 			if (result.provider === "claude") {
 				llm = {
-					prompt: buildPrompt(req, agent, config.claude.canDeny),
+					prompt: buildPrompt(
+						req,
+						agent,
+						config.claude.canDeny,
+						transcriptContext,
+					),
 					model: config.claude.model,
 				};
 			} else if (result.provider === "openrouter") {
 				llm = {
-					prompt: buildPrompt(req, agent, config.openrouter.canDeny),
+					prompt: buildPrompt(
+						req,
+						agent,
+						config.openrouter.canDeny,
+						transcriptContext,
+					),
 					model: config.openrouter.model,
 				};
 			} else {
@@ -332,14 +379,24 @@ export default defineCommand({
 				for (const name of resolveProviders(config)) {
 					if (name === "claude") {
 						llm = {
-							prompt: buildPrompt(req, agent, config.claude.canDeny),
+							prompt: buildPrompt(
+								req,
+								agent,
+								config.claude.canDeny,
+								transcriptContext,
+							),
 							model: config.claude.model,
 						};
 						break;
 					}
 					if (name === "openrouter") {
 						llm = {
-							prompt: buildPrompt(req, agent, config.openrouter.canDeny),
+							prompt: buildPrompt(
+								req,
+								agent,
+								config.openrouter.canDeny,
+								transcriptContext,
+							),
 							model: config.openrouter.model,
 						};
 						break;

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";
@@ -8,13 +9,10 @@ import {
 } from "../agents/claude.ts";
 import { rejectUnknownArgs } from "../args.ts";
 import { closeDb, getDb } from "../db.ts";
-import { readSettings, writeSettings } from "../install.ts";
+import { readSettings } from "../install.ts";
+import { getRepoRoot } from "../repo.ts";
 
 const suggestArgs = {
-	apply: {
-		type: "boolean" as const,
-		description: "Write suggestions into Claude's settings.json",
-	},
 	global: {
 		type: "boolean" as const,
 		description: "Target global (~/.claude/settings.json)",
@@ -27,9 +25,10 @@ const suggestArgs = {
 		type: "string" as const,
 		description: "Minimum approval count to suggest (default: 5)",
 	},
-	json: {
+	all: {
 		type: "boolean" as const,
-		description: "Output raw JSON",
+		description:
+			"Include commands from all projects (default: current directory)",
 	},
 };
 
@@ -44,23 +43,39 @@ export interface Suggestion {
 	rule: string;
 }
 
-/** Query frequently-allowed commands and filter out those already in allow lists. */
+/** Query frequently-allowed commands and filter out those already in allow lists.
+ *  When `cwd` is provided, only includes commands from that directory (or subdirs). */
 export function getSuggestions(
 	minCount: number,
 	allowPatterns: string[],
+	cwd?: string,
 ): Suggestion[] {
 	const db = getDb();
 
-	const rows = db
-		.query(
-			`SELECT tool_input, COUNT(*) as count
+	let query: string;
+	let params: (number | string)[];
+
+	if (cwd) {
+		const escapedCwd = cwd.replace(/[%_]/g, "\\$&");
+		query = `SELECT tool_input, COUNT(*) as count
+			 FROM logs
+			 WHERE decision = 'allow' AND mode IS NULL AND tool_name = 'Bash'
+			   AND (cwd = ? OR cwd LIKE ? || '/%' ESCAPE '\\')
+			 GROUP BY tool_input
+			 HAVING COUNT(*) >= ?
+			 ORDER BY COUNT(*) DESC`;
+		params = [cwd, escapedCwd, minCount];
+	} else {
+		query = `SELECT tool_input, COUNT(*) as count
 			 FROM logs
 			 WHERE decision = 'allow' AND mode IS NULL AND tool_name = 'Bash'
 			 GROUP BY tool_input
 			 HAVING COUNT(*) >= ?
-			 ORDER BY COUNT(*) DESC`,
-		)
-		.all(minCount) as CommandFrequency[];
+			 ORDER BY COUNT(*) DESC`;
+		params = [minCount];
+	}
+
+	const rows = db.query(query).all(...params) as CommandFrequency[];
 
 	const suggestions: Suggestion[] = [];
 	for (const row of rows) {
@@ -79,20 +94,43 @@ export function getSuggestions(
 	return suggestions;
 }
 
-/** Merge new allow rules into existing settings without clobbering. */
-export function mergeAllowRules(
-	settings: Record<string, unknown>,
-	rules: string[],
-): Record<string, unknown> {
-	const result = { ...settings };
-	const perms = (result.permissions ?? {}) as Record<string, unknown>;
-	const existing = Array.isArray(perms.allow) ? (perms.allow as string[]) : [];
+export function buildSuggestPrompt(
+	suggestions: Suggestion[],
+	targetPath: string,
+	allPaths: string[],
+): string {
+	const commandList = suggestions
+		.map((s) => `- \`${s.command}\` (approved ${s.count} times)`)
+		.join("\n");
+
+	const pathList = allPaths.map((p) => `- \`${p}\``).join("\n");
+
+	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}
 
-	const existingSet = new Set(existing);
-	const merged = [...existing, ...rules.filter((r) => !existingSet.has(r))];
+## Settings Files
 
-	result.permissions = { ...perms, allow: merged };
-	return result;
+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 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
+
+## 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 I'm ready, write the rules to the target settings file
+
+Be concise. Start by presenting your suggested rules and ask if I want to adjust them.`;
 }
 
 export default defineCommand({
@@ -118,67 +156,44 @@ export default defineCommand({
 			return;
 		}
 
-		try {
-			// Load all allow patterns from Claude settings to filter suggestions
-			const allPaths = settingsPaths(process.cwd());
-			const allowPatterns: string[] = [];
-			for (const path of allPaths) {
-				const settings = await readSettings(path);
-				const perms = settings.permissions as
-					| Record<string, unknown>
-					| undefined;
-				if (perms && Array.isArray(perms.allow)) {
-					allowPatterns.push(...extractBashPatterns(perms.allow));
-				}
-			}
-
-			const suggestions = getSuggestions(minCount, allowPatterns);
-
-			if (args.json) {
-				console.log(JSON.stringify(suggestions));
-				return;
-			}
-
-			if (suggestions.length === 0) {
-				console.log("No new suggestions found.");
-				return;
+		const repoRoot = getRepoRoot();
+		const allPaths = settingsPaths(repoRoot);
+		const allowPatterns: string[] = [];
+		for (const path of allPaths) {
+			const settings = await readSettings(path);
+			const perms = settings.permissions as Record<string, unknown> | undefined;
+			if (perms && Array.isArray(perms.allow)) {
+				allowPatterns.push(...extractBashPatterns(perms.allow));
 			}
+		}
 
-			if (!args.apply) {
-				console.log(
-					`Suggested allow rules (commands approved >= ${minCount} times):`,
-				);
-				console.log();
-				for (const s of suggestions) {
-					console.log(`  ${s.rule}  (${s.count} approvals)`);
-				}
-				console.log();
-				console.log("Run with --apply to add these rules to Claude settings.");
-				return;
-			}
+		const cwdFilter = args.all ? undefined : repoRoot;
+		const suggestions = getSuggestions(minCount, allowPatterns, cwdFilter);
+		closeDb();
 
-			// Apply mode: write rules to settings
-			const scope: "global" | "project" = args.project ? "project" : "global";
-			const configDir =
-				process.env.CLAUDE_CONFIG_DIR ?? join(homedir(), ".claude");
-			const settingsPath =
-				scope === "global"
-					? join(configDir, "settings.json")
-					: join(process.cwd(), ".claude", "settings.json");
-			const settings = await readSettings(settingsPath);
-
-			const newRules = suggestions.map((s) => s.rule);
-			const merged = mergeAllowRules(settings, newRules);
-			await writeSettings(settingsPath, merged);
-
-			console.log(
-				`Added ${newRules.length} allow rule(s) to ${scope} settings (${settingsPath}):`,
-			);
-			for (const rule of newRules) {
-				console.log(`  ${rule}`);
-			}
-		} finally {
-			closeDb();
+		if (suggestions.length === 0) {
+			console.log("No new suggestions found.");
+			return;
 		}
+
+		const scope: "global" | "project" = args.global ? "global" : "project";
+		const configDir =
+			process.env.CLAUDE_CONFIG_DIR ?? join(homedir(), ".claude");
+		const targetPath =
+			scope === "global"
+				? join(configDir, "settings.json")
+				: join(repoRoot, ".claude", "settings.json");
+
+		const existingPaths = allPaths.filter((p) => existsSync(p));
+		const prompt = buildSuggestPrompt(suggestions, targetPath, existingPaths);
+
+		const proc = Bun.spawn(["claude", prompt], {
+			stdin: "inherit",
+			stdout: "inherit",
+			stderr: "inherit",
+			env: { ...process.env, CLAUDECODE: undefined },
+		});
+
+		process.exitCode = await proc.exited;
 	},
 });

package/src/config.ts

@@ -101,6 +101,7 @@ const VALID_KEY_TYPES: Record<
 > = {
 	providers: "providers",
 	failOpen: "boolean",
+	conversationContext: "boolean",
 	verboseLog: "boolean",
 	logRetention: "string",
 	"claude.model": "string",

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/prompts.ts

@@ -3,7 +3,7 @@ import type { PermissionRequest } from "./types.ts";
 
 /** Expected shape of the LLM's JSON response. */
 export interface LlmDecision {
-	decision: "allow" | "deny";
+	decision: "allow" | "deny" | "abstain";
 	reason: string;
 }
 
@@ -12,20 +12,56 @@ export function buildPrompt(
 	req: PermissionRequest,
 	agent: ClaudeAgent,
 	canDeny: boolean,
+	conversationContext?: string,
 ): string {
 	const info = agent.getDebugInfo();
 	const command =
 		typeof req.tool_input.command === "string" ? req.tool_input.command : "";
 
-	const rules = canDeny
-		? `- If the command is a variation of one of the ALLOWED patterns → allow.
+	const fallthrough = canDeny ? "deny" : "abstain";
+
+	const conversationSection = conversationContext
+		? `\n## Recent conversation\n${conversationContext}\n`
+		: "";
+
+	let rules: string;
+	if (conversationContext) {
+		rules = `1. If the command matches a DENIED pattern → deny. No exceptions, regardless of context.
+2. If the command is a variation of an ALLOWED pattern → allow.
+3. If the command matches neither pattern, allow ONLY if ALL of these are true:
+   - The user clearly requested or implied this action in the conversation
+   - It is a typical development command (build, test, lint, search, read, install, etc.)
+   - It does not access sensitive resources (credentials, .env, auth tokens)
+   - It does not make irreversible system-wide changes
+4. Otherwise → ${fallthrough}.
+5. Only allow commands clearly within the spirit of an existing allowed pattern OR clearly supported by conversation context.`;
+	} else if (canDeny) {
+		rules = `- If the command is a variation of one of the ALLOWED patterns → allow.
 - If the command is a variation of one of the DENIED patterns → deny.
 - If the command is not clearly similar to either set of patterns → deny (fail-closed).
-- Only allow commands that are clearly within the spirit of an existing allowed pattern.`
-		: `- If the command is a variation of one of the ALLOWED patterns → allow.
+- Only allow commands that are clearly within the spirit of an existing allowed pattern.`;
+	} else {
+		rules = `- If the command is a variation of one of the ALLOWED patterns → allow.
 - If the command is NOT clearly similar to an allowed pattern → abstain.
 - Only allow commands that are clearly within the spirit of an existing allowed pattern.
 - You CANNOT deny commands. Your only options are allow or abstain.`;
+	}
+
+	const examples = conversationContext
+		? `
+
+## Examples
+- User: "run the tests" → agent runs \`pytest\` → allow (clear intent, common dev command)
+- User: "check the bundle size" → agent runs \`du -sh dist/\` → allow (clear intent, read-only)
+- User: "install the dependencies" → agent runs \`npm install\` → allow (clear intent, standard workflow)
+- User: "format the code" → agent runs \`prettier --write src/\` → allow (clear intent, common dev tool)
+- User: "check what's listening on port 3000" → agent runs \`lsof -i :3000\` → allow (clear intent, read-only)
+- User: "fix the bug" → agent runs \`curl https://example.com\` → ${fallthrough} (user didn't ask for network requests)
+- User: "deploy this" → agent runs \`rm -rf /tmp/*\` → ${fallthrough} (destructive, not clearly related)
+- Agent runs \`cat .env\` with no relevant user message → ${fallthrough} (no clear intent, sensitive file)
+- Agent runs \`ssh remote-host\` with no relevant context → ${fallthrough} (network access, no clear intent)
+- User: "clean up the build" → agent runs \`rm -rf node_modules/ dist/\` → allow (clear intent, scoped to project)`
+		: "";
 
 	const responseFormat = canDeny
 		? `{"decision": "allow", "reason": "brief explanation"}
@@ -43,7 +79,7 @@ A coding assistant is requesting permission to run a shell command. Your job is
 - Working directory: ${req.cwd}
 - Tool: ${req.tool_name}
 - Command: ${command}
-
+${conversationSection}
 ## Configured permission patterns
 - Allowed patterns: ${JSON.stringify(info.allow)}
 - Denied patterns: ${JSON.stringify(info.deny)}
@@ -51,7 +87,7 @@ A coding assistant is requesting permission to run a shell command. Your job is
 The command did not exactly match any pattern, so you must judge by similarity.
 
 ## Rules
-${rules}
+${rules}${examples}
 
 Respond with ONLY a JSON object in this exact format, no other text:
 ${responseFormat}`;
@@ -71,7 +107,9 @@ export function parseLlmResponse(stdout: string): LlmDecision | null {
 	try {
 		const parsed = JSON.parse(jsonStr) as Record<string, unknown>;
 		if (
-			(parsed.decision === "allow" || parsed.decision === "deny") &&
+			(parsed.decision === "allow" ||
+				parsed.decision === "deny" ||
+				parsed.decision === "abstain") &&
 			typeof parsed.reason === "string"
 		) {
 			return { decision: parsed.decision, reason: parsed.reason };

package/src/providers/claude.ts

@@ -20,14 +20,18 @@ export class ClaudeProvider implements Provider {
 	private model: string;
 	private canDeny: boolean;
 
+	private conversationContext?: string;
+
 	constructor(
 		private agent: ClaudeAgent,
 		config: ClaudeConfig,
 		private verbose: boolean = false,
+		conversationContext?: string,
 	) {
 		this.model = config.model;
 		this.timeoutMs = config.timeout * S_TO_MS;
 		this.canDeny = config.canDeny;
+		this.conversationContext = conversationContext;
 	}
 
 	async checkPermission(req: PermissionRequest): Promise<ProviderResult> {
@@ -37,7 +41,12 @@ export class ClaudeProvider implements Provider {
 		if (typeof command !== "string" || command.trim() === "")
 			return { decision: "abstain" };
 
-		const prompt = buildPrompt(req, this.agent, this.canDeny);
+		const prompt = buildPrompt(
+			req,
+			this.agent,
+			this.canDeny,
+			this.conversationContext,
+		);
 
 		// Clear CLAUDECODE env var so claude -p doesn't refuse to run
 		// inside a Claude Code session (tyr is invoked as a hook).
@@ -110,6 +119,10 @@ export class ClaudeProvider implements Provider {
 		const llmDecision = parseLlmResponse(result.stdout);
 		if (!llmDecision) return { decision: "abstain" };
 
+		if (llmDecision.decision === "abstain") {
+			return { decision: "abstain", reason: llmDecision.reason };
+		}
+
 		// When canDeny is false, convert deny→abstain so the user gets prompted
 		if (!this.canDeny && llmDecision.decision === "deny") {
 			return { decision: "abstain", reason: llmDecision.reason };

package/src/providers/openrouter.ts

@@ -19,15 +19,19 @@ export class OpenRouterProvider implements Provider {
 	private endpoint: string;
 	private canDeny: boolean;
 
+	private conversationContext?: string;
+
 	constructor(
 		private agent: ClaudeAgent,
 		config: OpenRouterConfig,
 		private verbose: boolean = false,
+		conversationContext?: string,
 	) {
 		this.model = config.model;
 		this.timeoutMs = config.timeout * S_TO_MS;
 		this.canDeny = config.canDeny;
 		this.endpoint = config.endpoint;
+		this.conversationContext = conversationContext;
 	}
 
 	async checkPermission(req: PermissionRequest): Promise<ProviderResult> {
@@ -45,7 +49,12 @@ export class OpenRouterProvider implements Provider {
 			return { decision: "abstain" };
 		}
 
-		const prompt = buildPrompt(req, this.agent, this.canDeny);
+		const prompt = buildPrompt(
+			req,
+			this.agent,
+			this.canDeny,
+			this.conversationContext,
+		);
 		const url = `${this.endpoint}/chat/completions`;
 
 		const controller = new AbortController();
@@ -102,6 +111,10 @@ export class OpenRouterProvider implements Provider {
 		const llmDecision = parseLlmResponse(responseText);
 		if (!llmDecision) return { decision: "abstain" };
 
+		if (llmDecision.decision === "abstain") {
+			return { decision: "abstain", reason: llmDecision.reason };
+		}
+
 		// When canDeny is false, convert deny→abstain so the user gets prompted
 		if (!this.canDeny && llmDecision.decision === "deny") {
 			return { decision: "abstain", reason: llmDecision.reason };

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();
+}

package/src/transcript.ts

@@ -0,0 +1,97 @@
+import { readFile } from "node:fs/promises";
+
+export interface TranscriptMessage {
+	role: "user" | "assistant";
+	content: string;
+}
+
+/** Content block within an assistant message. */
+interface ContentBlock {
+	type: string;
+	text?: string;
+}
+
+/** Shape of a single JSONL line in the transcript file. */
+interface TranscriptLine {
+	type: string;
+	isSidechain?: boolean;
+	isMeta?: boolean;
+	message?: {
+		role?: string;
+		content?: string | ContentBlock[];
+	};
+}
+
+/** Read the last N conversation messages from a Claude transcript JSONL file.
+ *  Returns an empty array on any error (graceful degradation). */
+export async function readTranscript(
+	path: string,
+	maxMessages: number,
+): Promise<TranscriptMessage[]> {
+	let text: string;
+	try {
+		text = await readFile(path, "utf-8");
+	} catch {
+		return [];
+	}
+
+	const messages: TranscriptMessage[] = [];
+
+	for (const line of text.split("\n")) {
+		const trimmed = line.trim();
+		if (!trimmed) continue;
+
+		let entry: TranscriptLine;
+		try {
+			entry = JSON.parse(trimmed) as TranscriptLine;
+		} catch {
+			continue;
+		}
+
+		// Skip non-conversation entries
+		if (entry.type !== "user" && entry.type !== "assistant") continue;
+		if (entry.isSidechain || entry.isMeta) continue;
+		if (!entry.message) continue;
+
+		if (entry.type === "user") {
+			if (typeof entry.message.content !== "string") continue;
+			messages.push({ role: "user", content: entry.message.content });
+		} else {
+			// Assistant: extract text content blocks
+			const content = entry.message.content;
+			if (!Array.isArray(content)) continue;
+			const textParts = content
+				.filter(
+					(block): block is ContentBlock & { text: string } =>
+						block.type === "text" && typeof block.text === "string",
+				)
+				.map((block) => block.text);
+			if (textParts.length === 0) continue;
+			messages.push({ role: "assistant", content: textParts.join("\n") });
+		}
+	}
+
+	return messages.slice(-maxMessages);
+}
+
+const DEFAULT_MAX_CHARS = 500;
+
+/** Format transcript messages for inclusion in an LLM prompt.
+ *  Each message is truncated to maxCharsPerMessage characters.
+ *  Returns an empty string if there are no messages. */
+export function formatTranscriptForPrompt(
+	messages: TranscriptMessage[],
+	maxCharsPerMessage: number = DEFAULT_MAX_CHARS,
+): string {
+	if (messages.length === 0) return "";
+
+	const lines = messages.map((msg) => {
+		const truncated =
+			msg.content.length > maxCharsPerMessage
+				? `${msg.content.slice(0, maxCharsPerMessage)}...`
+				: msg.content;
+		return `[${msg.role}]: ${truncated}`;
+	});
+
+	return lines.join("\n");
+}

package/src/types.ts

@@ -87,6 +87,8 @@ export const TyrConfigSchema = z.object({
 	claude: ClaudeConfigSchema.default(ClaudeConfigSchema.parse({})),
 	/** OpenRouter API provider configuration. */
 	openrouter: OpenRouterConfigSchema.default(OpenRouterConfigSchema.parse({})),
+	/** Include recent conversation messages in LLM judge prompts for better context. */
+	conversationContext: z.boolean().default(false),
 	/** Include LLM prompt and parameters in log entries for debugging. */
 	verboseLog: z.boolean().default(false),
 	/** Maximum age of log entries. Entries older than this are pruned on the next tyr invocation.