tail-fin-daemon 0.6.0

Long-running browser-session daemon for tail-fin (tfd binary). Keeps Chrome tabs warm across invocations via a Unix-socket protocol; registers Site implementations through a runtime Arc<dyn Site> registry.
Documentation

tail-fin-daemon (tfd)

tfd is an agent-friendly daemon that manages a pool of Chrome browser sessions so that multiple CLI calls and concurrent agents share tabs without opening redundant connections.

Quick Start

# Build
cargo build -p tail-fin-daemon

# Start the daemon (foreground)
tfd daemon start

# Run a business command (transparent mode — acquire/release happens automatically)
tfd sa earnings --ticker AAPL

# Run with an explicit session (skip auto acquire/release)
tfd --session <session_id> sa earnings --ticker AAPL

Commands

Subcommand Description
daemon start / stop / status Daemon lifecycle
session acquire / release / list / destroy Pool management
sa <cmd> SeekingAlpha commands
twitter <cmd> Twitter (read-only) commands
grok <cmd> Grok commands

Environment Variables

Variable Default Description
TFD_SOCKET ~/.tail-fin/daemon.sock Unix socket path
TFD_HOST 127.0.0.1:9222 Chrome CDP host:port
TFD_SESSION (none) Pin to an explicit session ID
TFD_LOG info Tracing log filter (e.g. debug, tfd=trace)

Session Modes

Transparent (default)

Each invocation automatically acquires a session in in_use mode and releases it when done. Multiple concurrent invocations for the same site share the same pool.

# Both commands share the pool; neither opens a redundant tab
tfd sa earnings --ticker AAPL &
tfd sa earnings --ticker MSFT &

Explicit session

Pass --session (or set TFD_SESSION) to bind directly to a known session ID. No acquire/release happens. Useful for long-running agent workflows that already called session acquire manually.

SID=$(tfd session acquire --site sa | jq -r .session_id)
tfd --session "$SID" sa earnings --ticker AAPL
tfd --session "$SID" sa news --ticker AAPL
tfd session release "$SID"

Architecture

See the design spec: docs/superpowers/specs/2026-04-17-tail-fin-daemon-design.md

Limitations

  • --connect only: auto-launch (stealth browser) is not supported in the current release. Chrome must already be running and listening on TFD_HOST.
  • Twitter commands are read-only (no posting).
  • Unix domain sockets only; Windows is not supported.