fedtail Documentation on fedtail

Getting Started

Mon, 01 Jan 0001 00:00:00 +0000

Every fedtail release ships as a self-contained single file with Python and Qt bundled inside — no extra dependencies needed.

Method 1. Single Binary, No Installation (Recommended)

Linux (x86_64)

Debian 12 or newer, Ubuntu 22.04 or newer and the like. The commands are for the latest release, 0.16.0:

# Download and make it executable:
curl -LO https://github.com/eugene-vereshchagin/fedtail/releases/download/v0.16.0/fedtail-0.16.0-linux-x86_64
chmod +x fedtail-0.16.0-linux-x86_64

# put it in the menu with its icon (and exit), then run it
./fedtail-0.16.0-linux-x86_64 --install-desktop
./fedtail-0.16.0-linux-x86_64

fedtail features

Mon, 01 Jan 0001 00:00:00 +0000

As of version 0.17.0 (in progress). This is the full list of fedtail’s features: what each one does, what turns it on and off, since which version it’s there, which API or protocol it stands on and how other clients do the same. The plans are here too, and what was turned down, with the reasons.

Configuration reference

Mon, 01 Jan 0001 00:00:00 +0000

Every key of the config, in tables by chapter.

Which feature stands behind a key and how other clients do it — the feature list.

How the config works

Every setting is here, with its default value and an explanation. Change what you need and restart fedtail. The program only reads this file and never writes it.

fedtail and other clients

Mon, 01 Jan 0001 00:00:00 +0000

The features of the full list, as one matrix a chapter: whether other clients have the same. ✓ they do, empty — they don’t or it’s unknown. From their READMEs and release notes (autumn 2026) and general knowledge, without trying each one live; the details and remarks are in the “Others” column of the full list.

Changelog

Mon, 01 Jan 0001 00:00:00 +0000

Every release, newest first. The files of each one are on the releases page.

0.16.0 — 2026-10-19

Faster reading deep into big lanes: stored posts are paged from where the last page ended instead of skipping the newer ones again each time, and text is pulled out of a post’s HTML with patterns compiled once. Ctrl+F “in every lane” goes through lanes that share a source together, each post parsed and matched once — on 20 000 stored posts it takes 0.4 s instead of 0.9 s; “Deeper” and long lanes gain the same way.
A click on the time slider of a video or an audio jumps right there; it used to move only one step towards the click, and only dragging the handle really seeked.
Sending no longer gives up after 30 seconds on a slow server: it waits post.send_timeout (90 s). When the answer still doesn’t come, fedtail looks among your latest posts first — the post was usually made, only the answer lost — and treats it as sent if it’s there. If it can’t tell, the message says “maybe sent: look before retrying” instead of a raw “Read timed out”. Each post carries an Idempotency-Key: Mastodon gives back the post already made instead of a double when the same text is sent again.
Ctrl+F “In every lane”: a tick in the find bar searches everything stored in every lane at once; the counter says which lane the match is in, and the next match opens its lane and loads it down to the post. Ctrl+F pressed again in the find bar goes to the next match, as in a browser (Enter, ↓ and F3 still do too).
The point theme closer to point.im: square avatars, the name bold in dark blue with @address · date under it, the post’s #id under the text on the left with the number of replies (#a3f | 4), the buttons on the right, a hatched grey band behind the lane’s and the new post’s title, solid and clearer lines between posts, a dark “Create” button. New theme keys for any theme: shape.avatar_shape (circle, square, rounded), shape.card_header = "stacked", shape.short_id (header, footer), shape.actions_align (left, right), shape.rule (solid, dashed), shape.header_stripes, shape.header_bar (a band above the title strip, point.im’s dark top bar), colors.primary / on_primary, colors.header, colors.header_bar, colors.name.
The lane’s and the new post’s title strip is tinted with the theme’s accent in every theme (colors.header left at “auto”), with a 3 px band of the accent above it (shape.header_bar, 0 turns it off); bnw and contrast keep a white strip under the band. Lines between posts in “rule” style are solid by default (terminal keeps its dashes).
“Add to list” for someone you don’t follow: the lists are dead now, not just greyed — a click on them does nothing at all (it used to send a request the server refused and stall the window). While fedtail is still asking the server whether you follow them, the lists are dead too, with “Checking…” above them, instead of looking clickable.
Video is decoded by the processor by default (ui.video_decode = "software"): on some cards Qt’s hardware decoding fails (“CUDA_ERROR_INVALID_VALUE”, “more than 32 decode surfaces”) and the video stutters or stalls. "hardware" brings the old way back.
The opossum is gone from the icon and About: it comes from an official Telegram sticker pack, and its artist says the rights are Telegram’s, not theirs to give. The drawn thread bubble is the icon again (in the theme’s colours with ui.themed_icon); ui.app_icon is gone with it.
“Activity” counts as seen what came on screen, like the other lanes, checked when you scroll or come back to the window. It used to mark everything once, on opening — rows far off screen too — and a window in the background at that moment left the newest unread for good.
The debug theme: for finding what’s wrong, not for reading. Each state of a post in a loud frame of its own — unread, “on screen but not all of it yet” (not counted read yet), the j/k cursor, what Ctrl+F found, the post you came to — plus the keyboard focus and disabled buttons. shape.debug = true turns the same on in any theme of your own.
“Copy handle”: a button in a profile, “Copy handle @…” in a post’s ⋯ menu (the author, and the booster of a boost) and on the “boosted by” line. Always the full @user@server — people of your own server come as a bare user, your server’s name is added.
⋯ → “Call into the thread…”: a reply to that post with only “@” in it and the people list open — pick who, add a word, send. They get a notification and open the thread at home; no links with service ids. The thread’s others aren’t mentioned; the call has its own draft. post.invite = false hides the item.
≡ → Debug → “Federation status”: how your server is doing — what it runs, how many answers and how fast, polls and the live stream — and what keeps failing that isn’t the client’s doing: what the server can’t do, who waits to go into a list, and every request that keeps getting 404/410/401/timeouts, on your server and on other servers, grouped (ids folded), counted, with when it last happened and what it most likely means. Live while open; “Copy” as text for an issue; “Count anew”. Only what this run saw: nothing is asked of the network for it, no queries or tokens are kept.
Federation status: who waits to go into a list is named (my server is asked who an id is when no post of theirs is here), linked to their profile in a tab, with why they wait — a follow request unanswered, not followed (refused or withdrawn), or followed and going in with the next refresh.
A slow answer about direct conversations no longer fails the whole poll (“Read timed out” on screen, the lanes not fetched): it is only a nicety, skipped till next time.
Someone waiting to go into a list is tried only once they’re followed; while the follow request waits nothing is asked, and once it’s refused or withdrawn they’re let go. (A refused follow was retried with a 404 every ten minutes, for a month.)
What the server hasn’t got — blocked domains on GoToSocial, the notification policy — is asked once a run, not on every silence refresh. Muted and blocked lists no longer ask for an empty second page.
A post’s ⋯ menu is built when it opens, not with every card: two dozen actions and submenus per card were most of a lane’s widgets and of its drawing time; what it shows (unread, subscribed, pinned) is how things are at that moment.
The log’s trend line gives the rate over the whole session beside start → now (and the last minutes apart): 245 → 763 MB over a night read “+1950/h”, the rate of three minutes.

