FAQ & Migration Guide

Answers to common questions, plus practical tips for users coming from other IRC clients.

Migration Guides

Whether you're coming from irssi, weechat, The Lounge, or mIRC, you'll find familiar concepts in kokoIRC. Here's what to expect.

>
Coming from irssi
The spiritual ancestor — most muscle memory transfers directly

What's familiar

  • Esc+1-9 window switching works identically
  • The same /commands you already know — /join, /part, /msg, /query, /nick, /topic, etc.
  • Format string theming with familiar %C, %B, %U tokens — kokoIRC extends these with 24-bit color and hex support
  • Scripting model — irssi has Perl, kokoIRC has TypeScript. The concept is the same: hook events, define commands, automate workflows
  • Status window and per-channel buffer layout
<h4>What's different</h4>
<ul>
  <li><strong>TOML config</strong> instead of <code>/set</code> — one file at <code>~/.kokoirc/config.toml</code>, not scattered runtime settings</li>
  <li><strong>TypeScript scripts</strong> instead of Perl — modern async/await, type safety, npm ecosystem</li>
  <li><strong>Built-in mouse support</strong> — click buffers, click nicks, drag to resize panels</li>
  <li><strong>SQLite logging</strong> with FTS5 full-text search instead of plain text files</li>
  <li><strong>Single binary</strong> — <code>bun build</code> produces one executable, no system packages or cpan modules</li>
  <li><strong>TOML themes</strong> instead of <code>/format</code> commands — structured, version-controllable theme files</li>
</ul>

<div class="migration-tip">
  <strong>Tip:</strong> Your irssi aliases map directly. Add <code>wc = "/close"</code> and <code>j = "/join"</code> to the <code>[aliases]</code> section in config.toml. The <code>autosendcmd</code> option replaces irssi's autosendcmd with the same semicolon-separated syntax: <code>"MSG NickServ identify pass; WAIT 2000; MODE $N +i"</code>
</div>
>
Coming from weechat
Similar philosophy, simpler config, modern stack

What's familiar

  • Plugin/script model — weechat's extension system maps to kokoIRC's TypeScript scripting API
  • Buffer list in the left panel with network grouping
  • Nick list in the right panel with mode prefixes (@, +)
  • Customizable status bar showing current nick, channel, modes, and lag
<h4>What's different</h4>
<ul>
  <li><strong>TypeScript only</strong> — no Python, Lua, Ruby, or Guile. One language, full type safety, modern tooling</li>
  <li><strong>One TOML file</strong> instead of weechat's many config files (<code>weechat.conf</code>, <code>irc.conf</code>, <code>buflist.conf</code>, etc.)</li>
  <li><strong>TOML themes</strong> instead of <code>/set weechat.color.*</code> — structured color definitions with 24-bit support</li>
  <li><strong>No relay protocol</strong> (yet) — web UI is on the roadmap, sharing the same Zustand state store</li>
</ul>

<h4>Why switch</h4>
<ul>
  <li><strong>Built-in encrypted logging</strong> with AES-256-GCM per-message encryption</li>
  <li><strong>FTS5 full-text search</strong> across all channels and queries — <code>/log search</code> finds anything instantly</li>
  <li><strong>Single binary deployment</strong> — no compilation from source, no dependency management</li>
  <li><strong>Modern React UI engine</strong> under the hood — smooth rendering, proper Unicode, truecolor everywhere</li>
</ul>
>
Coming from The Lounge
Terminal-first, with web UI coming next

What's familiar

  • Multi-network support — connect to as many servers as you need simultaneously
  • Persistent history — messages survive restarts, stored in SQLite
  • Modern feel — a client designed in the 2020s, not the 1990s
<h4>What's different</h4>
<ul>
  <li><strong>Terminal-first</strong> — kokoIRC is a terminal application (web UI coming in the next phase, same aesthetics)</li>
  <li><strong>TypeScript scripting</strong> — The Lounge has no scripting API; kokoIRC lets you automate anything</li>
  <li><strong>Format string theming</strong> — deep control over every line of output, not just CSS variables</li>
  <li><strong>Encrypted logs</strong> — optional AES-256-GCM encryption for your message history</li>
</ul>

<h4>Why switch</h4>
<ul>
  <li><strong>Web UI is on the roadmap</strong> — the Zustand store is already UI-agnostic, built for 1:1 terminal/web sync</li>
  <li><strong>Scripting</strong> — automate flood protection, custom commands, integrations, anything you can write in TypeScript</li>
  <li><strong>Better logging</strong> — SQLite WAL with FTS5 search, optional encryption, configurable retention</li>
  <li><strong>Single binary</strong> — deploy by copying one file, no Node.js server to maintain</li>
</ul>
>
Coming from mIRC
Modern, open source, cross-platform replacement

