pi-retune

One-command session renamer toggle for Pi coding agent.

Problem it solves:

• Pi sessions accumulate fast
• default names drift (“Chat 173”) and searching becomes pain
• you want good enough names, but you also want an easy undo

pi-retune is a safe toggle:

• /retune → rename (repo-scoped by default)
• /retune again → restore (only if the name is still what retune set)

If this improves your workflow, star the repo.

---

Install

Install with Pi, not npm:

pi install npm:pi-retune

Then:

/reload
/retune

---

Quickstart

• rename sessions for this repo: /retune
• undo safely: /retune again
• preview only: /retune --dry
• edit/approve the plan: /retune --review

---

Commands

• /retune
• /retune again
• /retune --help

---

Usage

Common options:

• --review edit/approve the plan before applying
• --dry preview only (no writes)
• --scope repo|cwd|all
• --limit 200
• --since 30d (or 2026-01-01)
• --template "#{moduleOrRepo} - {primaryTask|truncate:28}"
• --no-model never call a model
• --all include already-named sessions (overwrite)

---

Templates

Placeholders:

• {moduleOrRepo} {moduleName} {primaryTask} {repo} {branch} {ticket} {taskType}
• {created} {modified} {messages} {id8}

Modifiers:

• |lower |upper |title |kebab |snake |sanitize |caveman |truncate:N |default:TEXT

Escape braces:

• {{ → { and }} → }

---

Configuration

Merged global → project:

• ~/.pi/agent/retune.json
• <repo>/.pi/retune.json

Legacy names still supported:

• ~/.pi/agent/pi-retune.json
• <repo>/.pi/pi-retune.json

---

Files

• config: ~/.pi/agent/retune.json
• config (project): <repo>/.pi/retune.json

---

Troubleshooting

• No sessions matched repo scope
  • try: /retune --scope all
• You renamed a session manually, and restore didn’t happen
  • safety rule: restore only runs if the session name is still what retune set

---

Development

Local dev install:

pi install -l <path-to-pi-retune>

---

For maintainers

Release checklist:

• update CHANGELOG.md
• bump version: npm version patch
• npm publish

---

License

MIT