{"id":40126296,"url":"https://github.com/tigger04/smart-rename","last_synced_at":"2026-01-19T13:07:34.870Z","repository":{"id":333031509,"uuid":"1134677382","full_name":"tigger04/smart-rename","owner":"tigger04","description":"Auto rename files (individually or in batch) based on their content (AI assisted, supports Ollama, OpenAI and Claude APIs)","archived":false,"fork":false,"pushed_at":"2026-01-17T05:15:31.000Z","size":104,"stargazers_count":0,"open_issues_count":12,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-01-17T11:27:44.727Z","etag":null,"topics":["automation","bash","batch","cli","genai","organizatio","rename","shell"],"latest_commit_sha":null,"homepage":"https://tigger.dev","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tigger04.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-01-15T03:30:08.000Z","updated_at":"2026-01-17T05:15:23.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/tigger04/smart-rename","commit_stats":null,"previous_names":["tigger04/smart-rename"],"tags_count":18,"template":false,"template_full_name":null,"purl":"pkg:github/tigger04/smart-rename","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tigger04%2Fsmart-rename","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tigger04%2Fsmart-rename/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tigger04%2Fsmart-rename/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tigger04%2Fsmart-rename/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tigger04","download_url":"https://codeload.github.com/tigger04/smart-rename/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tigger04%2Fsmart-rename/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28568834,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-19T12:50:50.164Z","status":"ssl_error","status_checked_at":"2026-01-19T12:50:42.704Z","response_time":67,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","bash","batch","cli","genai","organizatio","rename","shell"],"created_at":"2026-01-19T13:07:32.804Z","updated_at":"2026-01-19T13:07:34.863Z","avatar_url":"https://github.com/tigger04.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# smart-rename\n\nAI-powered file renaming tool that generates intelligent, descriptive filenames based on file content.\n\n## Features\n\n- Analyze file content and generate smart filenames\n- Special formatting for receipts/invoices (YYYY-MM-DD-amount-description)\n- Support for multiple currencies with configurable base currency\n- Batch processing with pattern matching (regex or glob)\n- Multiple AI provider support (OpenAI, Claude, Ollama)\n- Interactive or automatic rename mode\n\n## Supported File Types\n\n### Currently Supported\n- [x] PDF documents\n- [x] Images (JPG, PNG, JPEG)\n- [x] Text files (TXT)\n- [x] Markdown files (MD)\n- [x] HTML files\n- [x] CSV files\n- [x] Subtitle files (SRT, VTT, SUB)\n- [x] JSON files\n- [x] XML files\n- [x] Source code files (any plaintext)\n\n### On the Roadmap\n- [ ] Microsoft Word documents (DOCX)\n- [ ] Microsoft Excel spreadsheets (XLSX) - with data analysis\n- [ ] Microsoft PowerPoint presentations (PPTX)\n- [ ] RTF documents\n- [ ] OpenDocument formats (ODT, ODS, ODP)\n- [ ] Email files (EML, MSG)\n- [ ] Video files (MP4, MOV) - extract first frame\n\n## Quick Start\n\n### MacOS\n```bash sh\nbrew install tigger04/tap/smart-rename\n```\n\n### Dependencies\n\nThe following are installed automatically via Homebrew:\n- `fd` - fast file finder\n- `yq` - YAML parser\n- `jq` - JSON parser\n- `poppler` - PDF text extraction (provides `pdftotext`)\n\n### Other platforms\n- Linux package managers coming soon, meanwhile see the Dev install guide below\n\n## Configuration\n\nThe tool automatically detects available AI providers and uses the first available one. Configuration is loaded in this order:\n\n1. **Environment variables** (highest priority)\n   - `OPENAI_API_KEY`\n   - `CLAUDE_API_KEY`\n\n2. **YAML config file**: `~/.config/smart-rename/config.yaml`\n   - The default config is copied here on first use, and should be intuitive to customize\n\n3. **Built-in defaults**\n\n### YAML Configuration Features\n\n- **Custom prompts**: Configure the AI prompt with placeholders\n- **API settings**: All providers and models in one place\n- **Abbreviations**: Clean YAML format for custom abbreviations\n\nExample YAML structure:\n```yaml\nprompts:\n  rename: |\n    Your custom prompt with {{BASE_CURRENCY}} and {{ABBREVIATIONS}} placeholders\n\ncurrency:\n  base: \"USD\"\n\nabbreviations:\n  myorg: \"My Organization\"\n```\n\n### Auto-Detection\n\n- If only one API key is provided, that provider becomes the default\n- If multiple keys are available, preference order: OpenAI → Claude → Ollama\n- If no API keys but Ollama is running locally, uses Ollama\n- If all are provided, the default can be set in `config.yaml`\n\n### Local AI with Ollama\n\nThe default local model is **Qwen2.5 3B**, chosen for:\n- Better accuracy for filename generation than alternatives\n- Lower hallucination rate for structured output\n- Optimized for 8GB RAM on Apple Silicon\n- Good balance of speed and quality\n\nThe model is automatically pulled on first use. To use a different model, set `api.ollama.model` in your config.\n\n**Optional: Custom Modelfile**\n\nFor optimized local processing, create a custom model with tuned parameters:\n\n```bash\n# Create ~/.ollama/modelfiles/smart-rename.Modelfile\ncat \u003e ~/.ollama/modelfiles/smart-rename.Modelfile \u003c\u003c 'EOF'\nFROM qwen2.5:3b\n\nSYSTEM \"\"\"You generate concise, descriptive filenames.\nRules:\n- Output only the filename, nothing else\n- No extension, lowercase, use hyphens\n- For receipts/invoices: YYYY-MM-DD-amount.cc-description\n- Amount always includes exactly two decimal places\n- Be specific, preserve key names, dates, figures\"\"\"\n\nPARAMETER temperature 0.2\nPARAMETER num_ctx 8192\nEOF\n\n# Build it\nollama create smart-rename -f ~/.ollama/modelfiles/smart-rename.Modelfile\n```\n\nThen set `model: smart-rename` in your config to use it.\n\n## Usage\n\n```bash\n# PATTERN\nsmart-rename [OPTIONS] [REGEX]\n# -or-\nsmart-rename -g [OPTIONS] [GLOB]\n\n# Process files matching pattern (interactive mode)\nsmart-rename \"receipt.*\\.pdf\"\n\n# Auto-rename without confirmation\nsmart-rename -y invoice.pdf\n\n# Search recursively\nsmart-rename -r \"\\.docx$\"\n\n# Use glob pattern instead of regex\nsmart-rename -g \"*.pdf\"\n\n# Use specific AI provider\nsmart-rename --claude document.pdf\nsmart-rename --openai receipt.jpg\n```\n\n## CLI switches\n\n### Search Options\n- `-r, --recursive`: Search files recursively\n- `-g, --glob`: Treat pattern as glob instead of regex\n\n### AI Models\n- `-l, --ollama[=model]`: Use Ollama API\n- `-o, --openai[=model]`: Use OpenAI API\n- `--claude`: Use Claude API\n- `--prompt=TEXT`: Custom prompt\n\n### Rename Options\n- `-y, --yes`: Auto-rename without confirmation\n\n## Filename Format\n\n### Regular Documents\n- Format: `descriptive-name-YY-MM-DD.ext`\n- Uses current date if not found in content\n\n### Receipts/Invoices\n- Format: `YYYY-MM-DD-amount.cc-description.ext` (amount always includes two decimal places)\n- Examples: `2024-01-15-123.45-office-supplies.pdf`, `2024-02-28-100.00-monthly-subscription.pdf`\n- Amount in base currency (base currency configurable, default EUR)\n- Non-base currency: `YYYY-MM-DD-CUR-amount.cc-description.ext` where CUR is the ISO currency code.\n\n### Abbreviations (Configurable)\nThe tool comes with a few example abbreviations, adjust to your own needs in `config.yaml`\n- svph = St. Vincent's Private Hospital\n- svuh = St. Vincent's University Hospital\n- nrh = National Rehabilitation Hospital\n- mater = Mater Misericordiae University Hospital\n\n## Examples\n\n```bash\n# Rename all PDF receipts in current directory\nsmart-rename -g \"receipt*.pdf\"\n\u003e \n\n# Process all documents recursively with auto-rename\nsmart-rename -r -y \".*\\.(pdf|jpg|png)$\"\n\n## Development Installation\n\nFor development or manual installation:\n\n```bash\n# Clone the repository\ngit clone https://github.com/tigger04/smart-rename.git\ncd smart-rename\n\n# Run tests\nmake test\n\n# Install to /usr/local/bin (requires sudo)\nsudo make install\n\n# Uninstall\nsudo make uninstall\n```\n\n## Release Workflow\n\nFor maintainers releasing new versions:\n\n```bash\n# 1. Make your changes and commit them\ngit add -A \u0026\u0026 git commit -m \"feat: description\" \u0026\u0026 git push\n\n# 2. Run release (auto-bumps version, tags, updates Homebrew)\nmake release\n```\n\n**Available make targets:**\n\n| Target | Description |\n|--------|-------------|\n| `make test` | Run all tests |\n| `make release` | Full release: test → bump → commit → tag → formula → brew-upgrade |\n| `make bump` | Increment patch version (X.Y.Z → X.Y.Z+1) |\n| `make tag` | Create and push git tag for current VERSION |\n| `make formula` | Update Homebrew formula with version and SHA256 |\n| `make brew-upgrade` | Upgrade local Homebrew installation |\n\nThe release process automatically:\n- Increments the patch version (e.g., 5.20.0 → 5.20.1)\n- Commits the version bump\n- Creates and pushes a git tag\n- Updates the Homebrew formula with new version and SHA256\n- Upgrades the local Homebrew installation\n- Requires a clean git working directory before starting\n\n## License\n\nMIT License - See LICENSE file for details\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftigger04%2Fsmart-rename","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftigger04%2Fsmart-rename","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftigger04%2Fsmart-rename/lists"}