A Fusabi-powered, pluggable TUI information rolodex for the terminal.
Status: Phase 0 complete — scaffolding and architecture in place. The TUI renders with dummy data; daemon starts but has no API yet. See docs/ROADMAP.md for development phases.
Scryforge unifies multiple read-mostly information streams (email, RSS, playlists, saved items, bookmarks, and more) into a single terminal interface backed by a local daemon. It is part of the raibid-labs ecosystem (Scarab, Hibana, Tolaria, Phage, Fusabi).
Scryforge follows a daemon + TUI architecture:
┌─────────────────┐ local API ┌─────────────────────┐
│ scryforge-tui │ ◄──────────────────► │ scryforge-daemon │
│ (Ratatui) │ (Unix socket / │ ("hub") │
└─────────────────┘ JSON-RPC) └─────────┬───────────┘
│
┌───────────────────────┼───────────────────────┐
│ │ │
▼ ▼ ▼
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ Provider │ │ Provider │ │ Provider │
│ (IMAP) │ │ (RSS) │ │ (Spotify) │
└─────────────┘ └─────────────┘ └─────────────┘
│
▼
┌─────────────┐
│ Sigilforge │ (separate auth manager daemon)
│ (tokens) │
└─────────────┘
- Daemon ("hub"): Manages provider plugins, handles sync/caching, retrieves auth tokens from Sigilforge, and exposes a local API.
- TUI: A Ratatui-based terminal client with explorer-style navigation (sidebars, lists, preview pane, omnibar).
- Providers: Pluggable data sources implementing capability traits (feeds, collections, saved items, etc.).
A Stream is a logical feed or collection of items:
- Email inboxes
- RSS feeds
- Spotify/YouTube playlists
- Reddit subreddits
- Bookmark folders
- Saved/liked items
An Item is an entry within a stream:
- Email message
- RSS article
- Video (YouTube)
- Track (Spotify)
- Reddit post
- Bookmark
- Task or calendar event
An Action is an operation that can be performed on an item:
- Read-only (MVP): Open, preview, copy link, open in browser, tag locally
- Write (future): Add to playlist, save/unsave, archive, mark read
Providers implement one or more capability traits:
| Trait | Description | Examples |
|---|---|---|
HasFeeds |
Lists logical feeds, retrieves items | Email inboxes, RSS, Reddit home/subs, YouTube subscriptions |
HasCollections |
Named collections with ordered items | Playlists (Spotify, YouTube), bookmark folders |
HasSavedItems |
Saved/bookmarked/liked items | Reddit saved, Medium bookmarks, YouTube watch-later |
HasCommunities |
Membership/subscriptions | Subreddits, channels, RSS feed list |
- Read-only viewing of information streams
- Providers:
- Email via IMAP (Gmail, Outlook)
- RSS feeds (including Medium via RSS)
- Microsoft To Do and Calendar (via MS Graph, read-only)
- Spotify (playlists, liked tracks)
- YouTube (subscriptions, playlists, watch-later)
- Reddit (home/subs, saved posts)
- Bookmarks (local store, optional
bukuintegration)
- TUI features:
- Explorer-style navigation (sidebar, list, preview)
- Fast filtering and search
- Omnibar / command palette
- Cross-stream views (all saved items, all feeds)
- Complex HTML email rendering
- Email composer / full write flows
- Heavy write operations (creating playlists from scratch, etc.)
- Full Gmail API (IMAP only for MVP)
- Mobile or GUI clients
scryforge/
├── Cargo.toml # Workspace root
├── crates/
│ ├── fusabi-streams-core/ # Core traits and types (Stream, Item, Actions)
│ ├── fusabi-tui-core/ # TUI event loop and state wiring
│ └── fusabi-tui-widgets/ # Reusable Ratatui widgets
├── scryforge-daemon/ # The hub daemon
├── scryforge-tui/ # The TUI client
├── providers/ # Provider crate implementations
└── docs/
├── ARCHITECTURE.md # Detailed architecture
├── ROADMAP.md # Phased development plan
└── PROVIDERS.md # Provider capability model
- Sigilforge: Auth manager daemon for token storage and refresh (referenced but not implemented here)
- Scarab: AI/agent integration layer (future integration)
- Fusabi: Plugin system powering Scryforge's extensibility
- Workspace compiles cleanly with
cargo buildandcargo clippy - TUI renders with dummy data (streams sidebar, item list, preview pane, omnibar, status bar)
- Keyboard navigation works (vim keys, Tab to switch panes,
/for search,qto quit) - Core types defined in
fusabi-streams-core(Stream, Item, Actions, Provider traits)
- Daemon starts and logs but has no API server
- TUI uses hardcoded dummy data (not connected to daemon)
- No providers implemented yet
- No configuration loading
- No caching/persistence
# Build all crates
cargo build
# Run the daemon (in one terminal)
cargo run --bin scryforge-daemon
# Run the TUI (in another terminal)
cargo run --bin scryforge-tui- Getting Started Guide - Installation, first run, and basic usage
- Configuration Guide - Complete config.toml reference
- Keybindings Reference - All keyboard shortcuts
- Commands Reference - Omnibar commands and search syntax
- Architecture - System design and implementation details
- Roadmap - Development phases and planned features
- Providers - Provider capability model and integration guide
The TUI uses vim-style keybindings for efficient navigation:
| Key | Action |
|---|---|
h/l or Tab |
Switch between panes |
j/k or ↑/↓ |
Navigate lists |
/ |
Search |
: |
Commands (:quit, :sync, :refresh, etc.) |
r |
Toggle read/unread |
s |
Save/unsave item |
? |
Show help |
q |
Quit |
See docs/KEYBINDINGS.md and docs/COMMANDS.md for complete references.
See docs/ROADMAP.md for the full development roadmap. Current priorities:
- Implement daemon API types and JSON-RPC server
- Create provider registry and caching layer
- Implement first real provider (RSS)
- Connect TUI to daemon
- Add configuration loading
The project includes comprehensive tests for TUI widgets and core state management:
# Run all tests with the recommended target directory override
CARGO_TARGET_DIR=./target cargo test --workspace
# Run tests for a specific crate
CARGO_TARGET_DIR=./target cargo test -p fusabi-tui-core
CARGO_TARGET_DIR=./target cargo test -p fusabi-tui-widgets
# Run tests with output
CARGO_TARGET_DIR=./target cargo test --workspace -- --nocapture
# Run a specific test
CARGO_TARGET_DIR=./target cargo test test_list_state_newNote: Using CARGO_TARGET_DIR=./target ensures consistent build artifact location and avoids permission issues in CI environments.
# Check formatting
cargo fmt --all -- --check
# Format code
cargo fmt --all
# Run clippy (linter)
CARGO_TARGET_DIR=./target cargo clippy --workspace -- -D warnings
# Auto-fix clippy warnings (when safe)
CARGO_TARGET_DIR=./target cargo clippy --workspace --fix --allow-dirty- Fork the repository
- Create a feature branch
- Make your changes
- Run tests:
CARGO_TARGET_DIR=./target cargo test --workspace - Run lints:
cargo clippyandcargo fmt - Submit a pull request
See docs/ARCHITECTURE.md for design details and docs/STRUCTURE.md for documentation guidelines.
MIT OR Apache-2.0