Skip to content

CLAUDE.md

Latest commit

 

History

History
249 lines (198 loc) · 10.2 KB

CLAUDE.md

File metadata and controls

249 lines (198 loc) · 10.2 KB

CLAUDE.md — claudetools

Project Overview

CLI tools for supercharging Claude Code workflows. No MCP overhead. Monorepo with one subdirectory per tool.

Current State (2026-02-13)

  • tx — Human-friendly tmux with named panes (Phase 1 complete, 17 commands)
  • ccli — Claude Code CLI orchestrator (Agent SDK + React Ink + tmux integration)
  • cswitch — Claude Session Switcher TUI for iTerm2 (Phase 1 complete)
  • itool — iTerm2 escape-sequence features (Phase 1 complete, 8 commands)

Directory Structure

claudetools/
├── CLAUDE.md              # This file
├── DONE.md                # Completed work log
├── README.md              # User-facing docs
├── .gitignore
├── tx/                    # tmux tool (Python)
│   ├── src/
│   │   └── tx.py          # Single-file CLI (~900 lines, libtmux)
│   └── docs/
│       ├── TMUX_PY.md     # Design doc, libtmux API reference, roadmap
│       ├── TX_USAGE.md    # Claude Code integration patterns
│       ├── ITERM_CC.md    # iTerm2 + CC integration patterns
│       └── ITERM2_PY.md   # iTerm2 Python API approach (future)
├── ccli/                  # Claude Code CLI orchestrator (TypeScript)
│   ├── CLAUDE.md          # ccli-specific instructions
│   ├── DONE.md            # ccli completed work log
│   ├── README.md          # ccli user-facing docs
│   ├── package.json       # Node.js dependencies
│   ├── tsconfig.json      # TypeScript config
│   ├── ccli.toml          # Example TOML config
│   ├── src/
│   │   ├── cli.tsx         # Entry point (launcher + multi + standalone)
│   │   ├── app.tsx         # Root component (single instance)
│   │   ├── multi-app.tsx   # Root component (multi-instance dashboard)
│   │   ├── components/     # React Ink UI components
│   │   ├── hooks/          # React hooks (Agent SDK, cost, multi)
│   │   └── utils/          # tmux.ts, config-toml.ts, config.ts
│   └── docs/
│       └── PLAN.md        # Implementation plan
├── itool/                 # iTerm2 escape-sequence features (Python)
│   └── src/
│       └── itool.py       # Single-file CLI (~350 lines, no deps)
├── cswitch/               # Claude Session Switcher (Python)
│   ├── src/
│   │   └── cswitch.py     # Single-file CLI + TUI (~560 lines)
│   └── docs/
│       └── DESIGN.md      # Design doc + implementation plan
└── docs/
    └── ITOOL_PLAN.md      # itool design plan (Phases 1-3)

tx — tmux tool

Shim: ~/.claude/bin/tx -> tx/src/tx.py

Working Commands (17 commands)

# Session lifecycle
tx new <session> [--dir D] [--pane-name N] [--window-name W] [--force]
                                     # Create bare session with one named pane
tx window <session> <name> [--dir D] [--pane-name N]
                                     # Add a window to existing session
tx workspace <project>               # Create 3-pane workspace (editor/terminal/git)
tx attach <session>                  # Attach to a session
tx detach                            # Detach from current session
tx kill <session>                    # Kill a session (guards attached)
tx orphans [--kill]                  # Find/kill detached sessions

# Pane operations
tx split <dir> [--name N] [--source S] [--dir D] [--size S] [--cmd C]
                                     # Split and name a new pane
tx send <pane> <command>             # Send command to named pane
tx read <pane> [--lines N] [--grep]  # Read pane output by name
tx read <pane> --json                # JSON output (AI-agent friendly)
tx interrupt <pane>                  # Ctrl+C a named pane

# Plumbing
tx resolve <pane>                    # Resolve name to tmux pane ID (for scripts)

# Monitoring
tx list                              # Sessions + named panes + [DETACHED] status
tx status                            # What's running everywhere

Dependencies

  • Python 3.10+
  • tmux >= 3.2a (installed: 3.5a)
  • libtmux >= 0.53.0 (installed: 0.53.0)

Architecture

  • Named panes via tmux pane titles (select-pane -T)
  • libtmux for object model, subprocess for title/split ops
  • Session metadata via list-sessions -F (epoch timestamps -> formatted)
  • Pane resolution: name -> session:name -> numeric index
  • Zero MCP — CC calls tx through its Bash tool
  • ccli integration: ccli uses tx new, tx window, tx split, tx send for all workspace creation

Development Notes

  • Single file for fast iteration during dogfooding
  • Refactor into modules when command count exceeds ~18
  • Run tx list to verify tmux state after changes
  • Pane titles persist across tmux detach/attach cycles
  • Use tx orphans to check for forgotten sessions
  • Shim uses absolute Python path (/Users/nitin/anaconda3/bin/python3) because tmux sessions may not have conda initialized — bare python3 may resolve to a different binary without libtmux. Falls back to python3 if the hardcoded path doesn't exist. If libtmux is missing: pip install 'libtmux>=0.53.0' in whichever Python the shim resolves to.

