discordo-plus/CLAUDE.md

Project Context

What This File Is

This is the persistent context file for Claude Code. Keep it concise and useful.

CLAUDE.md Maintenance Rules

• Keep this file under 160 lines
• Only record decisions, not explanations of common knowledge
• When adding something, check if anything existing is now outdated and remove it
• Use short bullet points, not paragraphs
• No boilerplate or filler text
• If a section grows past 10 items, consolidate or prune the least relevant ones
• Format: what we chose + why in one line (e.g., "imv over feh — WebP/Wayland support")

Overview

• Fork of ayn2op/discordo — a Discord TUI client
• Upstream: https://github.com/ayn2op/discordo.git
• Our repo: https://gogs.altsol.dev/claude/discordo-plus.git (branch: master)
• Binary name: discordo-plus (installed to /usr/local/bin/)

Stack

• Go (module: github.com/ayn2op/discordo)
• TUI: github.com/ayn2op/tview (custom tview fork) + tcell/v3
• Discord API: arikawa/v3 + ningen/v3 (state management + Discord markdown)
• Markdown: goldmark parser + chroma/v2 syntax highlighting
• Config: TOML via BurntSushi/toml, file at ~/.config/discordo/config.toml
• Cache: ~/.cache/discordo/ (attachments, logs)

Architecture

• main.go → cmd/root.go (app init) → internal/ui/ (TUI layers)
• internal/ui/chat/ — core chat UI: messages_list.go (1500+ lines, message rendering/keybinds), message_input.go, guilds_tree.go, attachments_picker.go
• internal/markdown/renderer.go — AST→styled lines, handles Discord markdown flavors
• internal/config/ — config.go (struct + loader), config.toml (defaults, embedded), keybinds.go, theme.go
• internal/consts/ — app name, cache dir
• Rendering pipeline: messages → tview.LineBuilder → []tview.Line (segments with tcell.Style)
• URLs get style.Url(rawURL) metadata for OSC 8 terminal hyperlinks
• External commands (editor, image viewer) use app.Suspend() pattern — suspends TUI, runs command, resumes

Key Patterns

• Keybinds: defined in config/keybinds.go structs, matched in HandleEvent() via keybind.Matches()
• Help tooltips: ShortHelp() (bottom bar, contextual) and FullHelp() (full overlay via ctrl+.)
• Attachments: downloaded to ~/.cache/discordo/attachments/, opened via configured viewer or open.Start()
• Embeds: rendered with ▎ bar prefix, wrapped to viewport width, markdown in descriptions
• Config defaults embedded via //go:embed config.toml

Our Changes (vs upstream)

• Image viewer: image_viewer config (default: mpv) — opens image attachments in configured viewer with TUI suspend/resume instead of browser
• mpv geometry: viewerArgs() auto-detects terminal geometry via xdotool on X11, passes --geometry, --force-window, --loop-file=inf to mpv
• Save image: save_image keybind (S) — saves image attachment to image_save_dir
• Attachment URL fix: split builder.Write(filename+"\n"+url) into proper NewLine() + .Url() style
• Supported image types: jpeg, png, webp, gif (via supportedImageTypes map)
• ShortHelp: o (open) now shows in bottom tooltip bar when message has attachments/URLs

Config Fields We Added

• image_viewer — external image viewer command (default: "mpv", "default" = system opener)
• image_save_dir — directory for saved images (supports ~/, default: current dir)
• keybinds.messages_list.save_image — save image keybind (default: S)

Build & Run

• Build: go build -o discordo-plus .
• Install: sudo mv discordo-plus /usr/local/bin/
• Run: discordo-plus
• Test: go test ./... (only config + keyring packages have tests)
• Dependencies: mpv (or configured image viewer), xdotool (optional, X11 geometry detection)

Git

• Identity: claude <claude@altsol.dev>
• Commit style: type(scope): description (e.g., feat(ui/chat): add image viewer)
• Branch: master

Known Issues

• Discord ToS discourages third-party clients — use at own risk
• xdotool geometry detection only works on X11; on Wayland use compositor window rules for mpv positioning
• viewerArgs() only adds special flags for mpv; other viewers get plain viewer path invocation