# 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

```bash
# 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 quote AAPL

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

## Commands

| Subcommand | Description |
|---|---|
| `daemon start / stop / status` | Daemon lifecycle |
| `session acquire / release / list / destroy` | Pool management |
| `<site> <cmd>` | Business commands for every registered site (run `tfd --help` for the generated list) |

Browser sites (sa, twitter, grok, reddit, shopee, spotify, …) drive a pooled
Chrome session. **Pure-HTTP sites (arkham, alphora, gemini, nansen, tradingview, 591) build no browser at
all** — their sessions are descriptor executors over plain HTTP, so `acquire`
is instant and needs no Chrome on the box.

## 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.

```bash
# Both commands share the pool; neither opens a redundant tab
tfd sa quote AAPL &
tfd sa quote 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.

```bash
SID=$(tfd session acquire --site sa | jq -r .session_id)
tfd --session "$SID" sa quote AAPL
tfd --session "$SID" sa news AAPL --count 10
tfd session release "$SID"
```

## Architecture

See the design spec:
[`docs/superpowers/specs/2026-04-17-tail-fin-daemon-design.md`](../../docs/superpowers/specs/2026-04-17-tail-fin-daemon-design.md)

## Limitations

- Browser sites need Chrome: attach to a running Chrome at `TFD_HOST`, or pass
  `--host auto` for a daemon-managed stealth Chromium (grok is attach-only —
  Cloudflare blocks fresh CDP attaches). HTTP sites need no Chrome at all.
- Twitter commands are read-only (no posting).
- Unix domain sockets only; Windows is not supported.
