Futon

Một terminal manga reader viết bằng Go — render manga trực tiếp trong terminal qua Kitty Graphics Protocol hoặc Sixel, không cần mở app xem ảnh riêng. Search từ nhiều nguồn, browse chapters, đọc với Vim-style keys.

Preview

Highlights

• Render ảnh trong terminal — Kitty hoặc Sixel, auto-detect
• Multi-source search — OTruyen, MangaDex, TruyenQQ, FoxTruyen, BaoTangTruyen (chọn nguồn qua /src)
• Favorites & History — Bookmark truyện, resume từ trang đã đọc
• Filter trong fav/his/src — Gõ chữ để lọc danh sách real-time
• Save ảnh — ctrl+d để download trang hiện tại
• Preload chapter — Chuyển chapter mượt, zero waiting
• LRU image cache — 20 ảnh cached, flip page ko cần re-render
• Quick jump — Gõ số chapter + enter
• Language filter — /lang vi hoặc /lang en cho MangaDex
• Vim-style navigation — Arrow keys, h/l, number jump

Tài liệu

• SPEC.md — product requirements, scope, keybindings, Definition of Done
• ROADMAP.md — lộ trình phát triển, tech debt, backlog
• TASKS.md — trạng thái công việc hiện tại
• AGENTS.md — kiến trúc & conventions cho contributors

Yêu cầu

Terminal cần support Kitty Graphics Protocol hoặc Sixel:

Terminal	Protocol
Kitty	Kitty (native)
WezTerm	Kitty + Sixel
Ghostty	Kitty + Sixel
foot	Sixel
iTerm2	Sixel
Konsole	Sixel
mlterm	Sixel
XTerm	Sixel (compile với --enable-sixel)

Kitty protocol nhanh hơn. Nếu terminal support cả hai, Futon tự động ưu tiên Kitty.

Cài đặt

Auto (recommended)

curl -sSL https://raw.githubusercontent.com/KabosuNeko/Futon/main/install.sh | bash

Gỡ cài đặt:

curl -sSL https://raw.githubusercontent.com/KabosuNeko/Futon/main/install.sh | bash -s -- uninstall

Build từ source

go install github.com/KabosuNeko/Futon@latest

Binary

Tải bản mới nhất từ Releases.

Hỗ trợ:

• Linux (amd64, arm64)
• macOS (amd64, arm64)

Cách dùng

futon

Keybindings

Search screen

Key	Action
ctrl+c	Thoát
enter	Search / mở truyện đang chọn
↑ / ↓	Di chuyển list
/fav	Xem favorites
/his	Xem history
/src	Chọn nguồn (space để toggle)
/lang vi|en	Set ngôn ngữ chapter (MangaDex)

Khi ở màn hình /fav, /his, hoặc /src: gõ chữ để lọc danh sách.

Favorites / History

Key	Action
enter	Mở truyện
ctrl+d	Xoá khỏi list
esc	Quay lại search

Chapter list

Key	Action
↑ / ↓	Browse chapters
ctrl+f	Toggle favorite
enter	Mở chapter
[number] + enter	Jump tới chapter
esc	Quay lại search
ctrl+c	Thoát

Reader

Key	Action
→ / l	Trang tiếp
← / h	Trang trước
ctrl+d	Save trang hiện tại
esc	Về chapter list
ctrl+c	Thoát

Data

Gì	Ở đâu
Favorites + Sources	~/.config/futon/userdata.json
Reading history	~/.config/futon/history.json
Ảnh đã download	~/Downloads/Futon_Downloads/

Architecture

cmd/main.go            — entry point
internal/
  api/                 — MangaProvider interface & HTTP clients
    provider.go        — interface + shared helpers, tea.Msg types
    source.go          — tea.Cmd wrappers (Search, GlobalSearch, Fetch*)
    otruyen.go         — OTruyen provider
    mangadex.go        — MangaDex provider
    truyenqq.go        — TruyenQQ provider
    baotangtruyen.go   — BaoTangTruyen provider
    foxtruyen.go       — FoxTruyen provider
  models/              — shared types (manga, chapter)
  storage/             — local JSON persistence
    userdata.go        — UserData (favorites + sources merged)
    sources.go         — Load/SaveSources → delegates to userdata
    favorites.go       — Load/SaveFavorites → delegates to userdata
    history.go         — per-manga reading history
  tui/                 — Bubble Tea screens
    app.go             — state machine: search → chapters → reader
    search*.go         — search screen (model, keys, cmd, view)
    chapter*.go        — chapter list (model, view)
    reader*.go         — reader (model, keys, msgs, cache, nav, view, download)
    flash.go           — flash message utility
    imgrender/         — Kitty / Sixel renderer

License

MIT