ccli — Claude Code CLI orchestrator

See ccli/CLAUDE.md for full ccli documentation. Key points:

  • Tech: TypeScript 5.x, React Ink 6.x, React 19, Agent SDK
  • Launcher pattern: Detects tmux, creates workspace via tx, re-launches inside
  • Flags: --inside-tmux (hidden, prevents recursion), --no-tmux (standalone)
  • Multi-Claude: ccli multi --config tasks.toml — N instances in parallel
  • Config: ccli.toml (TOML, optional, sparse — defaults just work)
  • Build: cd ccli && npm run build

itool — iTerm2 escape-sequence features

Shim: ~/.claude/bin/itool -> itool/src/itool.py

What It Does

Complements tx with iTerm2-exclusive visual features via escape sequences. Zero dependencies (stdlib only). Auto-detects tmux and wraps in DCS passthrough.

Commands (8 commands)

itool badge <text>                    Set badge on current iTerm2 session
itool badge --clear                   Clear badge
itool notify <message> [--title T]    macOS notification via iTerm2
itool title <text>                    Set tab/window title
itool color --fg/--bg/--cursor COLOR  Set terminal colors (#rrggbb or name)
itool color --reset                   Reset all colors to default
itool profile <name>                  Switch iTerm2 profile
itool mark                            Set mark at cursor position
itool annotate <text>                 Add annotation at cursor
itool check                           Verify iTerm2/tmux/tx environment

# Remote pane (sends via tx):
itool badge --pane terminal "TESTS"
itool color --pane git --bg '#001a00'

Architecture

  • Escape sequences printed to stdout → iTerm2 processes them
  • tmux passthrough: auto-enables allow-passthrough on, wraps in DCS
  • Remote pane: --pane flag sends via tx (base64-encoded command injection)
  • No iterm2 Python package needed (Phase 1 is escape-sequence only)
  • Plan for Phase 2 (Python API) in docs/ITOOL_PLAN.md

Dependencies

  • Python 3.10+ (stdlib only)
  • tx (only for --pane flag)
  • iTerm2 (escape sequences are iTerm2-specific)

cswitch — Claude Session Switcher

Shim: ~/.claude/bin/cswitch -> cswitch/src/cswitch.py

What It Does

TUI for discovering and switching between running Claude Code instances in iTerm2. Joins ps(1) output with iTerm2 AppleScript session enumeration on the TTY field to find which iTerm2 tabs/windows have Claude running.

Commands

cswitch                  # Launch Textual TUI (split-pane: session list + preview)
cswitch --list           # List all Claude sessions with status and project name
cswitch --preview N      # Preview content of session N (1-based from --list)
cswitch --switch N       # Switch to session N (1-based from --list)
cswitch --label          # Set iTerm2 tab titles to project directory names

Key Bindings (TUI mode)

Key Action
Up/Down Navigate session list
Enter Switch to highlighted session and exit
r Refresh session list
q Quit

Dependencies

  • Python 3.10+
  • iTerm2 (for AppleScript session enumeration)
  • textual >= 6.0 (for TUI mode only; --list works without it)

Architecture

  • Discovery via ps -eo tty,pid,comm filtered for 'claude'
  • iTerm2 session enumeration via AppleScript (osascript)
  • Inner-join on TTY field to match Claude PIDs to iTerm2 sessions
  • Status detection from last 5 lines of terminal content (idle/wait/review/working)
  • Strips iTerm2 process suffix (e.g. (clangd)) from session names
  • Textual TUI with split pane: ListView (sessions) + RichLog (preview)
  • AppleScript select window/select tab for switching
  • Zero MCP — CC calls cswitch through its Bash tool

Status Indicators

Symbol Status Meaning
⏸ idle -- INSERT -- detected Claude waiting for user input
❓ wait Esc to cancel detected Claude showing confirmation options
📋 review ctrl-g to edit detected Claude in plan review mode
⚙️ working Other non-blank content Claude actively processing
· ? All blank lines Unknown state

Development Notes

  • Single file for fast iteration during dogfooding
  • --list mode works without textual (graceful degradation)
  • All CLI indices are 1-based (matches # column in --list output)
  • Shim uses absolute Python path (/Users/nitin/anaconda3/bin/python3) same pattern as tx — falls back to python3 if hardcoded path doesn't exist. If textual is missing: pip install 'textual>=6.0' in whichever Python the shim resolves to.

Roadmap

  • tx Phase 2: watch, grep, signal commands
  • tx Phase 3: workspace layout variants, dashboard
  • itool Phase 2: iTerm2 Python API (screen reading, streaming) — decide after dogfooding Phase 1
  • itool Phase 3: workspace visual layer (themed workspaces, visual dashboards)
  • ccli: polish multi-instance dashboard, error recovery
  • cswitch: input tunneling (--send N "text"), session grouping, keyboard shortcuts
  • Open source when UX is validated through dogfooding