> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orinadus.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Shell Collector

> Ingests new commands from ~/.bash_history using a byte-offset checkpoint.

## Command

```bash theme={null}
urchin collect shell
```

## Source

```
~/.bash_history
```

No-op if the file does not exist.

## Behaviour

1. Reads the checkpoint file at `~/.local/share/urchin/shell.checkpoint` to get the last processed byte offset. Defaults to `0` on first run.
2. Opens `~/.bash_history` and reads from that offset to the end of file.
3. Each non-empty line is ingested as an `Event` with:
   * `source: "shell"`
   * `kind: "command"`
   * `content`: the command string
   * `workspace`: not set
   * `actor`: local identity (account + device)
4. Updates the checkpoint to the new end-of-file offset.

## Event shape

```json theme={null}
{
  "id": "...",
  "timestamp": "2026-05-04T20:00:00Z",
  "source": "shell",
  "kind": "command",
  "content": "cargo build --release",
  "actor": {
    "account": "samhc",
    "device": "saucemachine"
  }
}
```

## Notes

* Only `~/.bash_history` is read. `zsh_history` and fish history are not currently supported.
* The timestamp on each event is the time the collector ran, not the time the command was executed. Bash history does not include timestamps by default.
* If `HISTTIMEFORMAT` is set in your shell, bash writes timestamps inline in history — the collector does not currently parse these; it ingests the raw line including the timestamp prefix.
* Commands containing newlines (e.g. here-docs) may appear as multiple events.
* The collector is safe to run concurrently with normal shell use — it only reads, never writes.