What's familiar

  • Channel windows — each channel gets its own buffer, just like mIRC's MDI windows
  • Nick list — right-side panel showing channel members with mode prefixes
  • The same /commands — /join, /part, /msg, /nick, /kick, /ban, etc.
  • Aliases — define shortcuts for common commands in the [aliases] config section
<h4>What's different</h4>
<ul>
  <li><strong>Cross-platform</strong> — runs on macOS, Linux, and Windows (anywhere Bun runs). Not Windows-only</li>
  <li><strong>Terminal-based</strong> — no GUI dialogs or toolbars. The interface is a terminal with keyboard and mouse</li>
  <li><strong>TOML config</strong> instead of dialog boxes — edit <code>~/.kokoirc/config.toml</code> in any text editor</li>
  <li><strong>TypeScript scripting</strong> instead of mIRC scripting language — modern, well-documented, vast ecosystem</li>
</ul>

<h4>Why switch</h4>
<ul>
  <li><strong>Open source</strong> and MIT licensed — free forever, no shareware nag screens</li>
  <li><strong>Modern scripting</strong> — TypeScript with full npm ecosystem vs. mIRC's proprietary scripting language</li>
  <li><strong>Encrypted logging</strong> — AES-256-GCM per-message encryption, not plaintext log files</li>
  <li><strong>Cross-platform</strong> — use the same client and config on all your machines</li>
  <li><strong>Active development</strong> — web UI, mobile support, and more on the roadmap</li>
</ul>

Frequently Asked Questions

▶ What are the system requirements?
Bun v1.2+ and a terminal with 256-color or truecolor support. That's it. kokoIRC runs on macOS, Linux, and Windows. For the best experience, use a modern terminal emulator like iTerm2, Alacritty, kitty, WezTerm, or Windows Terminal.
▶ Where is the config file?
~/.kokoirc/config.toml — created automatically on first run with sensible defaults. Edit it with any text editor. See the Configuration page for full documentation.
▶ Where are logs stored?
~/.kokoirc/logs.db — a SQLite database with WAL mode and FTS5 full-text search. Use /log search <query> to search across all channels and queries. See the Logging & Search page for details.
▶ Can I use kokoIRC on Windows?
Yes. Bun runs on Windows, and kokoIRC works in any terminal that supports 256 colors. Use Windows Terminal for the best color and Unicode support. The classic cmd.exe will work but with limited color rendering.
▶ Can I run multiple connections?
Yes. Add multiple [servers.*] sections in your config.toml. Each server gets its own set of channels and settings. For example, you might have [servers.libera] and [servers.oftc] running simultaneously, each with their own channels, nick, and SASL credentials.
▶ Does it support SASL?
Yes. Set sasl_user and sasl_pass in your server configuration block. SASL PLAIN authentication is performed automatically during connection. Keep credentials in ~/.kokoirc/.env and reference them with environment variable syntax for better security.
▶ Does it support TLS?
Yes. Set tls = true in your server config. TLS is enabled by default for port 6697. Certificate verification is controlled with tls_verify = true (also the default). You can use any standard IRC server with TLS support.
▶ How do I search chat history?
Use /log search <query> from any buffer. The FTS5 full-text search index covers all logged messages across all channels and queries. You can search by keywords, nick, or phrases. Results are displayed inline with timestamps and context.
▶ Can I encrypt my logs?
Yes. Set encrypt = true in the [logging] section of your config. Messages are encrypted with AES-256-GCM on a per-message basis. The encryption key is derived from your configuration. Even with encryption enabled, FTS5 search continues to work over the plaintext index columns.
▶ How does image preview work?
kokoIRC detects your terminal's graphics capabilities and uses the best available protocol: kitty (kitty, ghostty, WezTerm), iTerm2, sixel (foot, contour, konsole), or Unicode half-block symbols as a fallback. Click an image URL in chat or use /preview <url>. Works through tmux with automatic DCS passthrough. Configure with /set image_preview.protocol auto|kitty|iterm2|sixel|symbols. See the Image Preview page for details.
▶ How do I write scripts?
Create .ts files in ~/.kokoirc/scripts/. Scripts are TypeScript modules that import from the kokoIRC API. You can hook IRC events, define custom commands, and interact with the full IRC protocol. See the Scripting guide for a complete walkthrough.
▶ How do I report bugs?
Open an issue on GitHub: github.com/kofany/kokoIRC/issues. Include your kokoIRC version, OS, terminal emulator, and steps to reproduce the issue.
▶ How do I contribute?
Fork the repository, make your changes, and submit a pull request. The codebase is TypeScript with a clean separation between src/core/ (IRC logic) and src/ui/ (React terminal components). See the architecture section in the README for an overview.
▶ Is kokoIRC free?
Yes. kokoIRC is open source and released under the MIT license. Free to use, modify, and distribute.