collect

agentcrumbs collect

The collector is an HTTP server that receives crumbs via POST /crumb and writes them to a JSONL file. Without it running, crumbs fall back to stderr only and can't be queried later.

agentcrumbs collect
# agentcrumbs collector
#   http:  http://localhost:8374/crumb
#   store: ~/.agentcrumbs/crumbs.jsonl
#   press ctrl+c to stop

Agent workflow

When an agent needs to debug something, it should start the collector, clear old crumbs, reproduce, and query:

agentcrumbs collect --quiet &
agentcrumbs clear
AGENTCRUMBS=1 node app.js
agentcrumbs query

Clear before reproducing so you only see crumbs from this run. No --since guessing needed. The --quiet flag keeps the collector from cluttering stdout.

Options

Examples

# Custom port and storage
agentcrumbs collect --port 9999 --dir /var/log/crumbs

# Quiet mode
agentcrumbs collect --quiet

How it works

1. Listens on the specified port for POST /crumb requests
2. Validates the JSON body matches the crumb schema
3. Appends each crumb as a line to crumbs.jsonl
4. The tail and query commands read from this file

Without the collector

If the collector isn't running, crumbs still print to stderr (via ConsoleSink). You can read them in the terminal output, but tail, query, and replay won't work because nothing is writing to the JSONL file.

For single-service debugging where you just want to see crumbs in the console, you don't need the collector. For multi-service setups or querying historical crumbs, start it first.