{"id":50455718,"url":"https://github.com/bsreeram08/folico","last_synced_at":"2026-06-01T02:30:20.751Z","repository":{"id":361152493,"uuid":"1253293936","full_name":"bsreeram08/folico","owner":"bsreeram08","description":"Make Finder make sense with automatic folder icons for macOS.","archived":false,"fork":false,"pushed_at":"2026-05-29T11:53:13.000Z","size":43,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-05-29T12:25:51.865Z","etag":null,"topics":["ai-agents","cli","finder","folder-icons","macos","mcp","productivity","swift","swiftui"],"latest_commit_sha":null,"homepage":"https://github.com/bsreeram08/folico","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bsreeram08.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","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-05-29T10:18:04.000Z","updated_at":"2026-05-29T11:53:17.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/bsreeram08/folico","commit_stats":null,"previous_names":["bsreeram08/folico"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/bsreeram08/folico","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bsreeram08%2Ffolico","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bsreeram08%2Ffolico/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bsreeram08%2Ffolico/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bsreeram08%2Ffolico/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bsreeram08","download_url":"https://codeload.github.com/bsreeram08/folico/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bsreeram08%2Ffolico/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33757790,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-01T02:00:06.963Z","response_time":115,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"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":["ai-agents","cli","finder","folder-icons","macos","mcp","productivity","swift","swiftui"],"created_at":"2026-06-01T02:30:20.011Z","updated_at":"2026-06-01T02:30:20.733Z","avatar_url":"https://github.com/bsreeram08.png","language":"Swift","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Folico\n\nFolico is a native macOS SwiftUI utility that applies custom folder icons based on folder names.\n\n## Automatic Generation + AI\n\nFolico works in two layers:\n\n- **Automatic generation:** Folico scans folder names and generates icon suggestions with built-in local rules. No AI or internet is required.\n- **AI-assisted workflow:** Any AI agent can call Folico's CLI, read the JSON plan, explain the suggestions, ask for approval, and apply only the approved icons.\n\nThat means Folico works by itself, and it also works well with AI agents.\n\n```sh\nfolico agent plan --path ~/Documents\n```\n\nThe command above auto-generates a JSON plan. An AI agent can then summarize it and run:\n\n```sh\nfolico agent apply --path ~/Documents --items 1,3 --confirm\n```\n\n## AI Agent Flow\n\nFolico is designed so you can ask an AI agent to organize Finder icons for you.\n\nThe agent should:\n\n1. Scan a folder with Folico.\n2. Show you the suggested icon changes.\n3. Ask which changes you want.\n4. Apply only the approved icons.\n5. Offer restore commands if you want to undo.\n\nFolico's agent commands are JSON-first, so any coding agent can call them through the shell.\n\n```sh\nfolico agent scan --path ~/Documents\nfolico agent plan --path ~/Documents\nfolico agent apply --path ~/Documents --items 1,3 --confirm\nfolico agent restore-plan --folders ~/Documents/Invoices\nfolico agent restore --folders ~/Documents/Invoices --confirm\nfolico agent names --path ~/Documents\nfolico agent review-names --names ~/Documents/client_invoices=\"Client Invoices\"\n```\n\n`scan`, `plan`, `restore-plan`, `names`, and `review-names` are read-only. `apply` and `restore` require `--confirm`.\n\n## Paste This Into Your AI Agent\n\nUse this prompt with Codex, Claude Code, Cursor, Windsurf, or any agent that can run shell commands:\n\n```text\nYou are helping me use Folico, a macOS CLI/app that applies folder icons based on folder names.\n\nUse Folico through the CLI. Prefer JSON agent commands.\n\nCore commands:\n- folico agent scan --path \u003cfolder\u003e\n- folico agent plan --path \u003cfolder\u003e\n- folico agent apply --path \u003cfolder\u003e --items \u003cnumbers\u003e --confirm\n- folico agent restore-plan [--folders \u003cpaths\u003e]\n- folico agent restore [--folders \u003cpaths\u003e] --confirm\n- folico agent names --path \u003cfolder\u003e\n- folico agent review-names --names \u003cpath=name,path=name\u003e\n\nRules:\n- Never apply icons before showing me the JSON plan and asking for approval.\n- Never run apply or restore without --confirm, and only use --confirm after I approve.\n- Prefer selecting specific suggestions with --items or --folders.\n- Treat naming suggestions as advice only. Do not rename folders automatically.\n- Folico only scans folder names. Do not inspect file contents.\n- If a command fails, explain the error and do not retry a mutating command without asking.\n\nFlow:\n1. Ask me which folder to scan if I have not provided one.\n2. Run: folico agent plan --path \u003cfolder\u003e\n3. Summarize the suggested icon changes in plain English.\n4. Ask which item numbers I want to apply.\n5. Run: folico agent apply --path \u003cfolder\u003e --items \u003capproved_numbers\u003e --confirm\n6. Summarize success/failure results.\n7. If I ask to undo, run restore-plan first, then restore only after approval.\n```\n\n## MVP Features\n\n- Choose one or more watched folders.\n- Live-watch selected folders for new files and folders.\n- Optional local notifications for new files and folders.\n- Optional automatic icon application for newly created folders.\n- Scan direct child folders only.\n- Preview matched icon suggestions before applying.\n- Deselect or manually override suggested icons.\n- Create and edit local keyword/path rules in the dedicated Rules tab.\n- Optionally learn local rules from manual icon choices.\n- Optionally learn folder-name preferences from accepted/rejected suggestions.\n- Configure scan exclusions from the app, CLI, or MCP.\n- Configure HTTP MCP, stdio MCP, CLI commands, and local automation hooks in the dedicated AI tab.\n- Optionally run local hooks for CLI agents, scripts, or notification bridges.\n- Apply icons with AppKit.\n- Restore default folder icons from history.\n- Store all app data locally in Application Support.\n\n## CLI\n\nFolico can also run directly against a folder:\n\n```sh\nswift run Folico scan ~/Documents\nswift run Folico scan ~/Documents --json\nswift run Folico agent scan --path ~/Documents\nswift run Folico agent plan --path ~/Documents\nswift run Folico agent apply --path ~/Documents --items 1,3 --confirm\nswift run Folico agent configure-settings --auto-watch true --notify true --learn-icons true\nswift run Folico agent upsert-rule --label Games --icon game --keywords game,games,gaming\nswift run Folico agent record-icon-preference --folder ~/Documents/python --icon code --folder-color blue\nswift run Folico agent upsert-hook --label Claude --event folderMatched --command 'claude -p {{prompt}}'\nswift run Folico agent add-exclusion --pattern node_modules\nswift run Folico apply ~/Documents --folders ~/Documents/Invoices,~/Documents/Photos\nswift run Folico restore --folders ~/Documents/Invoices\nswift run Folico names ~/Documents\n```\n\n`scan` and `names` are read-only. `apply` changes Finder folder icons, and `restore` clears custom folder icons from Folico history.\n\nFor AI agents and scripts, prefer the JSON-first agent commands:\n\n```sh\nfolico agent plan --path ~/Documents\nfolico agent scan --path ~/Documents\nfolico agent apply --path ~/Documents --items 1,3 --confirm\nfolico agent configure-settings --auto-watch true --notify true --auto-apply-new-folder-icons true --learn-icons true --learn-names true\nfolico agent upsert-rule --label Games --icon game --keywords game,games,gaming --folder-color purple\nfolico agent record-icon-preference --folder ~/Documents/python --icon code --folder-color blue\nfolico agent upsert-generated-rule --id generated-games --label \"Generated Games\" --icon game --keywords game,games,gaming\nfolico agent configure-settings --mcp-http true --mcp-http-port 8765\nfolico agent configure-settings --hooks true\nfolico agent upsert-hook --label Claude --event folderMatched --command 'claude -p {{prompt}}'\nfolico agent exclusions\nfolico agent restore-plan --folders ~/Documents/Invoices\nfolico agent restore --folders ~/Documents/Invoices --confirm\nfolico agent names --path ~/Documents\nfolico agent review-names --names ~/Documents/client_invoices=\"Client Invoices\"\n```\n\nSee [docs/CLI.md](docs/CLI.md) for the stable agent CLI contract.\n\n## Agent Skill File\n\nIf your agent supports reusable skills or instruction files, save this as `folico/SKILL.md`:\n\n```markdown\n---\nname: folico\ndescription: Use Folico to scan macOS folders, suggest icons, apply approved folder icons, restore icons, and review folder naming plans through the CLI.\n---\n\nUse Folico through shell commands. Prefer `folico agent ...` commands because they print JSON.\n\nCommands:\n- `folico agent scan --path \u003cfolder\u003e`: read-only raw suggestions.\n- `folico agent plan --path \u003cfolder\u003e`: read-only apply plan.\n- `folico agent apply --path \u003cfolder\u003e --items \u003cnumbers\u003e --confirm`: applies approved icons.\n- `folico agent restore-plan [--folders \u003cpaths\u003e]`: read-only restore plan.\n- `folico agent restore [--folders \u003cpaths\u003e] --confirm`: restores approved icons.\n- `folico agent names --path \u003cfolder\u003e`: read-only naming advice.\n- `folico agent review-names --names \u003cpath=name,path=name\u003e`: validate proposed names.\n\nSafety:\n- Show the user the plan before applying.\n- Do not use `--confirm` until the user approves.\n- Prefer `--items` or `--folders` instead of applying everything.\n- Do not rename folders automatically.\n- Do not inspect file contents.\n- Stop and explain if any mutating command fails.\n```\n\n## MCP\n\nTurn on the HTTP MCP server from the macOS app's AI tab, or start it from the CLI:\n\n```sh\nswift run Folico mcp-http --port 8765\n```\n\nThen point MCP clients that support Streamable HTTP at `http://127.0.0.1:8765/mcp`.\nThe AI tab also lets you stop the server, copy the URL, and change the port.\nFor clients that launch local command servers, `swift run Folico mcp-stdio` starts the stdio transport.\n\nAvailable tools:\n\n- `folico_scan_folder`: scan a root folder and return icon suggestions.\n- `folico_apply_icons`: apply selected suggestions; requires `confirmApply: true`.\n- `folico_restore_icons`: restore icons from history; requires `confirmRestore: true`.\n- `folico_suggest_folder_names`: suggest clearer folder names without renaming anything.\n- `folico_review_folder_name_plan`: let an agent submit proposed folder names for validation; Folico does not rename folders.\n- `folico_get_settings` / `folico_update_settings`: read and update local toggles.\n- `folico_list_rules` / `folico_upsert_rule` / `folico_remove_rule`: manage explicit local icon rules.\n- `folico_list_exclusions` / `folico_upsert_exclusion` / `folico_set_exclusion_enabled` / `folico_remove_exclusion`: manage local scan exclusions.\n- `folico_list_watched_folders` / `folico_add_watched_folder`: manage watched folders.\n- `folico_upsert_generated_rule`: manage generated fallback icon rules.\n\nSee [docs/MCP.md](docs/MCP.md) for tool inputs, agent safety rules, and example payloads.\n\n## Privacy\n\nFolico runs locally. It only scans folder names inside folders you select. It does not collect analytics, upload folder names, send file paths, inspect file contents, or use a remote service.\n\n## Development\n\nThis repository is a Swift Package with a small executable wrapper and a testable app module.\n\n```sh\nswift run Folico\nswift test\n```\n\nOpen the package in Xcode on macOS 14+ for app signing, native Finder icon verification, and release builds.\n\n## Build DMG\n\nOn macOS 14+:\n\n```sh\nbash scripts/package-dmg.sh\nopen dist/Folico.dmg\n```\n\nThe generated app bundle uses bundle identifier `folico.sreerams.in`.\n\nThe packaging script generates `Folico.icns` from `Assets/AppIcon/FolicoAppIcon.png` and sets it as the app icon in the bundle.\n\nGitHub Actions also builds `Folico.dmg` on every push to `master`. Run the **Build DMG** workflow manually with `publish_release=true` to upload the latest DMG to the `latest` GitHub release.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbsreeram08%2Ffolico","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbsreeram08%2Ffolico","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbsreeram08%2Ffolico/lists"}