@towles/tool 0.0.41 → 0.0.48

package/README.md

@@ -1,142 +1,108 @@
 # Towles Tool
 
-Collection of quality-of-life tools and Claude Code plugins for daily development workflows.
+CLI tool with autonomous task runner and quality-of-life commands for daily development.
 
-## Overview
+## Features
 
-**CLI tool** (`tt`) - Distributed as a compiled Bun executable for daily development tasks.
-
-**Claude Code Plugin Marketplace** - Hosts Claude Code plugins for personal use.
-
-The project evolved from a private toolbox of personal scripts to a compiled Bun executable and Claude Code plugin marketplace.
+- **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
 
 ## Installation
 
-### CLI Tool
-
-Download the pre-built executable for your platform from [Releases](https://github.com/ChrisTowles/towles-tool/releases), or build from source:
+### Claude Code Plugin
 
 ```bash
-# Clone and build
-git clone https://github.com/ChrisTowles/towles-tool.git
-cd towles-tool
-bun install
-bun run build
-
-# The executable is at dist/tt
-# Move it somewhere in your PATH
-mv dist/tt ~/.local/bin/tt
+claude plugin marketplace add ChrisTowles/towles-tool
+claude plugin install tt@towles-tool
 ```
 
-### Claude Code Plugins
-
-Install plugins from this marketplace:
+### From Source
 
 ```bash
-/plugins marketplace add ChrisTowles/towles-tool
-/plugin install tt@ChrisTowles/towles-tool
+git clone https://github.com/ChrisTowles/towles-tool.git
+cd towles-tool
+pnpm install
+pnpm start  # Run directly with tsx
 ```
 
-I do find myself editing `~/.claude/settings.json` a lot to directly modify settings around plugins.
+## CLI Commands
 
-### Shell Completions
+### Ralph (autonomous runner)
 
-Generate shell completions for tab completion support:
+| 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                  |
 
-```bash
-# Bash - add to ~/.bashrc
-tt completion >> ~/.bashrc
+### Observability
 
-# Zsh - add to ~/.zshrc
-tt completion >> ~/.zshrc
+| Command                   | Description                           |
+| ------------------------- | ------------------------------------- |
+| `tt graph`                | Generate HTML treemap of all sessions |
+| `tt graph --session <id>` | Single session treemap                |
+| `tt graph --open`         | Auto-open in browser                  |
 
-# Fish
-tt completion > ~/.config/fish/completions/tt.fish
-```
+Treemap colors indicate input/output token ratio: green <2:1, yellow 2-5:1, red >5:1.
 
-## Development
+### Git
 
-### Setup
+| 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          |
 
-```bash
-# Clone the repository
-git clone https://github.com/ChrisTowles/towles-tool.git
-cd towles-tool
-bun install
-```
+### Journaling
 
-### Commands
-
-```bash
-bun run start           # Run the CLI directly
-bun run build           # Build executable for current platform
-bun run build:all       # Build for all platforms (Linux, macOS, Windows)
-bun run test            # Run tests
-bun run lint            # Run linter
-bun run typecheck       # Type check
-```
+| 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                    |
 
-### Plugin Validation
+### Utilities
 
-```bash
-claude plugin validate .  # Validate Claude Code plugins before publishing
-```
+| Command      | Alias    | Description                    |
+| ------------ | -------- | ------------------------------ |
+| `tt config`  | `tt cfg` | Show configuration             |
+| `tt doctor`  |          | Check dependencies             |
+| `tt install` |          | Configure Claude Code settings |
 
-**Plugin Marketplace**: `.claude-plugin/marketplace.json`
+## Claude Code Plugin Skills
 
-- Defines available plugins for installation
+Available via `/tt:<command>`:
 
-### Releasing
+| 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                 |
 
-See [docs/releasing.md](./docs/releasing.md) for full details.
+## Development
 
 ```bash
-gh workflow run release.yml -f bump_type=patch  # or minor/major
-gh run watch  # monitor progress
+pnpm start              # Run CLI with tsx
+pnpm test               # Run tests
+pnpm lint               # Run oxlint
+pnpm format             # Format with oxfmt
+pnpm typecheck          # Type check
 ```
 
-## Reminders for me
-
-- Use plan mode!
-  - in plan mode tell claude your problems.
-  - in edit mode tell claude its problems.
-- use `/context` to see what is using context and if you need to trim anything down.
-  - Only add context Claude doesn't already have but needs
-- Always write in third person for prompts
-- use a tool to write your prompts and evaluate them.
-  - These models are smart. Less is more. don't be too verbose
-  - https://console.anthropic.com/workbench/
-- read source code from primary sources like:
-  - [anthropic repos](https://github.com/anthropics)
-- [Skills best practices](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/best-practices#core-principles)
-  - gerund form (verb + -ing) for skill names
-- [claude cookbook skills section](https://github.com/anthropics/claude-cookbooks/tree/main/skills)
-- https://github.com/anthropics/skills
-  - installed as a plugin, has examples and skill-creator
+### Releasing
 
 ```bash
-/plugin marketplace add anthropics/skills
+gh workflow run release.yml -f bump_type=patch  # or minor/major
+gh run watch
 ```
 
-## Roadmap
-
-### Planned Features
-
-**Journal Type System**:
-
-- [ ] daily-notes
-- [ ] meeting
-- [ ] note
-- [ ] task (todo)
-
-**Git Tools**:
-
-- [ ] commit-message-generator
-- [ ] pull-request-generator
-- [ ] issue-generator
-- [ ] pull-request-reviewer
-- [ ] branch-from-issue
-
 ## Resources
 
 ### Claude Code Plugin Development
@@ -146,14 +112,6 @@ gh run watch  # monitor progress
 - [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)
 
-### Project Documentation
-
-- [Node Package](./docs/node-package.md) - How the repo worked when it was a node package
-
-## History
-
-This project started as a collection of personal scripts and utilities built up over time in a private toolbox. It was initially published as an npm package, but has since evolved to be distributed as a compiled Bun executable. With the release of Claude Code Skills and plugins, the project also serves as a Claude Code plugin marketplace.
-
 ## License
 
 [MIT](./LICENSE) License © [Chris Towles](https://github.com/ChrisTowles)

package/package.json

@@ -1,7 +1,16 @@
 {
   "name": "@towles/tool",
-  "version": "0.0.41",
-  "description": "One off quality of life scripts that I use on a daily basis.",
+  "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"
@@ -25,77 +34,78 @@
     "src"
   ],
   "type": "module",
-  "publishConfig": {
-    "access": "public"
-  },
+  "main": "bin/run.ts",
   "scripts": {
-    "version:sync": "pnpm tsx scripts/sync-versions.ts",
-    "prepublishOnly": "pnpm run version:sync",
-    "start": "tsx bin/run.ts",
-    "format": "oxfmt --write .",
-    "format:check": "oxfmt --check .",
+    "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": "CI=DisableCallingClaude vitest watch",
-    "typecheck": "tsgo --noEmit --incremental",
-    "prepare": "simple-git-hooks"
+    "test:watch": "vitest watch",
+    "prepare": "simple-git-hooks",
+    "version:sync": "tsx scripts/sync-versions.ts"
   },
   "dependencies": {
-    "@anthropic-ai/claude-code": "^2.1.4",
-    "@anthropic-ai/sdk": "^0.56.0",
-    "@oclif/core": "^4.3.2",
+    "@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",
-    "zod": "^4.0.5"
+    "strip-ansi": "^7.1.2",
+    "tinyexec": "^1.0.2",
+    "zod": "^3.25.67"
   },
   "devDependencies": {
-    "@oclif/test": "^4.1.10",
+    "@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.6.2",
-    "@types/node": "^22.16.3",
+    "@types/luxon": "^3.4.2",
+    "@types/node": "^22.10.10",
     "@types/prompts": "^2.4.9",
-    "@typescript/native-preview": "^7.0.0-dev.20260111.1",
     "bumpp": "^10.4.0",
-    "lint-staged": "^15.5.2",
+    "lint-staged": "^15.5.1",
     "oxfmt": "^0.24.0",
-    "oxlint": "^1.7.0",
-    "simple-git-hooks": "^2.13.0",
-    "tsx": "^4.19.4",
+    "oxlint": "^1.2.0",
+    "simple-git-hooks": "^2.11.1",
+    "tsx": "^4.19.2",
     "typescript": "^5.8.3",
-    "vitest": "^4.0.17"
+    "vitest": "^3.1.3"
   },
   "simple-git-hooks": {
-    "pre-commit": "pnpm exec lint-staged -q && claude plugin validate ."
+    "pre-commit": "pnpm lint-staged && pnpm typecheck"
   },
   "lint-staged": {
-    "*.{js,ts,jsx,tsx,json,md}": "oxfmt --write",
-    "*": "oxlint --quiet --fix"
+    "package.json": "oxfmt --write",
+    "*.{ts,tsx,mts,cts,js,cjs,mjs}": [
+      "oxfmt --write",
+      "oxlint --fix"
+    ],
+    "*.{json,md,yaml,yml}": "oxfmt --write"
   },
   "oclif": {
     "bin": "tt",
     "commands": {
-      "identifier": "default",
-      "strategy": "explicit",
-      "target": "./src/commands/index.ts"
+      "strategy": "pattern",
+      "target": "./src/commands"
     },
     "dirname": "towles-tool",
+    "plugins": [],
     "topicSeparator": " "
   },
-  "packageManager": "pnpm@10.27.0",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "packageManager": "pnpm@10.11.0",
   "pnpm": {
     "patchedDependencies": {
       "prompts@2.4.2": "patches/prompts.patch"
     }
-  },
-  "trustedDependencies": [
-    "@anthropic-ai/claude-code"
-  ]
+  }
 }

package/src/commands/base.ts

@@ -1,5 +1,6 @@
 import { Command, Flags } from "@oclif/core";
-import { LoadedSettings, loadSettings } from "../config/settings.js";
+import type { SettingsFile } from "../config/settings.js";
+import { loadSettings } from "../config/settings.js";
 
 /**
  * Base command that all towles-tool commands extend.
@@ -14,7 +15,7 @@ export abstract class BaseCommand extends Command {
     }),
   };
 
-  protected settings!: LoadedSettings;
+  protected settings!: SettingsFile;
 
   /**
    * Called before run(). Loads user settings.
@@ -23,20 +24,4 @@ export abstract class BaseCommand extends Command {
     await super.init();
     this.settings = await loadSettings();
   }
-
-  /**
-   * Helper to log debug messages when --debug flag is set.
-   */
-  protected logDebug(message: string, ...args: unknown[]): void {
-    // Access flags via parse() - oclif guarantees flags exist after init()
-    void (this.parse as () => Promise<{ flags: { debug?: boolean } }>)()
-      .then((parsed) => {
-        if (parsed.flags?.debug) {
-          this.log(`[DEBUG] ${message}`, ...args);
-        }
-      })
-      .catch(() => {
-        /* ignore parse errors in debug logging */
-      });
-  }
 }

package/src/commands/config.ts

@@ -7,7 +7,10 @@ import { BaseCommand } from "./base.js";
 export default class Config extends BaseCommand {
   static override description = "Display current configuration settings";
 
-  static override examples = ["<%= config.bin %> <%= command.id %>", "<%= config.bin %> cfg"];
+  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);
@@ -15,20 +18,18 @@ export default class Config extends BaseCommand {
     consola.info("Configuration");
     consola.log("");
 
-    consola.info(`Settings File: ${this.settings.settingsFile.path}`);
+    consola.info(`Settings File: ${this.settings.path}`);
     consola.log("");
 
     consola.warn("User Config:");
     consola.log(
-      `  Daily Path Template: ${this.settings.settingsFile.settings.journalSettings.dailyPathTemplate}`,
+      `  Daily Path Template: ${this.settings.settings.journalSettings.dailyPathTemplate}`,
     );
     consola.log(
-      `  Meeting Path Template: ${this.settings.settingsFile.settings.journalSettings.meetingPathTemplate}`,
+      `  Meeting Path Template: ${this.settings.settings.journalSettings.meetingPathTemplate}`,
     );
-    consola.log(
-      `  Note Path Template: ${this.settings.settingsFile.settings.journalSettings.notePathTemplate}`,
-    );
-    consola.log(`  Editor: ${this.settings.settingsFile.settings.preferredEditor}`);
+    consola.log(`  Note Path Template: ${this.settings.settings.journalSettings.notePathTemplate}`);
+    consola.log(`  Editor: ${this.settings.settings.preferredEditor}`);
     consola.log("");
 
     consola.warn("Working Directory:");

package/src/commands/doctor.ts

@@ -17,7 +17,10 @@ interface CheckResult {
 export default class Doctor extends BaseCommand {
   static override description = "Check system dependencies and environment";
 
-  static override examples = ["<%= config.bin %> <%= command.id %>"];
+  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);

package/src/commands/gh/branch-clean.ts

@@ -12,10 +12,16 @@ export default class BranchClean extends BaseCommand {
   static override description = "Delete local branches that have been merged into main";
 
   static override examples = [
-    "<%= config.bin %> gh branch-clean",
-    "<%= config.bin %> gh branch-clean --dry-run",
-    "<%= config.bin %> gh branch-clean --force",
-    "<%= config.bin %> gh branch-clean --base develop",
+    { description: "Clean merged branches", command: "<%= config.bin %> <%= command.id %>" },
+    {
+      description: "Preview without deleting",
+      command: "<%= config.bin %> <%= command.id %> --dry-run",
+    },
+    { description: "Skip confirmation", command: "<%= config.bin %> <%= command.id %> --force" },
+    {
+      description: "Check against develop",
+      command: "<%= config.bin %> <%= command.id %> --base develop",
+    },
   ];
 
   static override flags = {

package/src/commands/gh/branch.ts

@@ -18,9 +18,12 @@ export default class GhBranch extends BaseCommand {
   static override description = "Create a git branch from a GitHub issue";
 
   static override examples = [
-    "<%= config.bin %> gh branch",
-    "<%= config.bin %> gh branch --assignedToMe",
-    "<%= config.bin %> gh branch -a",
+    { description: "Browse all open issues", command: "<%= config.bin %> <%= command.id %>" },
+    {
+      description: "Only issues assigned to me",
+      command: "<%= config.bin %> <%= command.id %> --assignedToMe",
+    },
+    { description: "Short flag for assigned", command: "<%= config.bin %> <%= command.id %> -a" },
   ];
 
   static override flags = {

package/src/commands/gh/pr.ts

@@ -14,14 +14,21 @@ export default class Pr extends BaseCommand {
   static override description = "Create a pull request from the current branch";
 
   static override examples = [
-    "<%= config.bin %> gh pr",
-    "<%= config.bin %> gh pr --draft",
-    "<%= config.bin %> gh pr --base develop",
+    {
+      description: "Create PR from current branch",
+      command: "<%= config.bin %> <%= command.id %>",
+    },
+    { description: "Create draft PR", command: "<%= config.bin %> <%= command.id %> --draft" },
+    {
+      description: "PR against develop branch",
+      command: "<%= config.bin %> <%= command.id %> --base develop",
+    },
   ];
 
   static override flags = {
     ...BaseCommand.baseFlags,
     draft: Flags.boolean({
+      char: "D",
       description: "Create as draft PR",
       default: false,
     }),