this repo has no description
dunkirk.sh
1# IRC <> Slack bridge
2
3This is a little bot in active development to bridge slack and irc for Hackclub!
4
5## How do I hack on it?
6
7### Development
8
9This is written in typescript so pretty easy to get started!
10
11```bash
12bun install
13bun dev
14```
15
16### Slack App Setup
17
181. Go to [api.slack.com/apps](https://api.slack.com/apps) and create a new app
192. Choose "From an app manifest"
203. Copy the contents of `slack-manifest.yaml` and paste it
214. Install the app to your workspace
225. Copy the "Bot User OAuth Token" (starts with `xoxb-`) and "Signing Secret"
236. Invite the bot to your desired Slack channel: `/invite @IRC Bridge`
24
25### Environment Setup
26
27Make a `.env` file with the following:
28
29```bash
30# Slack Configuration
31SLACK_BOT_TOKEN=xoxb-your-bot-token-here
32SLACK_SIGNING_SECRET=your-signing-secret-here
33
34# Slack workspace URL (for admin API calls)
35SLACK_API_URL=https://hackclub.enterprise.slack.com
36
37# Optional: For channel manager permission checks
38SLACK_USER_COOKIE=your-slack-cookie-here
39SLACK_USER_TOKEN=your-user-token-here
40
41# IRC Configuration
42IRC_NICK=slackbridge
43NICKSERV_PASSWORD=your-nickserv-password-here
44NICKSERV_EMAIL=your-email@example.com
45
46# Admin users (comma-separated Slack user IDs)
47ADMINS=U1234567890,U0987654321
48
49# Hack Club CDN Token (for file uploads)
50CDN_TOKEN=your-cdn-token-here
51
52# Server Configuration (optional)
53PORT=3000
54
55# Note: Channel and user mappings are now stored in the SQLite database (bridge.db)
56# Use the API or database tools to manage mappings
57```
58
59See `.env.example` for a template.
60
61### Slash Commands
62
63The bridge provides interactive slash commands for managing mappings:
64
65- `/irc-bridge-channel` - Bridge current Slack channel to an IRC channel
66- `/irc-unbridge-channel` - Remove bridge from current channel
67- `/irc-bridge-user` - Link your Slack account to an IRC nickname
68- `/irc-unbridge-user` - Remove your IRC nickname link
69- `/irc-bridge-list` - List all channel and user bridges
70
71### Managing Channel and User Mappings
72
73Channel and user mappings are stored in a SQLite database (`bridge.db`). You can manage them through:
74
75**Using Bun REPL:**
76```bash
77bun repl
78> import { channelMappings, userMappings } from "./src/db"
79> channelMappings.create("C1234567890", "#general")
80> userMappings.create("U1234567890", "myircnick")
81> channelMappings.getAll()
82```
83
84**Using SQLite directly:**
85```bash
86bun:sqlite bridge.db
87sqlite> SELECT * FROM channel_mappings;
88sqlite> INSERT INTO channel_mappings (slack_channel_id, irc_channel) VALUES ('C1234567890', '#general');
89```
90
91### How it works
92
93The bridge connects to `irc.hackclub.com:6667` (no TLS) and forwards messages bidirectionally based on channel mappings:
94
95- **NickServ Authentication**: If `NICKSERV_PASSWORD` is configured, the bridge authenticates on connect
96 - Waits for NickServ confirmation before joining channels
97 - Auto-registers the nick if not registered (requires `NICKSERV_EMAIL`)
98 - Prevents "No external channel messages" errors by ensuring proper authentication
99- **IRC → Slack**: Messages from mapped IRC channels appear in their corresponding Slack channels
100 - Image URLs are automatically displayed as inline attachments
101 - IRC mentions (`@nick` or `nick:`) are converted to Slack mentions for mapped users
102 - IRC formatting codes are converted to Slack markdown
103 - IRC `/me` actions are displayed in a context block with the user's avatar
104- **Slack → IRC**: Messages from mapped Slack channels are sent to their corresponding IRC channels
105 - Slack mentions are converted to mapped IRC nicks, or the display name from `<@U123|name>` format
106 - Slack markdown is converted to IRC formatting codes
107 - File attachments are uploaded to Hack Club CDN and URLs are shared
108- **User mappings** allow custom IRC nicknames for specific Slack users and enable proper mentions both ways
109
110The bridge ignores its own messages and bot messages to prevent loops.
111
112If you want to report an issue the main repo is [the tangled repo](https://tangled.org/dunkirk.sh/irc-slack-bridge) and the github is just a mirror.
113
114<p align="center">
115 <img src="https://raw.githubusercontent.com/taciturnaxolotl/carriage/master/.github/images/line-break.svg" />
116</p>
117
118<p align="center">
119 © 2025-present <a href="https://github.com/taciturnaxolotl">Kieran Klukas</a>
120</p>
121
122<p align="center">
123 <a href="https://github.com/taciturnaxolotl/irc-slack-bridge/blob/main/LICENSE.md"><img src="https://img.shields.io/static/v1.svg?style=for-the-badge&label=License&message=MIT&logoColor=d9e0ee&colorA=363a4f&colorB=b7bdf8"/></a>
124</p>