Plan files should have descriptive names, not random adjective-verb-noun

Resolved 💬 3 comments Opened Feb 26, 2026 by mabthew Closed Mar 28, 2026

Problem

Plan files in ~/.claude/plans/ are saved with randomly generated Docker-style names like dazzling-jumping-knuth.md, crispy-wandering-hopper.md, etc. These names have no relationship to the plan content, making the directory impossible to navigate.

When you accumulate 20+ plans, the only way to find anything is to head or grep every file. The plans themselves contain clear, descriptive titles (e.g., "# Plan: Add OAuth2 login flow") but the filenames discard that information entirely.

Why this matters

I understand that plans are designed as ephemeral session artifacts — the intended way to revisit a plan is to resume the session that created it via claude --continue or claude --resume. The filenames only need to be unique because the active session already knows the path.

But in practice, the plan files that get left behind are genuinely useful standalone documents. They contain structured context, rationale, and implementation steps — they're some of the most valuable artifacts Claude Code produces. It's frustrating that they persist on disk as well-written markdown but are essentially unfindable without grepping through every file. The tooling creates good documents and then throws away discoverability.

If plans are meant to be throwaway, they should be cleaned up. If they're meant to persist (and they do), they should be browsable.

Suggestions

  1. Descriptive filenames — Derive the filename from the plan's content, either from the # Plan: ... heading or from the session context (project name, initial prompt, etc.). Something like add-oauth2-login-flow.md or myapp-database-migration.md would make the directory immediately browsable. Even a timestamp prefix (e.g., 2026-02-26-add-oauth2-login.md) would be a significant improvement over random words.
  1. A /plans command — Similar to how /resume lets you browse and pick from past sessions, a /plans command could list saved plans with their titles, dates, and associated projects — and let you open or reference one in your current session. Right now there's no discovery mechanism at all.

Current workaround

Manually renaming files after each planning session (renaming doesn't break anything since active sessions reference plans by session ID, not filename).

View original on GitHub ↗

This issue has 3 comments on GitHub. Read the full discussion on GitHub ↗