@towles/tool 0.0.20 → 0.0.48

package/{LICENSE.md → LICENSE}

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2025-PRESENT Chris Towles<https://github.com/ChrisTowles>
+Copyright (c) 2026 Chris Towles
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -1,116 +1,117 @@
 # Towles Tool
 
-[![npm version][npm-version-src]][npm-version-href]
-[![npm downloads][npm-downloads-src]][npm-downloads-href]
-[![bundle][bundle-src]][bundle-href]
-[![JSDocs][jsdocs-src]][jsdocs-href]
-[![License][license-src]][license-href]
+CLI tool with autonomous task runner and quality-of-life commands for daily development.
 
-One off quality of life scripts that I use on a daily basis.
+## Features
 
-## Journal Type System
+- **Ralph** - Autonomous task runner with session forking and context reuse
+- **Observability** - Token usage visualization with interactive treemaps
+- **Git workflows** - Branch creation, PR generation, and cleanup
+- **Journaling** - Daily notes, meeting notes, and general notes
+- **Claude Code plugins** - Personal plugin marketplace for Claude Code integration
 
-The journal system supports three types of files with different templates and organization:
+## Installation
 
-### Daily Notes (`journal daily-notes`)
-- **Purpose**: Weekly files with daily sections for ongoing work and notes
-- **File structure**: `YYYY/daily-notes/YYYY-MM-DD-week-log.md` (Monday's date)
-- **Template**: Includes sections for Monday through Friday with date headers
-- **Use case**: Regular daily journaling, work logs, scratch pad for notes
+### Claude Code Plugin
 
-### Meeting Files (`journal meeting [title]`)
-- **Purpose**: Structured meeting notes with agenda and action items
-- **File structure**: `YYYY/meetings/YYYY-MM-DD-HHMM-meeting-[title].md`
-- **Template**: Includes Date, Time, Attendees, Agenda, Notes, Action Items, and Follow-up sections
-- **Use case**: Meeting preparation, note-taking, and action item tracking
+```bash
+claude plugin marketplace add ChrisTowles/towles-tool
+claude plugin install tt@towles-tool
+```
 
-### Note Files (`journal note [title]`)
-- **Purpose**: General-purpose notes with structured sections
-- **File structure**: `YYYY/notes/YYYY-MM-DD-HHMM-note-[title].md`
-- **Template**: Includes Summary, Details, and References sections
-- **Use case**: Research notes, documentation, general information capture
+### From Source
 
-### Commands
-- `journal` or `journal daily-notes` - Create/open current week's daily notes
-- `journal meeting [title]` - Create a new meeting file with optional title
-- `journal note [title]` - Create a new note file with optional title
+```bash
+git clone https://github.com/ChrisTowles/towles-tool.git
+cd towles-tool
+pnpm install
+pnpm start  # Run directly with tsx
+```
 
-## Tools to add
-- [x] Journal system - creates and opens markdown files with templates for daily-notes, meetings, and notes
-- [ ] use claude code to generate git commits with multiple options for the commit message.
+## CLI Commands
 
-## Install from repository
+### Ralph (autonomous runner)
 
-```bash
-pnpm add --global @towles/tool
+| Command                     | Description                                   |
+| --------------------------- | --------------------------------------------- |
+| `tt ralph plan add <desc>`  | Add task to plan                              |
+| `tt ralph plan list`        | View tasks                                    |
+| `tt ralph plan done <id>`   | Mark task complete                            |
+| `tt ralph plan remove <id>` | Remove task                                   |
+| `tt ralph run`              | Run autonomous loop (auto-commits by default) |
+| `tt ralph show`             | Show plan with mermaid graph                  |
 
-## followed by
-tt
+### Observability
 
-# or
-towles-tool
-```
+| Command                   | Description                           |
+| ------------------------- | ------------------------------------- |
+| `tt graph`                | Generate HTML treemap of all sessions |
+| `tt graph --session <id>` | Single session treemap                |
+| `tt graph --open`         | Auto-open in browser                  |
 
-## Unisntall
+Treemap colors indicate input/output token ratio: green <2:1, yellow 2-5:1, red >5:1.
 
-```bash
-pnpm remove --global @towles/tool
-```
+### Git
 
-## If command not found
+| Command              | Alias   | Description                     |
+| -------------------- | ------- | ------------------------------- |
+| `tt gh branch`       |         | Create branch from GitHub issue |
+| `tt gh pr`           | `tt pr` | Create pull request             |
+| `tt gh branch-clean` |         | Delete merged branches          |
 
-try running with pnpm
-```bash
-pnpm tt
-```
+### Journaling
+
+| Command                  | Alias      | Description                      |
+| ------------------------ | ---------- | -------------------------------- |
+| `tt journal daily-notes` | `tt today` | Weekly files with daily sections |
+| `tt journal meeting`     | `tt m`     | Meeting notes                    |
+| `tt journal note`        | `tt n`     | General notes                    |
 
-if that works, then you need to add the pnpm global bin directory to your PATH.
-
-## packages to consider
-- [@anthropic-ai/claude-code](https://github.com/anthropic-ai/claude-code) - A library for interacting with the Claude code
-- [zod](https://github.com/colinhacks/zod) - TypeScript-first schema validation
-- [Consola](https://github.com/unjs/consola) console wrapper and colors
-- ~~[c12](https://github.com/unjs/c12) configuration loader and utilities~~
-    - referted stayed to json config
-- [rolldown-vite](https://voidzero.dev/posts/announcing-rolldown-vite) - A Vite plugin for rolling down your code
-- ~~[zx](https://github.com/google/zx) google created library to write shell scripts in a more powerful and expressive way via the Anthropic API.~~
-- [prompts](https://github.com/terkelg/prompts) - A library for creating beautiful command-line prompts, with fuzzy search and other features.
-  - had to patch it so `esc` cancels the selection with [pnpm-patch-i](https://github.com/antfu/pnpm-patch-i)
-- [yargs](https://github.com/yargs/yargs) - A modern, feature-rich command-line argument parser with enhanced error handling, TypeScript support, and flexible command configuration.
-- ~~[ink](https://github.com/vadimdemedes/ink) - React for interactive command-line apps~~
-    - wanted hotkey support and more complex UI but this was overkill for this project.
-- [publint](https://publint.dev/)
-- [e18e.dev](https://e18e.dev/guide/resources.html)
-
-## Document verbose and debug options
+### Utilities
+
+| Command      | Alias    | Description                    |
+| ------------ | -------- | ------------------------------ |
+| `tt config`  | `tt cfg` | Show configuration             |
+| `tt doctor`  |          | Check dependencies             |
+| `tt install` |          | Configure Claude Code settings |
+
+## Claude Code Plugin Skills
+
+Available via `/tt:<command>`:
+
+| Command       | Description                                   |
+| ------------- | --------------------------------------------- |
+| `/tt:commit`  | AI-powered conventional commit messages       |
+| `/tt:plan`    | Interview user and create implementation plan |
+| `/tt:improve` | Explore codebase and suggest improvements     |
+| `/tt:refine`  | Fix grammar/spelling in files                 |
+
+## Development
 
 ```bash
-export DEBUG=1
+pnpm start              # Run CLI with tsx
+pnpm test               # Run tests
+pnpm lint               # Run oxlint
+pnpm format             # Format with oxfmt
+pnpm typecheck          # Type check
 ```
 
-TODO add verbose option.
+### Releasing
 
-## Development
+```bash
+gh workflow run release.yml -f bump_type=patch  # or minor/major
+gh run watch
+```
 
-For information on how releases are managed, see the [Release Process](docs/release-process.md) documentation.
+## Resources
 
-## History
+### Claude Code Plugin Development
 
-I'm using a lot of inspiration from [Anthony Fu](https://github.com/antfu) for this projects codebase.
+- [Claude Code Plugins Announcement](https://www.anthropic.com/news/claude-code-plugins)
+- [Official Claude Code Plugins](https://github.com/anthropics/claude-code/tree/main/plugins)
+- [Skills Guide](https://docs.claude.com/en/api/skills-guide)
+- [Best Practices](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices)
 
 ## License
 
 [MIT](./LICENSE) License © [Chris Towles](https://github.com/ChrisTowles)
-
-<!-- Badges -->
-
-[npm-version-src]: https://img.shields.io/npm/v/@towles/tool?style=flat&colorA=080f12&colorB=1fa669
-[npm-version-href]: https://npmjs.com/package/@towles/tool
-[npm-downloads-src]: https://img.shields.io/npm/dm/@towles/tool?style=flat&colorA=080f12&colorB=1fa669
-[npm-downloads-href]: https://npmjs.com/package/@towles/tool
-[bundle-src]: https://img.shields.io/bundlephobia/minzip/@towles/tool?style=flat&colorA=080f12&colorB=1fa669&label=minzip
-[bundle-href]: https://bundlephobia.com/result?p=@towles/tool
-[license-src]: https://img.shields.io/github/license/ChrisTowles/towles-tool.svg?style=flat&colorA=080f12&colorB=1fa669
-[license-href]: https://github.com/ChrisTowles/towles-tool/blob/main/LICENSE.md
-[jsdocs-src]: https://img.shields.io/badge/jsdocs-reference-080f12?style=flat&colorA=080f12&colorB=1fa669
-[jsdocs-href]: https://www.jsdocs.io/package/@towles/tool

package/bin/run.ts

@@ -0,0 +1,5 @@
+#!/usr/bin/env tsx
+
+import { execute } from "@oclif/core";
+
+await execute({ dir: import.meta.url });

package/package.json

@@ -1,91 +1,111 @@
 {
   "name": "@towles/tool",
-  "type": "module",
-  "version": "0.0.20",
-  "description": "One off quality of life scripts that I use on a daily basis.",
-  "author": "Chris Towles <Chris.Towles.Dev@gmail.com>",
-  "license": "MIT",
-  "funding": {
-    "url": "https://github.com/sponsors/ChrisTowles"
-  },
+  "version": "0.0.48",
+  "description": "CLI tool with autonomous task runner (ralph), observability, and quality-of-life commands for daily development.",
+  "keywords": [
+    "autonomic",
+    "claude",
+    "cli",
+    "git",
+    "journal",
+    "oclif",
+    "ralph"
+  ],
   "homepage": "https://github.com/ChrisTowles/towles-tool#readme",
+  "bugs": {
+    "url": "https://github.com/ChrisTowles/towles-tool/issues"
+  },
+  "license": "MIT",
+  "author": "Chris Towles <Chris.Towles.Dev@gmail.com>",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/ChrisTowles/towles-tool.git"
   },
-  "bugs": {
-    "url": "https://github.com/ChrisTowles/towles-tool/issues"
-  },
-  "keywords": [],
-  "sideEffects": false,
-  "exports": {
-    ".": "./dist/index.mjs",
-    "./package.json": "./package.json"
+  "funding": {
+    "url": "https://github.com/sponsors/ChrisTowles"
   },
-  "main": "./dist/index.mjs",
-  "module": "./dist/index.mjs",
-  "types": "./dist/index.d.mts",
   "bin": {
-    "towles-tool": "./dist/index.mjs",
-    "tt": "./dist/index.mjs"
+    "towles-tool": "./bin/run.ts",
+    "tt": "./bin/run.ts"
   },
   "files": [
-    "dist"
+    "bin",
+    "patches",
+    "src"
   ],
+  "type": "module",
+  "main": "bin/run.ts",
+  "scripts": {
+    "start": "tsx ./bin/run.ts",
+    "typecheck": "tsc --noEmit",
+    "lint": "oxlint",
+    "lint:fix": "oxlint --fix",
+    "format": "oxfmt --write",
+    "format:check": "oxfmt --check",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "prepare": "simple-git-hooks",
+    "version:sync": "tsx scripts/sync-versions.ts"
+  },
   "dependencies": {
-    "@anthropic-ai/claude-code": "^1.0.51",
-    "@anthropic-ai/sdk": "^0.56.0",
-    "@clack/prompts": "^0.11.0",
-    "comment-json": "^4.2.5",
+    "@oclif/core": "^4.3.16",
     "consola": "^3.4.2",
+    "d3-hierarchy": "^3.1.2",
     "fzf": "^0.5.2",
-    "luxon": "^3.7.1",
-    "neverthrow": "^8.2.0",
+    "globby": "^14.1.0",
+    "luxon": "^3.5.0",
+    "open": "^10.1.1",
+    "picocolors": "^1.1.1",
     "prompts": "^2.4.2",
-    "strip-ansi": "^7.1.0",
-    "tinyexec": "^0.3.2",
-    "yargs": "^17.7.2",
-    "zod": "^4.0.5"
+    "strip-ansi": "^7.1.2",
+    "tinyexec": "^1.0.2",
+    "zod": "^3.25.67"
   },
   "devDependencies": {
-    "@antfu/ni": "^25.0.0",
-    "@types/luxon": "^3.6.2",
-    "@types/node": "^22.16.3",
+    "@oclif/test": "^4.1.13",
+    "@total-typescript/tsconfig": "^1.0.4",
+    "@tsconfig/strictest": "^2.0.5",
+    "@types/d3-hierarchy": "^3.1.7",
+    "@types/luxon": "^3.4.2",
+    "@types/node": "^22.10.10",
     "@types/prompts": "^2.4.9",
-    "@types/yargs": "^17.0.32",
-    "bumpp": "^10.2.0",
-    "lint-staged": "^15.5.2",
-    "oxlint": "^1.7.0",
-    "simple-git-hooks": "^2.13.0",
-    "tsx": "^4.20.3",
+    "bumpp": "^10.4.0",
+    "lint-staged": "^15.5.1",
+    "oxfmt": "^0.24.0",
+    "oxlint": "^1.2.0",
+    "simple-git-hooks": "^2.11.1",
+    "tsx": "^4.19.2",
     "typescript": "^5.8.3",
-    "unbuild": "^3.5.0",
-    "vite": "^6.3.5",
-    "vitest": "^3.2.4",
-    "vitest-package-exports": "^0.1.1",
-    "yaml": "^2.8.0"
+    "vitest": "^3.1.3"
   },
   "simple-git-hooks": {
-    "pre-commit": "pnpm i --frozen-lockfile --ignore-scripts --offline && npx lint-staged"
+    "pre-commit": "pnpm lint-staged && pnpm typecheck"
   },
   "lint-staged": {
-    "*": "oxlint --fix"
+    "package.json": "oxfmt --write",
+    "*.{ts,tsx,mts,cts,js,cjs,mjs}": [
+      "oxfmt --write",
+      "oxlint --fix"
+    ],
+    "*.{json,md,yaml,yml}": "oxfmt --write"
   },
-  "directories": {
-    "test": "test"
+  "oclif": {
+    "bin": "tt",
+    "commands": {
+      "strategy": "pattern",
+      "target": "./src/commands"
+    },
+    "dirname": "towles-tool",
+    "plugins": [],
+    "topicSeparator": " "
   },
-  "scripts": {
-    "build": "unbuild",
-    "dev": "unbuild --stub",
-    "lint": "oxlint",
-    "lint:fix": "oxlint --fix",
-    "lint:fix_all": "oxlint --fix .",
-    "lint:package": "pnpm dlx publint --fix && pnpm dlx knip",
-    "release:local": "bumpp && pnpm publish --no-git-checks -r --access public",
-    "release": "bumpp && echo \"github action will run and publish to npm\"",
-    "start": "tsx src/index.ts",
-    "test": "vitest --run",
-    "test:watch": "CI=DisableCallingClaude vitest --watch",
-    "typecheck": "tsc --noEmit"
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "packageManager": "pnpm@10.11.0",
+  "pnpm": {
+    "patchedDependencies": {
+      "prompts@2.4.2": "patches/prompts.patch"
+    }
   }
-}
+}

package/patches/prompts.patch

@@ -0,0 +1,34 @@
+# prompts patch
+#
+# Used by: src/commands/gh/branch.ts (autocomplete with fzf fuzzy filtering)
+#
+# Fix: On exit (Ctrl+C/Ctrl+D), reject the promise instead of resolving.
+# Without this, exiting a prompt resolves with undefined and code continues
+# as if user submitted empty input. This lets us catch cancellation properly.
+
+diff --git a/dist/prompts.js b/dist/prompts.js
+index 31f2648a7d215d61aff736424a6f2d66d07e3273..2b8a0ac36fd22ed17f6096ce4f52a4db95ba2633 100644
+--- a/dist/prompts.js
++++ b/dist/prompts.js
+@@ -14,7 +14,7 @@ function toPrompt(type, args, opts = {}) {
+     const onExit = opts.onExit || noop;
+     p.on('state', args.onState || noop);
+     p.on('submit', x => res(onSubmit(x)));
+-    p.on('exit', x => res(onExit(x)));
++    p.on('exit', x => rej(onExit(x)));
+     p.on('abort', x => rej(onAbort(x)));
+   });
+ }
+diff --git a/lib/prompts.js b/lib/prompts.js
+index 9f625564601da8f79040698de197a6ff2fec3859..e08923fc9f66ab0700788a62455da89ad23c5f35 100644
+--- a/lib/prompts.js
++++ b/lib/prompts.js
+@@ -11,7 +11,7 @@ function toPrompt(type, args, opts={}) {
+     const onExit = opts.onExit || noop;
+     p.on('state', args.onState || noop);
+     p.on('submit', x => res(onSubmit(x)));
+-    p.on('exit', x => res(onExit(x)));
++    p.on('exit', x => rej(onExit(x)));
+     p.on('abort', x => rej(onAbort(x)));
+   });
+ }

package/src/commands/base.ts

@@ -0,0 +1,27 @@
+import { Command, Flags } from "@oclif/core";
+import type { SettingsFile } from "../config/settings.js";
+import { loadSettings } from "../config/settings.js";
+
+/**
+ * Base command that all towles-tool commands extend.
+ * Provides shared functionality like settings loading and debug flag.
+ */
+export abstract class BaseCommand extends Command {
+  static baseFlags = {
+    debug: Flags.boolean({
+      char: "d",
+      description: "Enable debug output",
+      default: false,
+    }),
+  };
+
+  protected settings!: SettingsFile;
+
+  /**
+   * Called before run(). Loads user settings.
+   */
+  async init(): Promise<void> {
+    await super.init();
+    this.settings = await loadSettings();
+  }
+}

package/src/commands/config.test.ts

@@ -0,0 +1,15 @@
+/**
+ * Integration tests for oclif config command
+ * Note: consola outputs to stderr with different log levels
+ */
+import { describe, it, expect } from "vitest";
+import { runCommand } from "@oclif/test";
+
+describe("config command", () => {
+  it("runs config and outputs settings info", async () => {
+    const { stderr } = await runCommand(["config"]);
+    // consola.warn outputs captured in stderr
+    expect(stderr).toContain("User Config");
+    expect(stderr).toContain("Working Directory");
+  });
+});

package/src/commands/config.ts

@@ -0,0 +1,44 @@
+import consola from "consola";
+import { BaseCommand } from "./base.js";
+
+/**
+ * Display current configuration settings
+ */
+export default class Config extends BaseCommand {
+  static override description = "Display current configuration settings";
+
+  static override examples = [
+    { description: "Display configuration", command: "<%= config.bin %> <%= command.id %>" },
+    { description: "Use alias", command: "<%= config.bin %> cfg" },
+  ];
+
+  async run(): Promise<void> {
+    await this.parse(Config);
+
+    consola.info("Configuration");
+    consola.log("");
+
+    consola.info(`Settings File: ${this.settings.path}`);
+    consola.log("");
+
+    consola.warn("User Config:");
+    consola.log(
+      `  Daily Path Template: ${this.settings.settings.journalSettings.dailyPathTemplate}`,
+    );
+    consola.log(
+      `  Meeting Path Template: ${this.settings.settings.journalSettings.meetingPathTemplate}`,
+    );
+    consola.log(`  Note Path Template: ${this.settings.settings.journalSettings.notePathTemplate}`);
+    consola.log(`  Editor: ${this.settings.settings.preferredEditor}`);
+    consola.log("");
+
+    consola.warn("Working Directory:");
+    consola.log(`  ${process.cwd()}`);
+    consola.log("");
+
+    consola.info("Shell Completions:");
+    consola.log("  Run `tt completion` to generate shell completions");
+    consola.log("  Bash/Zsh: tt completion >> ~/.bashrc (or ~/.zshrc)");
+    consola.log("  Fish: tt completion > ~/.config/fish/completions/tt.fish");
+  }
+}

package/src/commands/doctor.ts

@@ -0,0 +1,136 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { x } from "tinyexec";
+import pc from "picocolors";
+import { BaseCommand } from "./base.js";
+
+interface CheckResult {
+  name: string;
+  version: string | null;
+  ok: boolean;
+  warning?: string;
+}
+
+/**
+ * Check system dependencies and environment
+ */
+export default class Doctor extends BaseCommand {
+  static override description = "Check system dependencies and environment";
+
+  static override examples = [
+    { description: "Check system dependencies", command: "<%= config.bin %> <%= command.id %>" },
+    { description: "Verify environment after setup", command: "<%= config.bin %> doctor" },
+  ];
+
+  async run(): Promise<void> {
+    await this.parse(Doctor);
+
+    this.log("Checking dependencies...\n");
+
+    const checks: CheckResult[] = await Promise.all([
+      this.checkCommand("git", ["--version"], /git version ([\d.]+)/),
+      this.checkCommand("gh", ["--version"], /gh version ([\d.]+)/),
+      this.checkCommand("node", ["--version"], /v?([\d.]+)/),
+      this.checkCommand("bun", ["--version"], /([\d.]+)/),
+    ]);
+
+    // Display results
+    for (const check of checks) {
+      const icon = check.ok ? pc.green("✓") : pc.red("✗");
+      const version = check.version ?? "not found";
+      this.log(`${icon} ${check.name}: ${version}`);
+      if (check.warning) {
+        this.log(`  ${pc.yellow("⚠")} ${check.warning}`);
+      }
+    }
+
+    // Check gh auth
+    this.log("");
+    const ghAuth = await this.checkGhAuth();
+    const authIcon = ghAuth.ok ? pc.green("✓") : pc.yellow("⚠");
+    this.log(`${authIcon} gh auth: ${ghAuth.ok ? "authenticated" : "not authenticated"}`);
+    if (!ghAuth.ok) {
+      this.log(`  ${pc.dim("Run: gh auth login")}`);
+    }
+
+    // Node version check
+    const nodeCheck = checks.find((c) => c.name === "node");
+    if (nodeCheck?.version) {
+      const major = Number.parseInt(nodeCheck.version.split(".")[0], 10);
+      if (major < 18) {
+        this.log("");
+        this.log(`${pc.yellow("⚠")} Node.js 18+ recommended (found ${nodeCheck.version})`);
+      }
+    }
+
+    // Check ralph files in .gitignore
+    this.log("");
+    const gitignoreCheck = this.checkRalphGitignore();
+    const gitignoreIcon = gitignoreCheck.ok ? pc.green("✓") : pc.yellow("⚠");
+    this.log(
+      `${gitignoreIcon} .gitignore: ${gitignoreCheck.ok ? "ralph-* excluded" : "ralph-* NOT excluded"}`,
+    );
+    if (!gitignoreCheck.ok) {
+      this.log(`  ${pc.dim('Add "ralph-*" to .gitignore to exclude local ralph state files')}`);
+    }
+
+    // Summary
+    const allOk = checks.every((c) => c.ok) && ghAuth.ok && gitignoreCheck.ok;
+    this.log("");
+    if (allOk) {
+      this.log(pc.green("All checks passed!"));
+    } else {
+      this.log(pc.yellow("Some checks failed. See above for details."));
+    }
+  }
+
+  private async checkCommand(
+    name: string,
+    args: string[],
+    versionPattern: RegExp,
+  ): Promise<CheckResult> {
+    try {
+      // tinyexec is safe - uses execFile internally, no shell injection risk
+      const result = await x(name, args);
+      const output = result.stdout + result.stderr;
+      const match = output.match(versionPattern);
+      return {
+        name,
+        version: match?.[1] ?? output.trim().slice(0, 20),
+        ok: true,
+      };
+    } catch {
+      return { name, version: null, ok: false };
+    }
+  }
+
+  private async checkGhAuth(): Promise<{ ok: boolean }> {
+    try {
+      // tinyexec is safe - uses execFile internally, no shell injection risk
+      const result = await x("gh", ["auth", "status"]);
+      return { ok: result.exitCode === 0 };
+    } catch {
+      return { ok: false };
+    }
+  }
+
+  private checkRalphGitignore(): { ok: boolean } {
+    const gitignorePath = path.join(process.cwd(), ".gitignore");
+    try {
+      if (!fs.existsSync(gitignorePath)) {
+        return { ok: false };
+      }
+      const content = fs.readFileSync(gitignorePath, "utf-8");
+      // Check for ralph-* pattern or specific ralph files
+      const hasRalphPattern = content.split("\n").some((line) => {
+        const trimmed = line.trim();
+        return (
+          trimmed === "ralph-*" || trimmed === "ralph-*.json" || trimmed === "ralph-state.json"
+        );
+      });
+      return { ok: hasRalphPattern };
+    } catch {
+      return { ok: false };
+    }
+  }
+}