# firehose-listener

A command-line listener that writes matching Bluesky Jetstream posts to stdout for [Letta Monitor](https://docs.letta.com/).

**Stdout contains only matching post text, one post per row.** Connection state, retries, and shutdown details go to stderr. The listener does not fetch profiles, build links, search the web, or interpret posts.

## Requirements

- Node.js 22 or later
- No Bluesky account or API key

## Run it

```bash
./bin/firehose-listener
```

The default query is `Letta`. Add one or more queries:

```bash
./bin/firehose-listener --query Letta --query ATProto
```

Replay recent events and stop after the first match:

```bash
./bin/firehose-listener --query Letta --since 5m --max-matches 1
```

See every option:

```bash
./bin/firehose-listener --help
```

## Use it with Monitor

Start Letta Code in this repository and paste [`DEMO_PROMPT.md`](./DEMO_PROMPT.md). Monitor runs the listener in the background. Each matching stdout row returns to the same conversation as an event, and the agent decides what to do next.

## Event flow

1. The listener opens a WebSocket to an official Bluesky Jetstream instance.
2. Jetstream sends only `app.bsky.feed.post` records.
3. The listener checks each new post against the configured whole-term queries.
4. Each match is normalized to one line and written to stdout.
5. On reconnect, the listener resumes from its last cursor with a two-second overlap and removes duplicate post IDs.

`--since` converts a duration such as `5m` into a Jetstream time cursor. The cursor replays recent public posts before the live stream starts.

## Jetstream boundary

[Jetstream](https://docs.bsky.app/blog/jetstream) converts the ATProto firehose into filtered JSON events. It is useful for demos and low-stakes monitoring. Jetstream events are not cryptographically verified, so this tool is not suitable for moderation, archival, or security decisions.

Public instance details are in [`bluesky-social/jetstream-legacy`](https://github.com/bluesky-social/jetstream-legacy).

## Test

```bash
npm run check
```