Terminal Session Recorder & AI Summarizer for debugging and incident investigation.
ShellSight wraps your shell via a PTY, transparently captures every command and its output, and uses AI to produce structured investigation summaries. Sessions are stored in a SQLite knowledge base with ChromaDB-powered semantic search for future lookup, interactive replay, and runbook generation.
pip install -e .
# With all optional dependencies (AI + semantic search + dev tools):
pip install -e ".[all]"# Launch the recording terminal
shellsight
# Launch with a pre-named session
shellsight --session "nginx-502-investigation"| Command | Description |
|---|---|
::session start [name] |
Start recording a session |
::session end |
End session and trigger AI summarization |
::session summary |
Show current session stats |
::note <text> |
Add a freeform note |
::hypothesis <text> |
Mark what you're about to test |
::found <text> |
Mark a key discovery |
::resolved |
Mark session as resolved |
::unresolved |
Mark session as unresolved |
::recall <query> |
Search past sessions semantically |
::replay <name> [--phase X] |
Replay a past session |
# List past sessions
shellsight sessions list
shellsight sessions list --last 7d --unresolved --tag nginx
# View a session
shellsight sessions show <session-id>
shellsight sessions timeline <session-id>
shellsight sessions commands <session-id> --phase remediation
# Search
shellsight search "OOM kill" # Full-text (FTS5)
shellsight recall "nginx returning errors" # Semantic (ChromaDB)
# Replay
shellsight replay <session-id>
shellsight replay <session-id> --phase remediation --dry-run
# Runbook generation
shellsight runbook <session-id> --format markdown
shellsight runbook <session-id> --format shell-script
# Export
shellsight sessions export <session-id> --format jsonCopy .env.example to .env and configure:
SHELLSIGHT_LLM_PROVIDER=anthropic # anthropic | openai | gemini | ollama
ANTHROPIC_API_KEY=sk-ant-...
# OPENAI_API_KEY=sk-...
# GEMINI_API_KEY=...
SHELLSIGHT_AUTO_SUGGEST=false
SHELLSIGHT_REDACT_SECRETS=true- PTY Wrapper — Transparent shell proxy using
pty/os/select - Command Parser — Shell hook injection (bash/zsh) with OSC 777 markers
- Session Manager — Lifecycle management with annotation support
- Knowledge Base — SQLite with FTS5 full-text search
- AI Summarizer — Multi-provider LLM (Anthropic, OpenAI, Gemini, Ollama)
- ChromaDB — Embedded vector DB for semantic search/recall
- Replay Engine — Interactive step-through with variable substitution
- Runbook Generator — LLM-powered clean runbooks from messy sessions
MIT