Shell Collector

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.

​

Command

urchin collect shell

​

Source

~/.bash_history

​

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

{
  "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.