{"id":25935257,"url":"https://github.com/guardzcom/slack-channel-curator","last_synced_at":"2026-04-29T09:32:06.827Z","repository":{"id":280098743,"uuid":"940660450","full_name":"guardzcom/slack-channel-curator","owner":"guardzcom","description":"CLI tool for Slack channel maintenance","archived":false,"fork":false,"pushed_at":"2025-03-02T08:22:29.000Z","size":190,"stargazers_count":7,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-07T14:03:39.943Z","etag":null,"topics":["automation","cli","python","slack","slack-api"],"latest_commit_sha":null,"homepage":"","language":"Python","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/guardzcom.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":"2025-02-28T15:11:25.000Z","updated_at":"2025-03-25T12:59:39.000Z","dependencies_parsed_at":"2025-03-01T13:28:02.707Z","dependency_job_id":"fdb6ce8f-10bd-420c-ace3-3d0af25c4304","html_url":"https://github.com/guardzcom/slack-channel-curator","commit_stats":null,"previous_names":["guardzcom/slack-channel-cleanup","guardzcom/slack-channel-curator"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/guardzcom/slack-channel-curator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guardzcom%2Fslack-channel-curator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guardzcom%2Fslack-channel-curator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guardzcom%2Fslack-channel-curator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guardzcom%2Fslack-channel-curator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/guardzcom","download_url":"https://codeload.github.com/guardzcom/slack-channel-curator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/guardzcom%2Fslack-channel-curator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32419860,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T06:29:02.080Z","status":"ssl_error","status_checked_at":"2026-04-29T06:29:00.631Z","response_time":110,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6: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","cli","python","slack","slack-api"],"created_at":"2025-03-04T01:33:55.090Z","updated_at":"2026-04-29T09:32:06.809Z","avatar_url":"https://github.com/guardzcom.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Slack Channel Curator\n\nA Python script to thoughtfully curate Slack channels, supporting operations like renaming and archiving channels. Perfect for workspace cleanup and reorganization.\n\n\u003e 🤖 Built with [Cursor](https://cursor.sh/), the AI-first code editor, and its Claude-powered assistant.\n\n## ⚠️ Warning\n\nThis tool performs bulk operations that can permanently affect your Slack workspace. While it includes safety features, you are responsible for any changes made to your channels. Please use thoughtfully!\n\n## Why?\n\nManaging Slack channels at scale can be tedious and error-prone. This tool helps you:\n- Clean up inactive channels\n- Reorganize channel naming\n- Consolidate redundant channels\n- Review changes before executing\n- Keep audit trail of all actions\n\n## Features\n\n- 🔍 Maintains a spreadsheet of all channels (public and private)\n- 📝 Review and plan changes in your preferred format (CSV or Google Sheets)\n- 🔄 Bulk actions: rename, archive, or update descriptions of channels\n- ✨ Interactive approval process with detailed channel info\n- 🛡️ Safe execution with dry-run mode and backups\n- 📊 Real-time progress and summary reporting\n\n## Prerequisites\n\n- Python 3.6+\n- A Slack user token (xoxp) with the following scopes:\n  - `channels:read` - For listing public channels\n  - `groups:read` - For listing private channels\n  - `channels:write` - For managing public channels\n  - `groups:write` - For managing private channels\n  - `chat:write` - For posting redirect notices (optional)\n  - `channels:history` - For fetching public channel last activity data\n  - `groups:history` - For fetching private channel last activity data\n\nNote: Admin privileges are recommended for full workspace management capabilities.\n\nTo get a Slack token:\n1. Go to [api.slack.com/apps](https://api.slack.com/apps)\n2. Create a new app in your workspace\n3. Add the required scopes under \"OAuth \u0026 Permissions\"\n4. Install the app to your workspace\n5. Copy the \"User OAuth Token\" (starts with `xoxp-`)\n\n## Setup\n\nCreate a `.env` file with your Slack token:\n```bash\nSLACK_TOKEN=xoxp-your-token-here\n```\n\n## Google Sheets Integration\n\nTo use Google Sheets as your spreadsheet format:\n\n1. Set up Google Cloud Project:\n   - Go to [Google Cloud Console](https://console.cloud.google.com)\n   - Create a new project or select an existing one\n   - Enable the Google Sheets API for your project\n\n2. Create Service Account:\n   - Go to \"IAM \u0026 Admin\" \u003e \"Service Accounts\"\n   - Click \"Create Service Account\"\n   - Name it (e.g., \"slack-channel-curator\")\n   - Click \"Create and Continue\"\n   - Skip role assignment\n   - Click \"Done\"\n\n3. Download Credentials:\n   - Click on the newly created service account\n   - Go to \"Keys\" tab\n   - Click \"Add Key\" \u003e \"Create new key\"\n   - Choose JSON format\n   - Save the downloaded file as `service-account.json` in your project directory\n\n4. Share your Google Sheet:\n   - Create a new Google Sheet\n   - Click \"Share\" in the top right\n   - Add the service account email (found in `service-account.json`) with \"Editor\" access\n   - Copy the sheet URL\n\n5. Run the script with the `--sheet` option:\n```bash\npython slack_channel_curator.py --sheet \"YOUR-SHEET-URL\"\n```\n\nThe sheet will be automatically populated with your channels and kept in sync.\n\n## Usage\n\nThe script maintains a spreadsheet of all your Slack channels. Each time you run it, it will:\n1. Process any pending actions from the spreadsheet\n2. Update the channel list with any new channels\n3. Keep the spreadsheet in sync with your workspace\n\nChoose your preferred format:\n```bash\n# Using CSV format\npython slack_channel_curator.py -f channels.csv\n\n# Using Google Sheets\npython slack_channel_curator.py --sheet \"YOUR-SHEET-URL\"\n\n# Test changes with dry run mode\npython slack_channel_curator.py -f channels.csv --dry-run\n\n# Process channels in batches of 5 instead of the default 10\npython slack_channel_curator.py -f channels.csv --batch 5\n\n# Process each channel individually (no batch confirmation)\npython slack_channel_curator.py -f channels.csv --batch 0\n\n# Force refresh of channel data (ignore cache)\npython slack_channel_curator.py -f channels.csv --refresh\n```\n\nThe spreadsheet has the following columns:\n\nRequired columns:\n- channel_id: Slack's internal channel ID\n- name: Channel name\n- description: Channel purpose/description\n- action: What action to take (keep, archive, rename, update_description)\n- target_value: Target for rename, archive redirect, or new description\n\nOptional columns:\n- is_private: Whether the channel is private\n- is_shared: Whether the channel is shared via Slack Connect\n- member_count: Number of members\n- created_date: When the channel was created\n- last_activity: Date of the most recent message (YYYY-MM-DD)\n- notes: Optional notes about the change\n\nTo make changes:\n1. Edit the spreadsheet and set actions:\n   - `new` - Newly discovered channel that needs review\n   - `keep` - No changes (default for existing channels)\n   - `archive` - Archive the channel. Optionally specify a target channel in `target_value` to post a redirect notice\n   - `rename` - Rename channel (set new name in `target_value`)\n   - `update_description` - Update channel description (set new description in `target_value`)\n2. Run the script again to process your changes\n3. The script will:\n   - Show you each proposed change\n   - Ask for confirmation\n   - Execute approved changes\n   - Update the spreadsheet to reflect the changes\n\n## Command Line Options\n\n```bash\npython slack_channel_curator.py [options]\n\nOptions:\n  -f, --file FILE      Path to CSV file (cannot be used with --sheet)\n  --sheet URL          Google Sheets URL (cannot be used with --file)\n  -d, --dry-run        Simulate execution without making changes\n  -b, --batch SIZE     Number of channels to confirm at once (default: 10, 0 for individual confirmation)\n  -r, --refresh        Force refresh of channel data (ignore cache)\n\nNote: You must specify either --file OR --sheet, but not both.\n```\n\n## Performance Optimization\n\nThe script caches channel activity data to speed up repeated runs. The cache:\n- Is stored in `channel_activity_cache.json` in the project directory (ignored by git)\n- Only stores the last activity timestamps, not the entire channel list\n- Expires after 24 hours\n- Can be refreshed with the `--refresh` flag\n\nThis significantly improves performance when making small changes or corrections, as it avoids repeatedly fetching channel activity data from Slack, which is one of the most time-consuming operations.\n\n## Safety Features\n\n- ✅ Interactive approval for each action (individual or batch)\n- ⚠️ Extra confirmation for destructive actions\n- 🔍 Dry run mode to preview changes\n- 🔒 Permission and name validation\n- 📝 Detailed logging and error reporting\n\n## Limitations\n\n- Cannot archive:\n  - The general/default channel\n  - Required channels\n  - Slack Connect (shared) channels\n  - Channels where you're not a member (unless you're an admin)\n- Redirect notices:\n  - Will attempt to post when archiving with a target channel\n  - If posting fails (e.g., not a member of the channel), a warning is shown and archiving continues\n  - Target channel must exist and not be archived\n- Cannot rename:\n  - Archived channels\n  - Channels without proper permissions (unless you're an admin)\n  - To names that already exist\n- Channel names must be:\n  - Lowercase\n  - No spaces or periods\n  - Max 80 characters\n  - Only letters, numbers, hyphens, underscores\n- Google Sheets specific:\n  - Requires a Google Cloud Project\n  - Service account must have editor access to the sheet\n  - Sheet URL must be in the correct format\n- Last activity data:\n  - Fetched using conversations.history API (Tier 3 rate limit)\n  - May be empty if channel has no messages or if you lack access permissions\n  - Updates each time the channel list is refreshed\n\n## Debugging\n\n- Use VSCode's debug configurations (included in `.vscode/launch.json`)\n- Check the Slack API responses for detailed error messages\n- Use `--dry-run` to validate changes before executing\n- Review version history (Google Sheets) or backup files (CSV) if needed\n- For Google Sheets specific issues:\n  - Verify service account permissions\n  - Check sheet sharing settings\n  - Ensure sheet URL is correct\n\n## Contributing\n\nContributions are welcome! Feel free to:\n- Report bugs\n- Suggest features\n- Submit pull requests\n\n## Security Note\n\n- Never commit your `.env` file or `service-account.json`\n- Keep your Slack token secure\n- Review changes carefully before execution\n- Consider running `--dry-run` first\n- For Google Sheets:\n  - Keep service account credentials secure\n  - Only share sheets with necessary users\n  - Regularly review service account access","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguardzcom%2Fslack-channel-curator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fguardzcom%2Fslack-channel-curator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fguardzcom%2Fslack-channel-curator/lists"}