Skip to content

CLAUDE.md

Latest commit

 

History

History
52 lines (36 loc) · 1.83 KB

CLAUDE.md

File metadata and controls

52 lines (36 loc) · 1.83 KB
Raw

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Claude Code skill package (pdb-tmux) that enables interactive Python pdb debugging sessions through tmux. It solves the problem of Claude Code not having direct TTY stdin access by using tmux as an intermediary - pdb runs in a tmux pane with real TTY, while Claude interacts via capture-pane and send-keys.

Architecture

.claude/skills/pdb-tmux/
├── SKILL.md          # Skill specification (loaded by Claude Code)
└── scripts/
    ├── start.sh      # Initialize pdb session in tmux
    ├── capture.sh    # Read current pane output
    └── send.sh       # Send pdb command and capture response

Workflow pattern: Capture → Send → Capture (read state, issue command, read new state)

Script Usage

All scripts default to session name dbg and target SESSION:0.0 (first window, first pane).

# Start pdb session (requires -- separator before pdb command)
./scripts/start.sh [session] -- python -m pdb script.py

# With uv (recommended when pyproject.toml exists)
./scripts/start.sh [session] -- uv run python -m pdb script.py

# Capture current output (default 200 lines)
./scripts/capture.sh [session] [lines]

# Send pdb command and capture result
./scripts/send.sh [session] "pdb_command"

Bash Conventions

All scripts use:

  • #!/usr/bin/env bash shebang
  • set -euo pipefail for strict error handling
  • Default argument pattern: session="${1:-dbg}"
  • printf "%q" for shell-safe escaping in start.sh

Key Constraints

  • Scripts only interact with the specified tmux session (no cross-session operations)
  • The -- separator in start.sh is required to prevent argument confusion
  • Default capture is 200 lines; SKILL.md allows up to 400