{
  "markdown": "# stugan\n\nA self-hosted, plugin-extensible web IRC client written in Go.\n\nstugan is a persistent daemon that holds your IRC connections 24/7 and buffers\nhistory, plus a Vue 3 browser frontend that talks to it over a typed-JSON\nWebSocket — think [TheLounge](https://thelounge.chat/), rewritten in Go, with\nthe IRCv3 discipline of [Halloy](https://github.com/squidowl/halloy) and a\n**weechat/irssi-style Lua plugin system** as the headline feature.\n\n![stugan screenshot](screenshot.png)\n\n## Features\n\n- Persistent connections that survive browser disconnects; SQLite history with\n  backlog replay and full-text search (FTS5).\n- Real-time **multi-device synchronization**: server-side settings, unsent composer drafts,\n  and accurate read marker timestamps (`draft/read-marker` / `MARKREAD`) stay in sync across all your browser tabs and IRC clients.\n- Manage networks entirely from the web UI — add, edit, connect/disconnect,\n  remove. Server password (bouncers like ZNC/soju), per-network \"perform\"\n  commands, SASL (PLAIN and EXTERNAL/CertFP).\n- IRCv3: server-time, echo-message, away-notify, account-tag, multi-prefix,\n  extended-join, message-tags, typing indicators, standard-replies, emoji\n  reactions, message redaction, draft/read-marker (MARKREAD), a channel browser (LIST), best-effort\n  chathistory. See [docs/ircv3.md](docs/ircv3.md).\n- Link previews + inline image/video via a local proxy, drag-drop/paste\n  uploads (local storage or custom upload hosts like `x0.at`), autocomplete\n  (nicks/commands/channels/emoji), command aliases, per-channel mute, a mentions\n  view, configurable highlight rules.\n- A **Lua plugin system** (weechat/irssi style): commands, message\n  filters/rewrites, signal hooks, timers, persistent KV, hot-reload.\n- PWA: installable, mobile-responsive, Web Push + desktop notifications.\n- **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.\n- **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.\n- **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.\n- Multi-user with bcrypt auth and full per-user isolation; an optional\n  site-wide password gate.\n\n## Quick start\n\n```sh\n# Build the client (the daemon serves client/dist at /).\ncd client && npm install && npm run build && cd ..\n\n# Build and run the daemon.\ngo build -o stugan ./cmd/stugan\n./stugan                      # uses $STUGAN_HOME, else ~/.config/stugan\n./stugan -home ./dev          # disposable config/data dir\n```\n\nThen open the listen address (default `http://127.0.0.1:8080`).\n\nFor live client reload, run the daemon and the Vite dev server side by side\n(Vite on :5173 proxies the WebSocket to the daemon on :8080):\n\n```sh\n./stugan &\ncd client && npm run dev\n```\n\n## Docker\n\nImages are published to GHCR (`ghcr.io/klppl/stugan`) for amd64 and arm64:\n\n```sh\ndocker run -d --name stugan -p 8080:8080 -v stugan-data:/data \\\n  ghcr.io/klppl/stugan:latest\n```\n\nConfig, history, scripts, and uploads live in the `/data` volume. Put a\n`config.toml` there with `listen = \"0.0.0.0:8080\"`; set `public_url` /\n`origin_patterns` when serving from a non-localhost host. See\n[docs/docker.md](docs/docker.md) for the full run guide (compose, reverse\nproxy + TLS, `trusted_proxies` for login throttling, auth, updates). The image is built and published by\n`.github/workflows/docker.yml`.\n\n## Configuration\n\nConfig, scripts, and data live under one root, resolved in order:\n`$STUGAN_HOME`, then `$XDG_CONFIG_HOME/stugan`, then `~/.config/stugan`. By\ndefault stugan runs single-user and unauthenticated; add `[[users]]` to require\nlogin and isolate accounts. See [docs/config.md](docs/config.md) for the full\nreference and [docs/config.example.toml](docs/config.example.toml) for a\nstarting point.\n\n## Plugins & Script Library\n\n`stugan` includes an official **Plugin Library** located in [plugins/](plugins/), packed with ready-to-use scripts:\n\n- **AI Companion & Summarizer** ([`ai.lua`](plugins/ai.lua)): `/ask <prompt>` and `/summarize [N]` using OpenAI, DeepSeek, Claude, Gemini, or Ollama.\n- **Outbound Webhooks** ([`webhooks.lua`](plugins/webhooks.lua)): Forward highlights & mentions to Discord, Slack, Ntfy, or custom HTTP webhooks.\n- **FiSH Encryption** ([`fish.lua`](plugins/fish.lua)): Blowfish CBC/ECB encryption with `/setkey` and sidebar lock indicators.\n- **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`).\n\nInstall 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.\n\nManage, configure, reload, or unload plugins directly in the Web UI under **Settings → Plugins** or via `/load`, `/unload`, and `/reload` slash commands.\n\nSee [plugins/README.md](plugins/README.md) for the plugin library catalog and [docs/plugins.md](docs/plugins.md) for the Lua API reference.\n\n## Documentation\n\n| Doc | What it covers |\n|-----|----------------|\n| [architecture](docs/layout.md) | Module/interface layout, dependency contract, data flow |\n| [core](docs/core.md) | The engine, domain types, event bus, sinks, the plugin API surface |\n| [protocol](docs/protocol.md) | The WebSocket wire protocol (envelope + every event) |\n| [irc](docs/irc.md) | The IRC layer: girc wrapping, event translation, SASL |\n| [ircv3](docs/ircv3.md) | IRCv3 capability matrix and roadmap |\n| [storage](docs/storage.md) | SQLite schema, history, search, persistence |\n| [server](docs/server.md) | HTTP/WebSocket server, multi-tenant hub, auth, security |\n| [frontend](docs/frontend.md) | The Vue 3 client architecture |\n| [theming](docs/theming.md) | Creating and installing custom themes |\n| [docker](docs/docker.md) | Pulling the GHCR image and running it on a server |\n| [plugins](docs/plugins.md) | The Lua plugin API |\n| [ssh](docs/ssh.md) | SSH Terminal UI setup and usage |\n| [bouncer](docs/ircserver.md) | Built-in IRC bouncer server (native client access) |\n| [config](docs/config.md) | Configuration reference |\n\n## License\n\nstugan is released under the [Lagom License](LICENSE) — not too much, not too\nlittle.\n</content>\n</invoke>\n",
  "bytes": 6733,
  "sha": "660bb43539cad3cfcea52ae010d5c1df2f90bdd1d6d551e420f9a8e03ddd0874",
  "repo_slug": "klppl/stugan",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/okf_klppl_stugan_openwiki_index_md_b1e02fd9/readme"
}