# Auto Rename

> Mission

- Skill: `pamacea/auto-rename` (Agent Skill)
- Install (CLI): `npx skillmds@latest add pamacea/auto-rename`
- Raw SKILL.md: https://api.skillmd.com/api/skills/pamacea/auto-rename/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: Pamacea (https://skillmd.com/u/pamacea)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/pamacea/auto-rename

---


## Mission

Automatically rename Claude Code sessions with intelligent, context-aware names generated by AI analysis.

---

## Usage Guidelines

### Automatic Activation

The skill runs automatically on three key hooks:

| Hook | When it Triggers | What it Does |
|------|-----------------|--------------|
| **SessionStart** | When a session begins | Sets initial name from first meaningful message |
| **PostToolUse** | After code operations (Write, Bash, git) | Updates name based on work performed |
| **UserPromptSubmit** | After significant conversation | Refines name as session evolves |

### Smart Filtering

The system intelligently avoids unnecessary renames by:

- **Skipping command/skill invocations**: Only processes genuine user requests
- **Filtering system messages**: Ignores <command->, <objective>, <process> artifacts
- **Rate limiting**: Maximum 10 automatic renames prevents spam
- **Quality threshold**: Only renames when meaningful improvement detected

### Manual Override

```bash
# Automatic (runs on hooks - no action needed)
# The system handles everything automatically

# Manual override when you want custom names
/rename "Build JWT authentication system"

# Auto-generated examples (for reference)
"Fix: login bug"
"Add: user CRUD API"
"Refactor: auth system"
"Debug: memory leak"
```

---

## Core Workflow

1. **Input**: Hook trigger (SessionStart, PostToolUse, UserPromptSubmit)
2. **Process**:
   - Intelligently skip command/skill invocations (system-generated messages)
   - Analyze session context (first real user message, recent tools, project)
   - Generate concise name following "Action: Context" format
   - Update session .jsonl file with system message
3. **Output**: Session renamed and visible in history/resume

---

## Key Principles

- **Automatic operation**: Runs in background without manual intervention
- **Intelligent naming**: LLM analysis understands session context
- **Command artifact filtering**: Skips <command->, <objective>, <process> tags from skills
- **Dynamic updates**: Name evolves as session progresses
- **Manual override**: `/rename` command available for custom names
- **User control**: Always respects manual naming preferences

---

## Name Format

### Pattern: `Action: Context`

| Action Prefix | Usage | Example |
|---------------|-------|---------|
| **Fix** | Bug fixes | `Fix: login bug` |
| **Add** | New features | `Add: user CRUD API` |
| **Update** | Modifications | `Update: database schema` |
| **Delete** | Removals | `Delete: deprecated code` |
| **Refactor** | Restructuring | `Refactor: auth system` |
| **Debug** | Investigation | `Debug: memory leak` |
| **Test** | Testing | `Test: payment flow` |
| **Docs** | Documentation | `Docs: API README` |
| **Config** | Configuration | `Config: env variables` |

---

## Integration

- **SessionStart hook**: Analyzes first message, sets initial name
- **PostToolUse hook**: Renames after Write/Bash/git operations
- **UserPromptSubmit hook**: Updates based on conversation evolution
- **Manual command**: `/rename` for custom or auto-generated names
- **Storage**: System messages in .jsonl session files

---

## Configuration

- **maxSessionNameLength**: 50 characters (default)
- **maxRenamesPerSession**: 10 automatic renames (default)
- **renameTriggers**: Control which hooks activate (sessionStart, postToolUse, userPromptSubmit)
- **Config file**: `config/settings.json`

---

## Error Handling

- **Insufficient content**: Falls back to "Working on code"
- **LLM failure**: Generic name, retry on next trigger
- **Network issues**: Graceful degradation to defaults
- **File permissions**: Report error, skip rename
- **Max renames reached**: Stop automatic renaming, manual still available

---

## Design Principles

| Principle | Implementation | Benefit |
|-----------|----------------|---------|
| **Rate Limiting** | Maximum 10 automatic renames per session | Prevents spam, maintains focus |
| **Smart Filtering** | Filters out <command->, <objective>, <process> tags | Clean, meaningful names |
| **Specific Naming** | Uses "Action: Context" format with clear prefixes | Instant session understanding |
| **Non-Intrusive Operation** | Skips system-generated and skill execution messages | No distraction during work |
| **Contextual Evolution** | Updates name based on conversation progress | Names stay relevant |
| **User Sovereignty** | Manual /rename command always available | Full control when needed |

---

*Auto-generated from plugin.json - Last sync: 2025-01-22*