An AI-powered file renaming agent built with the Claude Agent SDK. It analyzes documents, classifies them, and applies consistent naming patterns that are learned and remembered over time.

• Document Analysis: Reads PDFs, images, and text files to understand content
• Smart Classification: Identifies document types (receipts, bills, tax documents, bank statements, etc.)
• Pattern-Based Naming: Uses customizable templates with tokens like {Date}, {Merchant}, {Amount}
• Pattern Learning: Saves patterns for future use when processing similar documents
• Batch Processing: Process multiple files at once with consistent naming
• History Tracking: Keeps track of all renames for reference

curl -fsSL https://raw.githubusercontent.com/omarshahine/claude-rename-agent/main/install.sh | bash

Or install via pip:

pip install claude-rename-agent

Add the rename skill to Claude Code and just ask Claude to rename your files. The skill will check if rename-agent is installed and help you set it up if needed.

Copy the skill to your Claude Code skills directory:

# Create the skills directory if it doesn't exist
mkdir -p ~/.claude/skills

# Copy the rename-agent skill
cp -r .claude/skills/rename-agent ~/.claude/skills/

Or download directly:

mkdir -p ~/.claude/skills/rename-agent
curl -fsSL https://raw.githubusercontent.com/omarshahine/claude-rename-agent/main/.claude/skills/rename-agent/SKILL.md \
  -o ~/.claude/skills/rename-agent/SKILL.md

Once the skill is added, you can use it in two ways:

Slash command - Type /rename-agent to explicitly invoke the skill:

> /rename-agent
> /rename-agent ~/Downloads/tax-forms

Natural language - Just describe what you want to rename. Claude will automatically detect when to use the skill based on your request:

> Rename these tax documents in ~/Downloads/tax-forms
> Organize my receipts in ~/Documents/Receipts with date and merchant
> Batch rename PDFs in /path/to/folder using pattern {Date} - {Title}

The skill will check if rename-agent is installed and help you set it up if needed.

• Python 3.10+
• Claude Code - Install Claude Code first
• Anthropic API Key - Set ANTHROPIC_API_KEY environment variable

rename-agent

This starts an interactive session where you can describe what you want to rename.

rename-agent "Rename these 1099 tax forms for 2024" --files /path/to/forms

rename-agent --files /path/to/documents

rename-agent --files /path/to/receipts --pattern "{Date:YYYY-MM-DD} - {Merchant} - {Amount}"

rename-agent --files /path/to/docs --dry-run

rename-agent stats

rename-agent history

rename-agent patterns

rename-agent types

rename-agent preview /path/to/folder --ext ".pdf,.jpg" --recursive

Use these tokens in your naming patterns:

The agent recognizes these document types:

• Receipt - Purchase receipts, order confirmations
• Bill - Utility bills, service statements
• Tax Document - W-2, 1099, K-1, tax returns
• Bank Statement - Account statements
• Invoice - Business invoices
• Contract - Legal agreements
• Medical - Medical records, EOBs
• Insurance - Policies, claims
• Investment - Brokerage statements
• Payslip - Pay stubs
• Identity - IDs, passports, licenses
• Correspondence - Letters, notices
• Manual - Product manuals
• Photo - Images, screenshots
• General - Other documents

Patterns and history are stored in ~/.rename-agent/ by default:

• patterns.json - Learned naming patterns
• history.json - Rename history

Use --data-dir to specify a custom location.

rename-agent "Rename all 1099 forms using the pattern {Year} - 1099 - {Institution}" \
  --files ~/Documents/Tax/2024/1099s

rename-agent --files ~/Downloads/statements \
  --pattern "{Date:YYYY-MM} - {Bank Name} - Statement" \
  --type bank_statement

During interactive mode, the agent will offer to learn patterns when processing batches. You can also explicitly ask:

You: Learn this pattern for Chase bank statements: {Date:YYYY-MM} - Chase - Statement - {Last 4 Digits}

1. Analysis: The agent reads your files and extracts text/images
2. Classification: Claude AI identifies the document type and extracts key fields
3. Pattern Matching: Finds the best naming pattern (or suggests a new one)
4. Batch Consistency: For similar documents, uses the same pattern
5. Preview: Shows you all proposed renames before executing
6. Learning: Saves patterns that work well for future use

# Install in development mode
pip3.11 install -e ".[dev]"

# Run tests
python3.11 -m pytest

# Format code
python3.11 -m black rename_agent/

MIT