Stugan Knowledge Wiki
Comprehensive documentation index for the stugan codebase, covering architecture, subsystems, event flows, and plugin extensions.
Open source Repository Open in the app JSON README (API)
About
# Stugan Knowledge Wiki
Welcome to the OpenWiki knowledge repository for **stugan**, a self-hosted, plugin-extensible web IRC client written in Go with a Vue 3 frontend, SSH Terminal UI, and Lua plugin runtime.
## Quickstart
- [Quickstart & Getting Started](quickstart.md) — High-level overview, feature summary, and developer workflows.
## Architecture
- [Architecture Overview](architecture/overview.md) — System boundaries, dependency inversion, and package import rules.
- [Core Domain & Interfaces](architecture/core.md) — Central `internal/core` domain models, interfaces (`IRCConn`, `PluginHost`, `Sink`), and state encapsulation.
- [Concurrency & Event Model](architecture/concurrency_event_model.md) — The two-sided bus, serial engine loop, synchronous plugin dispatch, and Sink fan-out.
## Subsystems
- [Subsystem: Composition Root (`cmd/stugan`)](subsystems/cmd_stugan.md) — Application startup, flag parsing, multi-tenant wiring, and graceful shutdown.
- [Subsystem: IRC Protocol &
Details
- Kind
- OKF bundles
- Topic
- Productivity
- Publisher
- klppl
- Origin
- okf_github
- Category
- dados
- Version
- 0.1
- Stars
- 2
- Forks
- 3
- Last push
- 2026-09-05T20:27:41Z
- Repository state
- ativo
- Language
- Go
- License
- NOASSERTION
- Added
- 2026-09-09 05:03:59
- Updated
- 2026-09-09 05:03:59
- Origin id
klppl/stugan:openwiki/index.md
README
# stugan A self-hosted, plugin-extensible web IRC client written in Go. stugan is a persistent daemon that holds your IRC connections 24/7 and buffers history, plus a Vue 3 browser frontend that talks to it over a typed-JSON WebSocket — think [TheLounge](https://thelounge.chat/), rewritten in Go, with the IRCv3 discipline of [Halloy](https://github.com/squidowl/halloy) and a **weechat/irssi-style Lua plugin system** as the headline feature.  ## Features - Persistent connections that survive browser disconnects; SQLite history with backlog replay and full-text search (FTS5). - Real-time **multi-device synchronization**: server-side settings, unsent composer drafts, and accurate read marker timestamps (`draft/read-marker` / `MARKREAD`) stay in sync across all your browser tabs and IRC clients. - Manage networks entirely from the web UI — add, edit, connect/disconnect, remove. Server password (bouncers like ZNC/soju), per-network "perform" commands, SASL (PLAIN and EXTERNAL/CertFP). - IRCv3: server-time, echo-message, away-notify, account-tag, multi-prefix, extended-join, message-tags, typing indicators, standard-replies, emoji reactions, message redaction, draft/read-marker (MARKREAD), a channel browser (LIST), best-effort chathistory. See [docs/ircv3.md](docs/ircv3.md). - Link previews + inline image/video via a local proxy, drag-drop/paste uploads (local storage or custom upload hosts like `x0.at`), autocomplete (nicks/commands/channels/emoji), command aliases, per-channel mute, a mentions view, configurable highlight rules. - A **Lua plugin system** (weechat/irssi style): commands, message filters/rewrites, signal hooks, timers, persistent KV, hot-reload. - PWA: installable, mobile-responsive, Web Push + desktop notifications. - **SSH Terminal UI**: Access your persistent session directly over SSH via a full-screen terminal UI (Bubble Tea/Wish) with mouse support, quick-switcher, and plugin manager. - **IRC Bouncer Server**: Connect your favorite native desktop/mobile IRC clients (WeeChat, HexChat, irssi, Textual) directly to stugan with full state replay, backlog sync, and multi-network support. - **Data Portability & Backups**: One-click full user backup export and restore (.tar.gz, .zip, or raw SQLite) covering message history, network credentials, Lua plugins, and user preferences. - Multi-user with bcrypt auth and full per-user isolation; an optional site-wide password gate. ## Quick start ```sh # Build the client (the daemon serves client/dist at /). cd client && npm install && npm run build && cd .. # Build and run the daemon. go build -o stugan ./cmd/stugan ./stugan # uses $STUGAN_HOME, else ~/.config/stugan ./stugan -home ./dev # disposable config/data dir ``` Then open the listen address (default `http://127.0.0.1:8080`). For live client reload, run the daemon and the Vite dev server side by side (Vite on :5173 proxies the WebSocket to the daemon on :8080): ```sh ./stugan & cd client && npm run dev ``` ## Docker Images are published to GHCR (`ghcr.io/klppl/stugan`) for amd64 and arm64: ```sh docker run -d --name stugan -p 8080:8080 -v stugan-data:/data \ ghcr.io/klppl/stugan:latest ``` Config, history, scripts, and uploads live in the `/data` volume. Put a `config.toml` there with `listen = "0.0.0.0:8080"`; set `public_url` / `origin_patterns` when serving from a non-localhost host. See [docs/docker.md](docs/docker.md) for the full run guide (compose, reverse proxy + TLS, `trusted_proxies` for login throttling, auth, updates). The image is built and published by `.github/workflows/docker.yml`. ## Configuration Config, scripts, and data live under one root, resolved in order: `$STUGAN_HOME`, then `$XDG_CONFIG_HOME/stugan`, then `~/.config/stugan`. By default stugan runs single-user and unauthenticated; add `[[users]]` to require login and isolate accounts. See [docs/config.md](docs/config.md) for the full reference and [docs/config.example.toml](docs/config.example.toml) for a starting point. ## Plugins & Script Library `stugan` includes an official **Plugin Library** located in [plugins/](plugins/), packed with ready-to-use scripts: - **AI Companion & Summarizer** ([`ai.lua`](plugins/ai.lua)): `/ask <prompt>` and `/summarize [N]` using OpenAI, DeepSeek, Claude, Gemini, or Ollama. - **Outbound Webhooks** ([`webhooks.lua`](plugins/webhooks.lua)): Forward highlights & mentions to Discord, Slack, Ntfy, or custom HTTP webhooks. - **FiSH Encryption** ([`fish.lua`](plugins/fish.lua)): Blowfish CBC/ECB encryption with `/setkey` and sidebar lock indicators. - **Utilities & Automation**: Auto-away (`away.lua`), URL title fetchers (`title.lua`), typo sed corrections (`sed.lua`), NickServ auto-identify (`nickserv.lua`), URL tracking (`urls.lua`), nick watcher (`watch.lua`), and fun commands (`fun.lua`). Install any plugin directly from within stugan by running `/load <script-name>` in chat (e.g. `/load title`), which downloads it directly from the official repository and loads it live into the runtime. You can also drop any Lua script into `$STUGAN_HOME/scripts/*.lua` for local development. Manage, configure, reload, or unload plugins directly in the Web UI under **Settings → Plugins** or via `/load`, `/unload`, and `/reload` slash commands. See [plugins/README.md](plugins/README.md) for the plugin library catalog and [docs/plugins.md](docs/plugins.md) for the Lua API reference. ## Documentation | Doc | What it covers | |-----|----------------| | [architecture](docs/layout.md) | Module/interface layout, dependency contract, data flow | | [core](docs/core.md) | The engine, domain types, event bus, sinks, the plugin API surface | | [protocol](docs/protocol.md) | The WebSocket wire protocol (envelope + every event) | | [irc](docs/irc.md) | The IRC layer: girc wrapping, event translation, SASL | | [ircv3](docs/ircv3.md) | IRCv3 capability matrix and roadmap | | [storage](docs/storage.md) | SQLite schema, history, search, persistence | | [server](docs/server.md) | HTTP/WebSocket server, multi-tenant hub, auth, security | | [frontend](docs/frontend.md) | The Vue 3 client architecture | | [theming](docs/theming.md) | Creating and installing custom themes | | [docker](docs/docker.md) | Pulling the GHCR image and running it on a server | | [plugins](docs/plugins.md) | The Lua plugin API | | [ssh](docs/ssh.md) | SSH Terminal UI setup and usage | | [bouncer](docs/ircserver.md) | Built-in IRC bouncer server (native client access) | | [config](docs/config.md) | Configuration reference | ## License stugan is released under the [Lagom License](LICENSE) — not too much, not too little. </content> </invoke>