Skip to content

README.md

Latest commit

 

History

History
108 lines (75 loc) · 3.77 KB

README.md

File metadata and controls

108 lines (75 loc) · 3.77 KB
Raw

buddy-log

Capture and replay Claude Code's companion (/buddy) speech bubble messages.

The companion's insights are normally ephemeral — they appear briefly in a speech bubble and vanish. buddy-log captures them from the terminal output, logs them per-project and per-session, and optionally auto-injects them into your conversation as context.

How it works

  1. claude-log wraps your Claude Code session with script (or taps into a tmux session via pipe-pane) to capture all terminal rendering
  2. A background watcher parses the raw output for ink round-border boxes (╭╮╰╯│─) — the companion's speech bubbles
  3. Messages are deduplicated (ink re-renders frequently) and saved to a per-session log
  4. A UserPromptSubmit hook checks for new messages on every prompt and injects them as context

The companion's name is detected automatically from your Claude Code session data.

Install

git clone https://github.com/bashctrl/buddy-log.git
cd buddy-log
bash install.sh

Then add the hook to ~/.claude/settings.json (the installer prints the exact JSON).

Add to your shell rc:

alias claude-log='~/.claude/scripts/claude-log.sh'
alias buddy-log='~/.claude/scripts/buddy-log.sh'

Usage

New session with logging

claude-log                # Launches Claude Code with companion capture

Tap into existing tmux sessions

claude-log --tap myapp        # Start capturing in background
claude-log --tmux myapp       # Tap + attach
claude-log --untap myapp      # Stop capturing
claude-log --status           # Show active taps

View captured messages

buddy-log                 # This session's messages
buddy-log --today         # All of today's messages
buddy-log --all           # All messages for this project
buddy-log --tail          # Follow new messages in real-time

Manual injection

If auto-injection is not configured, you can manually inject companion messages inside a Claude Code session:

! buddy-log --contribute          # Inject last message
! buddy-log --contribute -n 3     # Inject last 3 messages

Auto-injection (recommended)

With the UserPromptSubmit hook configured, new companion messages are automatically included as context on your next prompt. No action needed — just work normally and your companion's observations will appear when relevant.

File layout

~/.claude/
  scripts/
    buddy-extract.py       # Core: terminal parser + message extractor
    buddy-log.sh           # CLI for viewing messages
    claude-log.sh          # Session wrapper + tmux tap manager
  hooks/
    buddy-contribute.sh    # UserPromptSubmit hook for auto-injection

~/.claude/projects/<project>/logs/
    session-<id>.raw       # Raw terminal capture
    buddy-<id>.log         # Extracted companion messages
    current.raw            # Symlink to active session's raw log
    .buddy-cursor          # Tracks last injected message position
    .tap-<tmux>.meta       # Tap state for tmux sessions

Requirements

  • Claude Code with a /buddy companion configured
  • Python 3.10+
  • script command (standard on Linux/macOS)
  • tmux (optional, for tapping existing sessions)

How the parser works

Claude Code's companion bubble is rendered by ink using a Box component with borderStyle: "round" — Unicode box-drawing characters ╭╮╰╯│─. The text is word-wrapped at 30 characters with a max box width of 34.

The parser strips ANSI escape codes from the raw terminal capture, then matches these box patterns to extract the text content. Consecutive duplicate messages (from ink's frequent re-renders) are deduplicated.

A heuristic filter excludes UI elements (trust prompts, menu items) that also use box-drawing characters.

License

MIT