@towles/tool

Towles Tool

Personal CLI toolkit with auto-claude pipeline and developer utilities.

Installation

Claude Code Plugin

claude plugin marketplace add ChrisTowles/towles-tool
claude plugin install tt@towles-tool
claude plugin update tt@towles-tool

Global Install

bun install -g towles-tool

From Source

git clone https://github.com/ChrisTowles/towles-tool.git
cd towles-tool
bun install
bun link

CLI Commands

Auto-Claude (issue-to-PR pipeline)

A fully autonomous issue-to-PR pipeline — what a more productizable version of the ralph planning/execution loop looks like. Cloud-based agents (GitHub Copilot, Anthropic agents) can create PRs but can't run your full stack — Docker, Postgres, Playwright, Chrome DevTools MCP, etc. Running locally gives Claude access to the complete environment to run, test, and iterate.

Label issues with auto-claude, start the loop, and walk away. Queue up multiple issues during the day and let them run overnight, or tag an issue from your phone or the Claude mobile app and have it waiting as a PR by morning.

Inspired by Boris Tane's workflow and Francisco Hermida's auto-pr.

tt auto-claude --issue 42                # Process specific issue
tt auto-claude --issue 42 --until plan   # Stop after planning step
tt auto-claude --refresh --issue 42      # Rebase stale PR branch
tt auto-claude --reset 42               # Reset state for an issue
tt auto-claude --loop                    # Start polling loop

Slot-based workflow: Run auto-claude in a dedicated clone of the repo — not the one you're actively editing. Keep 3-5 clones (e.g. slot-1, slot-2, slot-primary) so each issue gets its own isolated environment. slot-primary is typically the one open in VS Code for manual work; the numbered slots run auto-claude independently. Each slot has its own .env so services and ports don't collide between slots. Claude Code's worktree feature may replace this approach in the future, but full repo clones have been more reliable in practice.

Pipeline Steps

Step	What it does	Artifact produced
research	Deep-reads the codebase for context relevant to the issue	research.md
plan	High-level technical plan with architectural decisions and alternatives	plan.md
plan-annotations	(optional) Addresses reviewer feedback if plan-annotations.md exists	updates plan.md
plan-implementation	Breaks plan into an ordered checkbox task list	plan-implementation.md
implement	Executes tasks one-by-one, checking boxes and committing as it goes (loops up to 100 iterations)	completed-summary.md
review	Self-reviews the diff, fixes issues, rates confidence	review.md
create-pr	Pushes branch and opens a PR with artifact links and review summary	GitHub PR
remove-label	Removes the auto-claude label so the issue isn't picked up again	—

All artifacts are written to .auto-claude/issue-{N}/. Use --until <step> to pause after any step (e.g. --until plan to review before implementation). The plan-annotations step lets you drop feedback into plan-annotations.md and re-run — the pipeline will revise the plan before continuing.

How it works under the hood

• Auto-detects repo (gh repo view) and main branch (git symbolic-ref) from cwd — no config file needed
• Creates a branch auto-claude/issue-{N} from main
• Runs Claude Code CLI (claude -p) in print mode with JSON output for each step, using prompt templates with token replacement ({{ISSUE_DIR}}, {{SCOPE_PATH}}, {{MAIN_BRANCH}})
• Artifacts drive state — each step checks if its output file exists before running (idempotent). Resume after a crash by re-running the same command
• Returns to main after each issue completes or fails

Code layout

src/commands/auto-claude.ts          # oclif command (alias: ac)
src/lib/auto-claude/
  config.ts                          # Zod schema, initConfig(), getConfig()
  utils.ts                           # exec helpers, runClaude, templates, IssueContext
  pipeline.ts                        # step orchestration
  steps/                             # one file per pipeline step
  prompt-templates/                  # 7 .md prompt files with {{TOKEN}} placeholders

Observability

Command	Description
tt graph	Token Usage (auto-opens)
tt graph --session <id>	Single session
tt graph --days 14	Filter to last N days

Git

Command	Description
tt gh branch	Create branch from GitHub issue
tt gh pr	Create pull request
tt gh branch-clean	Delete merged branches

Journaling

Command	Alias	Description
tt journal daily-notes	tt today	Weekly/daily
tt journal meeting	tt m	Meeting notes
tt journal note	tt n	General notes

Utilities

Command	Description
tt config	Show configuration
tt doctor	Check dependencies
tt install	Configure Claude Code settings

Claude Code Skills

Skill	Description
/tt:plan	Create implementation plan
/tt:improve	Suggest codebase improvements
/tt:refactor-claude-md	Fix grammar/spelling
/tt:refine	Fix grammar/spelling

Guidelines

• Architecture - CLI structure, plugin system, tech stack
• CICD via GitHub Actions - Automated release workflow
• Testing - Info about Tests

License

MIT © Chris Towles