{"id":48883131,"url":"https://github.com/devsigner9920/threadle","last_synced_at":"2026-04-16T04:02:10.627Z","repository":{"id":325427505,"uuid":"1101131017","full_name":"devsigner9920/threadle","owner":"devsigner9920","description":"Threadle Slack Translator Bot","archived":false,"fork":false,"pushed_at":"2025-11-21T08:46:09.000Z","size":184,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-21T10:21:53.981Z","etag":null,"topics":["ai","anthropic","chatbot","cross-team","gemini","google-gemini","llm","openai","slack","slack-bot","translation","typescript"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/devsigner9920.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":"SECURITY_PERFORMANCE.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":"2025-11-21T08:35:19.000Z","updated_at":"2025-11-21T08:51:28.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/devsigner9920/threadle","commit_stats":null,"previous_names":["devsigner9920/threadle"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/devsigner9920/threadle","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devsigner9920%2Fthreadle","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devsigner9920%2Fthreadle/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devsigner9920%2Fthreadle/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devsigner9920%2Fthreadle/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/devsigner9920","download_url":"https://codeload.github.com/devsigner9920/threadle/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/devsigner9920%2Fthreadle/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":31870516,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-15T15:24:51.572Z","status":"online","status_checked_at":"2026-04-16T02:00:06.042Z","response_time":69,"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","anthropic","chatbot","cross-team","gemini","google-gemini","llm","openai","slack","slack-bot","translation","typescript"],"created_at":"2026-04-16T04:02:09.685Z","updated_at":"2026-04-16T04:02:10.613Z","avatar_url":"https://github.com/devsigner9920.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Threadle\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)\n[![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A520.0.0-green.svg)](https://nodejs.org/)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](https://github.com/devsigner9920/threadle/pulls)\n\n\u003e Cross-discipline Slack translator bot powered by LLM - Helping teams communicate across technical boundaries.\n\nThreadle is an open-source Slack bot that translates technical jargon between professional disciplines (engineers, designers, marketers, PMs) using AI-powered explanations. Install it as a global npm package or run it via Docker in minutes.\n\n## Features\n\n- **Cross-Discipline Translation**: Engineers, designers, PMs, and marketers can understand each other's technical discussions\n- **Private \u0026 Secure**: Runs locally on your machine with your own API keys\n- **Multiple LLM Providers**: Support for OpenAI, Anthropic Claude, and Google Gemini\n- **Slack Integration**: Native `/explain`, `/setprofile`, and `/help` slash commands\n- **Role-Based Context**: Explanations tailored to your professional background\n- **Web Dashboard**: User-friendly setup wizard and profile management\n- **SQLite Database**: Single-tenant, no cloud dependencies\n- **Docker Support**: Easy deployment with Docker or Docker Compose\n\n## Quick Start\n\n### Option 1: npm Installation (Recommended)\n\n```bash\nnpm install -g threadle\n```\n\nOr use npx without installing:\n\n```bash\nnpx threadle init\nnpx threadle start\n```\n\n**Initialize:**\n\n```bash\nthreadle init\n```\n\nThis creates `~/.threadle/` directory with:\n\n- `config.json` - Application configuration\n- `secrets.encrypted` - Encrypted API keys and tokens\n- `data/` - SQLite database storage\n- `logs/` - Application logs\n\n**Start Server:**\n\n```bash\nthreadle start\n```\n\nOpens http://localhost:3000 in your browser. On first run, you'll see the setup wizard.\n\n**Stop Server:**\n\n```bash\nthreadle stop\n```\n\nGracefully shuts down the server.\n\n### Option 2: Docker Deployment\n\n**Quick start with Docker:**\n\n```bash\ndocker run -d \\\n  --name threadle \\\n  -p 3000:3000 \\\n  -v threadle-data:/app/data \\\n  --restart unless-stopped \\\n  threadle/threadle:latest\n```\n\n**Or use Docker Compose (recommended):**\n\n```bash\n# Download docker-compose.yml\ncurl -O https://raw.githubusercontent.com/threadle/threadle/main/docker-compose.yml\n\n# Start Threadle\ndocker-compose up -d\n\n# Access at http://localhost:3000\n```\n\n**Docker commands:**\n\n```bash\n# View logs\ndocker-compose logs -f\n\n# Stop\ndocker-compose down\n\n# Update to latest version\ndocker-compose pull \u0026\u0026 docker-compose up -d\n```\n\nFor detailed Docker instructions, see [DOCKER_README.md](DOCKER_README.md)\n\n## Setup Wizard\n\nThe first time you run `threadle start`, you'll be guided through a 6-step setup wizard:\n\n### Step 1: Welcome \u0026 Prerequisites\n\n- Verifies Node.js version (20+)\n- Checks network connectivity\n- Links to Slack App creation guide\n\n### Step 2: AI Provider Configuration\n\nSelect your preferred LLM provider:\n\n- **OpenAI** (GPT-4, GPT-4 Turbo)\n- **Anthropic** (Claude 3.5 Sonnet, Claude 3 Opus)\n- **Google** (Gemini Pro, Gemini Ultra)\n\nEnter your API key (stored encrypted locally).\n\n### Step 3: Slack App Setup\n\nFollow the guided instructions to:\n\n1. Create a Slack App at [api.slack.com/apps](https://api.slack.com/apps)\n2. Configure Bot Token Scopes:\n   - `chat:write` - Send messages\n   - `commands` - Handle slash commands\n   - `users:read` - Read user profiles\n   - `channels:history` - Read channel messages\n3. Enter App ID, Client ID, Client Secret, and Signing Secret\n\n### Step 4: Slack OAuth Installation\n\nClick \"Install to Workspace\" to authorize Threadle in your Slack workspace.\n\n### Step 5: Global Default Settings\n\nConfigure defaults:\n\n- **Translation Style**: ELI5, Business Summary, Technical Lite, or Analogies Only\n- **Language**: English, Spanish, French, German, etc.\n- **Rate Limiting**: Requests per user per minute (default: 10)\n- **Cache TTL**: How long to cache translations (default: 1 hour)\n\n### Step 6: Admin Account Creation\n\nSet yourself as the admin user using your Slack User ID.\n\n## Creating a Slack App\n\nDetailed guide: `/SLACK_APP_SETUP.md` in the package\n\n### Quick Steps:\n\n1. Go to https://api.slack.com/apps and click \"Create New App\"\n2. Choose \"From scratch\"\n3. Name it \"Threadle\" and select your workspace\n4. Navigate to \"OAuth \u0026 Permissions\" and add these Bot Token Scopes:\n   - `chat:write`\n   - `commands`\n   - `users:read`\n   - `channels:history`\n5. Navigate to \"Slash Commands\" and create:\n   - `/explain` - Translate technical jargon\n   - `/setprofile` - Update your user profile\n   - `/help` - Show help information\n6. Set Request URLs to your server (e.g., `https://your-domain.com/api/v1/slack/commands`)\n7. Install the app to your workspace\n\n## Usage\n\n### In Slack\n\n#### `/explain` Command\n\nGet an AI-powered explanation of the current thread:\n\n```\n/explain\n```\n\nRequest a public explanation (visible to all):\n\n```\n/explain public\n```\n\n#### `/setprofile` Command\n\nUpdate your role and preferences:\n\n```\n/setprofile\n```\n\nOpens a modal where you can set:\n\n- Professional role (Engineering, Design, Product, Marketing, etc.)\n- Preferred language\n- Translation style preference\n- Custom instructions for personalized explanations\n\n#### `/help` Command\n\nDisplay comprehensive help:\n\n```\n/help\n```\n\n### Web Dashboard\n\nNavigate to http://localhost:3000 after starting the server.\n\n#### Dashboard (/)\n\n- View workspace status\n- See usage statistics\n- Browse recent translations\n- Quick links to profile and settings\n\n#### Profile (/profile)\n\n- Update your role\n- Set language preference\n- Choose translation style\n- Add custom instructions\n\n#### Translation History (/history)\n\n- View all your past translations\n- Filter by date range\n- Paginated results\n\n#### Admin Settings (/admin) - Admin Only\n\n- Manage global settings\n- View all users\n- Update LLM provider configuration\n- Clear translation cache\n- View usage analytics\n\n## Configuration\n\nConfiguration file: `~/.threadle/config.json`\n\n```json\n{\n  \"setupCompleted\": false,\n  \"port\": 3000,\n  \"llmProvider\": \"openai\",\n  \"defaultLanguage\": \"English\",\n  \"defaultStyle\": \"ELI5\",\n  \"rateLimitPerMinute\": 10,\n  \"cacheTTL\": 3600\n}\n```\n\n### Available Options\n\n- `port` - Server port (default: 3000)\n- `llmProvider` - AI provider: \"openai\", \"anthropic\", or \"google\"\n- `defaultLanguage` - Default language for translations\n- `defaultStyle` - Default explanation style:\n  - `ELI5` - Explain Like I'm 5 (simplest)\n  - `Business Summary` - Business-focused explanation\n  - `Technical Lite` - Technical but accessible\n  - `Analogies Only` - Use analogies and metaphors\n- `rateLimitPerMinute` - Max requests per user per minute\n- `cacheTTL` - Cache time-to-live in seconds\n\n## Commands Reference\n\n### CLI Commands\n\n```bash\nthreadle init          # Initialize configuration\nthreadle start         # Start server\nthreadle stop          # Stop server\nthreadle help          # Show help\n```\n\n### Docker Commands\n\n```bash\n# Build Docker image\nnpm run docker:build\n\n# Run Docker container\nnpm run docker:run\n\n# Stop Docker container\nnpm run docker:stop\n\n# Docker Compose\nnpm run docker:compose:up\nnpm run docker:compose:down\nnpm run docker:compose:logs\n```\n\n### Slash Commands (in Slack)\n\n```bash\n/explain              # Explain current thread (ephemeral)\n/explain public       # Explain current thread (visible to all)\n/setprofile           # Update your profile\n/help                 # Show help information\n```\n\n## Deployment Options\n\n### Local npm Installation\n\nPerfect for personal use or small teams. Simple installation, runs on your local machine.\n\n**Pros:**\n\n- Easiest to set up\n- Direct access to configuration files\n- No Docker required\n\n**Cons:**\n\n- Requires Node.js installed\n- Manual process management\n\n### Docker Deployment\n\nIdeal for production deployments, server installations, or when you prefer containerization.\n\n**Pros:**\n\n- Isolated environment\n- Easy updates (`docker-compose pull`)\n- Auto-restart on failure\n- No Node.js installation required\n- Simple backup/restore (volume snapshots)\n\n**Cons:**\n\n- Requires Docker installed\n- Slightly larger disk footprint\n\nSee [DOCKER_README.md](DOCKER_README.md) for detailed Docker deployment instructions.\n\n## Troubleshooting\n\n### Server won't start\n\n**Problem**: `Error: Threadle not initialized`\n\n**Solution**: Run `threadle init` first\n\n---\n\n**Problem**: `Error: Server not built`\n\n**Solution**: The package should be pre-built. If developing locally, run `npm run build`\n\n---\n\n**Problem**: `Error: Port 3000 already in use`\n\n**Solution**: Change the port in `~/.threadle/config.json` or stop the process using port 3000\n\n### Slack Integration Issues\n\n**Problem**: Slash commands don't respond\n\n**Solution**:\n\n1. Check server is running: `curl http://localhost:3000/health`\n2. Verify Slack App Request URL is correct\n3. Check signing secret matches in setup wizard\n4. Review logs in `~/.threadle/logs/`\n\n---\n\n**Problem**: \"Invalid token\" error\n\n**Solution**:\n\n1. Re-run setup wizard from web UI\n2. Verify Slack bot token is correct\n3. Reinstall Slack App to workspace\n\n### LLM Provider Issues\n\n**Problem**: \"Invalid API key\" error\n\n**Solution**:\n\n1. Verify API key in Admin Settings\n2. Test connection from web UI\n3. Check API key has required permissions\n4. Verify API key is not expired\n\n---\n\n**Problem**: Slow response times\n\n**Solution**:\n\n1. Check network connectivity\n2. Increase cache TTL in config\n3. Consider switching to faster LLM provider\n4. Review rate limits on your API key\n\n### Database Issues\n\n**Problem**: \"Database locked\" error\n\n**Solution**:\n\n1. Stop server: `threadle stop`\n2. Wait 10 seconds\n3. Restart: `threadle start`\n4. SQLite WAL mode should prevent this\n\n---\n\n**Problem**: Lost data after update\n\n**Solution**:\n\n1. Database is stored in `~/.threadle/data/threadle.db`\n2. Check if file exists and has content\n3. Restore from backup if available\n\n### Docker-Specific Issues\n\n**Problem**: Container won't start\n\n**Solution**:\n\n1. Check Docker logs: `docker logs threadle`\n2. Verify volume permissions\n3. Ensure port 3000 is available\n\n---\n\n**Problem**: Data not persisting\n\n**Solution**:\n\n1. Verify volume is mounted correctly\n2. Check docker-compose.yml volume configuration\n3. Use named volumes or bind mounts consistently\n\nSee [DOCKER_README.md](DOCKER_README.md) for more Docker troubleshooting.\n\n## Development\n\n### Prerequisites\n\n- Node.js 20+\n- npm 9+\n\n### Local Development\n\n```bash\n# Clone repository\ngit clone https://github.com/threadle/threadle.git\ncd threadle\n\n# Install dependencies\nnpm install\ncd client \u0026\u0026 npm install \u0026\u0026 cd ..\n\n# Build project\nnpm run build\n\n# Run tests\nnpm test\n\n# Start in dev mode\nnpm run dev\n```\n\n### Project Structure\n\n```\nthreadle/\n├── bin/                    # CLI entry points\n│   ├── threadle.js        # Main CLI wrapper\n│   ├── threadle-init.js   # Init command\n│   ├── threadle-start.js  # Start command\n│   └── threadle-stop.js   # Stop command\n├── server/                 # Express backend (TypeScript)\n│   ├── index.ts           # Main server file\n│   ├── config/            # Configuration service\n│   ├── database/          # Database \u0026 Prisma\n│   ├── llm/               # LLM provider integrations\n│   ├── slack/             # Slack integration\n│   ├── translation/       # Translation engine\n│   ├── user/              # User management\n│   ├── routes/            # API routes\n│   └── middleware/        # Express middleware\n├── client/                 # React frontend (Vite + TypeScript)\n│   ├── src/\n│   │   ├── pages/         # Page components\n│   │   ├── components/    # Reusable components\n│   │   ├── api/           # API client\n│   │   └── hooks/         # Custom hooks\n│   └── dist/              # Built frontend (served by Express)\n├── prisma/                 # Database schema\n├── prompts/                # LLM prompt templates\n├── Dockerfile              # Docker image definition\n├── docker-compose.yml      # Docker Compose configuration\n├── docker-entrypoint.sh    # Container startup script\n└── __tests__/              # Test files\n```\n\n## Tech Stack\n\n- **Runtime**: Node.js 20+\n- **Language**: TypeScript 5.x (strict mode)\n- **Backend**: Express.js 4.x\n- **Frontend**: React 19 + Vite\n- **Database**: SQLite 3 with Prisma ORM\n- **Slack**: @slack/bolt SDK\n- **LLM**: OpenAI SDK, Anthropic SDK, Google Generative AI\n- **State Management**: TanStack Query + Zustand\n- **UI Components**: Radix UI + Tailwind CSS\n- **Testing**: Jest + Supertest\n- **Containerization**: Docker + Docker Compose\n\n## Security \u0026 Privacy\n\n- **Local First**: All data stored locally on your machine\n- **Encrypted Secrets**: API keys and tokens encrypted at rest\n- **No Cloud Dependencies**: No data sent to Threadle servers (we don't have any!)\n- **PII Redaction**: Automatically redacts sensitive information before sending to LLM\n- **Rate Limiting**: Configurable per-user rate limits\n- **Audit Logging**: All actions logged for security review\n- **HTTPS Only**: Enforced for production Slack webhooks\n- **Non-Root Container**: Docker image runs as non-root user for security\n\n## Contributing\n\nContributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.\n\n### Areas to Contribute\n\n- Additional LLM providers (Azure OpenAI, Cohere, etc.)\n- Translation style presets\n- UI/UX improvements\n- Performance optimizations\n- Documentation improvements\n- Bug fixes\n\n## Support\n\n- **Issues**: https://github.com/threadle/threadle/issues\n- **Discussions**: https://github.com/threadle/threadle/discussions\n- **Documentation**: https://github.com/threadle/threadle/wiki\n\n## Roadmap\n\n- [x] Docker image distribution\n- [ ] SaaS multi-tenant version\n- [ ] Slack App Marketplace listing\n- [ ] Microsoft Teams integration\n- [ ] Custom fine-tuned models\n- [ ] Company knowledge base integration\n\n## License\n\nMIT License - see [LICENSE](LICENSE) for details\n\n## Acknowledgments\n\nBuilt with:\n\n- [Express.js](https://expressjs.com/)\n- [React](https://react.dev/)\n- [Prisma](https://www.prisma.io/)\n- [Slack Bolt](https://slack.dev/bolt-js/)\n- [OpenAI API](https://openai.com/api/)\n- [Anthropic Claude](https://www.anthropic.com/)\n- [Google Gemini](https://deepmind.google/technologies/gemini/)\n\n## Star History\n\nIf you find Threadle useful, please consider starring the repository!\n\n---\n\nMade with care by the Threadle community\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevsigner9920%2Fthreadle","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdevsigner9920%2Fthreadle","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdevsigner9920%2Fthreadle/lists"}