Testing and Bug Reports

Mon, 01 Jan 0001 00:00:00 +0000

Thanks for trying out fedtail! It is currently in active beta, and user feedback is essential to track down edge cases and fix breakages quickly.

What to Check First

Tree-view Threads. Open any conversation (click the “Thread” button or click on a post timestamp): it renders as an indented tree with comment numbers /1 /2 …. Responses your home instance never received are fetched directly from the author’s server via ActivityPub after a brief moment.
Nothing Lost. Press Esc to close lanes and leave the app running overnight. In the morning, unread badges appear on the left, and opening a lane resumes at your exact previous position.
Replies and Thread Subscriptions. Click “Subscribe” above a thread or run S #abc in the bottom command line: new comments in followed discussions show up even if you weren’t directly mentioned.
Notifications. Test system notifications via Menu ≡ → “Debugging” → “Send a test notification”.
Command Line. Focus the bottom prompt with Ctrl+L (enter ? for help) to experience Point.im-style rapid interaction.
Multiple Accounts. Right-click your avatar in the status corner to switch between isolated profiles.
Themes. Customize colors and appearance via the ui.theme key in config.toml.

Reporting an Issue

If you encounter a bug or unexpected behavior:

Architecture & Design

Mon, 01 Jan 0001 00:00:00 +0000

fedtail is engineered for people who value conversation context, non-jumping chronological timelines, and complete discussion threads.

Foundational Principles

Nothing jumps. Opening a lane places you at the first unread post. New arrivals never push what you are currently reading. You consume feeds in order, just like RSS.
Every reply knows its parent. A quote strip above each response shows the origin post; a single click expands the entire tree.
Lanes are segregated. People, bots, direct replies, and mentions are cleanly partitioned into distinct feeds.
Private by default. New posts target followers only. Replies never exceed the visibility level of the parent note.
Config-driven. Every behavior is governed by explicit settings in config.toml rather than GUI preference dialogs.
No client tokens sent to third-party instances. Missing thread data fetched via ActivityPub is retrieved anonymously without leaking user tokens.
Headless core. The application engine is fully decoupled from presentation. Frontends (Qt, TUI, Web) interact via events and futures.
One profile per account. Profiles remain isolated; multiple profiles can be switched easily or merged into a single window.
No patronizing moderation (arts mode). In tribute to @arts (founder of Point.im), content is presented as-is with full user agency.

Architectural Components

Core Engine (fedtail/core): Headless orchestration of networking, storage, polling, and event dispatch.
Data Persistence: Local SQLite database storing cached status entities, thread graph relationships, read markers, and subscriptions.
Thread Reassembly: Fetches missing conversational branches directly from origin author instances when home servers lack federated context.
Frontends (fedtail/frontends):
- qt: Native desktop UI built on PySide6.
- tui: Terminal text-mode interface.
- web: Embedded lightweight browser interface.
- cli: Scriptable terminal commands (fedtail tail, fedtail show, etc.).

Coming in 0.17.0

Mon, 01 Jan 0001 00:00:00 +0000

Not released yet: this is the 0.17.0 section of the changelog as of today. The latest release is 0.16.0. Things may still change before it’s out.

fedtail --layout single|columns|qip and --theme NAME: the layout or the theme for one run, the config untouched.
Five themes in the spirit of messengers, for ui.layout = "qip" above all: qip-retro (QIP Infium’s pale blue), qip-modern (QIP 2012, flat), mra and mra-blue (the Mail.ru Agent’s orange and blue), psi. They write a post as a message: “Name (15:25:43 23/06/2007)” over it, mine and the others’ in colours of their own — shape.card_header = "chat", colors.chat_me / chat_them, words.chat / chat_date for any theme. Their icons and colours are fedtail’s own, not anyone’s skin.
Help gets a “Server and federation” part under its contents: About the server, What it can do (the probe) and Federation status open on its right side, as pages of the same panel — the settings-like window of Psi or QIP, only for what to read, not to set (settings stay a file).
ui.layout = "qip", the first step of a messenger-style layout (docs/LAYOUTS.md): the lanes in a narrow roster window of their own, as in QIP, Psi or the Mail.ru Agent — who I am and what’s new in Activity on top, a search line, the lanes in folding groups “▾ Personal (2/9)” (with something new / all), each with its count, a line of its newest post and its author’s face. A click opens the lane in the main window, which here is the messages window, without the sidebar. Closing the roster closes fedtail (to the tray with ui.close_to_tray); ui.roster_on_top. Followed threads and private talks stand there as contacts of their own (“Threads”, “Talks”, the freshest ui.roster_threads): who began it and how, or who is in it.
fedtail took GoToSocial 0.22 for Mastodon: its version says only “0.22.1+git-…”. Now it reads the instance document’s source_url and GoToSocial’s own keys, and asks the server’s nodeinfo when still unsure — so × in Activity hides here instead of asking the server, and the probe says right what GoToSocial can’t. Translating is read from the newer instance document (Mastodon said “no” before when it could).
Server info → What it can do: “Copy” (a Markdown table, for a bug report or a chat), “Save…” to a file, Ctrl+C copies the selected rows.
≡ → Server info has a “What it can do” tab: “Check” asks the server about two dozen features with harmless one-item GETs (a few seconds, in the background) and lists yes / no / closed to me / unclear, with the limits; the last check is kept. The answers also decide which buttons fedtail offers.
Help: in the comparison tables the header row stays on top while the rows scroll under it, so a ✓ always says whose it is.
Every built-in theme comes with its fonts (all SIL OFL 1.1, all with Cyrillic, nothing to install): PT Serif in paper, IBM Plex Mono in terminal, IBM Plex Sans in nord, Source Sans 3 and Source Code Pro in night and solarized, Open Sans in point, Arimo in juick, Comfortaa and Nunito in pink, PT Sans in contrast, Fira Mono in bnw where DejaVu is missing. ui.fonts chooses whose: the theme’s (default), the system’s, or your own (ui.font, ui.mono_font — any of these by name too).
× on a row of Activity on GoToSocial: the server can’t dismiss one notification (only clear them all), and fedtail used to ask it anyway — a 404 in the log, the row stayed, and “Clear” went missing until a restart. Now × hides the row here (and stays hidden after the next fetch); on Mastodon it goes from the server too. It never mutes anything: new ones of the kind come as before. The tooltip says which it is.
Fonts of your own: ui.fonts = "custom" with ui.font (a list works: the first one there), ui.mono_font for #ids. Fonts needn’t be installed: .ttf / .otf in ~/.config/fedtail/fonts/ are picked up at start, and a theme can bring its own ([font] files, next to its .toml).
Muting a thread works on GoToSocial: the server can’t, so fedtail mutes it itself — the thread’s mentions are dropped as they come (replies there tag everyone in the thread by themselves), even replies under posts fedtail never saw, and what came before leaves the lanes. It used to say “Your server can’t do that” and hide the item; now the item is always in the ⋯ menu, and on Mastodon it asks the server as well.
Reply with quotes: ⋯ → “Reply with quote” puts the post (or what’s selected in it) into the reply as a > quote; a right click on selected text → “Quote in reply”. With the reply already open the quote goes where the cursor is, so a long post can be answered sentence by sentence without copying. post.quote_prefix.
Web: the ≡ menu (write, my profile, refresh, all read, help, keys, about) and a post’s ⋯ menu (reply with quote, subscribe / leave / mute the thread, copy the link, delete my post); q replies with a quote. A reply shows the whole post it answers: select a piece, “❝ Quote in reply” puts it at the cursor. The picture viewer goes through the post’s pictures with ← / → and the side buttons.
Terminal interface: p shows the profile for real — the screen used to scroll its header away as the first post was highlighted, and what stayed looked like a lane. Lanes by keyboard: [ / ], 1…9, h into the lane list (j / k move there), l back; Tab now really goes between lanes and posts. “Activity” and “Follow requests” show their rows (they were empty: they aren’t post lanes); a / d answer a request. Pictures drawn with half blocks: a post’s first one small in the lane (tui.pictures, tui.picture_rows), v — all of them full screen, ← / →, o — the original in the browser. Needs Pillow (python3-pil).
Unsubscribing from a thread mutes its mentions too (subs.leave_mutes, on): leaving used to stop “Subscriptions” only, while auto-tagged replies kept coming.
The opossum holding its own tail is back: the app’s icon (ui.app_icon) and the picture in About. It is a sticker from an official Telegram sticker pack.
The config’s reference comes in English too: config.example.en.toml lies next to config.example.ru.toml (the old config.example.toml goes). A new config is written in the desktop’s language; --update-config and --rebuild-config keep the language your file is in.
Help inside: ≡ → “Help” opens it as a panel over the lanes, like the compose panel — the contents on the left, search through it all, Back and Forward. Short pages, each ending in “In detail →” links into the full feature list and the settings reference, which come with it and work offline. In Russian and in English.
≡ → “What’s this?”: point the mouse at a button and get the longer story — what it does, which config key changes it, where the help says more. For the session from the menu, or from the start with ui.whats_this. Neither has a key: F1 is next to Esc. The hint is a window of its own, beside the cursor and never under it: a long Qt tooltip there was hidden and shown again round and round until the window froze.
The docs come in Russian and English, docs/ru/ and docs/en/: the feature list now says since which version each feature is there, and fedtail next to thirteen other clients is one matrix a chapter (comparison.md). All of it, the config reference and the shared pieces of the READMEs are built by tools/docs_build.py; a test keeps them in step.
The database no longer grows for ever. Every storage.gc_hours (6) fedtail forgets posts nothing points at any more — no lane, followed thread, activity entry or reply draft; boosted and quoted posts and parents of kept ones up the thread stay, and so do your own posts and anything stored in the last storage.grace_hours (48). A forgotten post is fetched again when needed; short ids are kept for good. The file really shrinks (incremental vacuum; an older file is converted once, at the first start — it may take a moment). If it is still over storage.max_mb (1 GB), lanes get shorter until it fits and grow back later. New [storage] options; storage gc: lines in the log.
Pictures that didn’t come no longer stay blank until a restart. When the server answered with an error twice (busy, restarting, still fetching a remote post’s media), fedtail asks again by itself in 1, 5 and 30 minutes for the cards still waiting, and a card that gave up gets the picture when it comes. The log now says the HTTP status (“HTTP 503”) instead of just “HTTPError”.
The web interface, rebuilt: a “Write” button (and ✎ on a phone) opens a composer with a content warning, who sees it, the language and a character count; drafts are kept in the browser. Replies start with the right @names and never go wider than what they answer. Pictures in a grid with a viewer, video, gifs and audio; a picture that doesn’t come says so, links to the original and is tried again later. Polls with bars and voting, link cards, quotes, custom emoji, a profile’s header, fields with ✓ verified, follow / requested. “More” at the end of a lane loads older posts. The command line has a line of its own. Lanes slide in on a phone; light and dark follow the system.
Inside: the terminal, the TUI and the web interface work on fedtail’s own data model (fedtail/model, fedtail/core/view.py) instead of the server’s JSON — stage 2 of docs/PROTOCOLS.md; so does the Qt window, all of it. The Mastodon API itself lives in fedtail/protocols/mastodon/ behind a protocol interface (stage 3), and what the server can do is kept in one place (stage 4): a button the server refuses goes at once, and stays gone after a reconnect. Nothing changes in what they show, except that the web page and fedtail post -v say “followers” (private still works).