Skip to content

nborwankar/claudetools

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

35 Commits
ccli
ccli
 
 
ccmdr
ccmdr
 
 
cswitch
cswitch
 
 
docs
docs
 
 
itool/src
itool/src
 
 
tx
tx
 
 
.gitignore
.gitignore
 
 
CLAUDE.md
CLAUDE.md
 
 
README.md
README.md
 
 

Repository files navigation

claudetools

CLI tools for supercharging Claude Code workflows. Zero MCP overhead — everything runs through CC's built-in Bash tool or as external scripts.

Tools

tx — Human-Friendly tmux with Named Panes

A Python CLI wrapper around tmux (via libtmux) that replaces cryptic tmux flag syntax with readable, name-based commands.

# Instead of this:
tmux capture-pane -t :.1 -p -S -50 | grep -i "error"
tmux send-keys -t mysession:0.1 "pytest" Enter
tmux split-window -h -t "$SESSION:0" -c "$DIR"

# You do this:
tx read tests --grep error
tx send terminal "pytest"
tx split right --name tests --dir ~/Projects/github/myproject

Key idea: Panes have names, not numbers. You never think about indices.

ccmdr — Claude Code Commander

A one-command 3-pane workspace for Claude Code development. Thin wrapper around tx workspace.

# From inside any project directory
ccmdr

# Or by project name
ccmdr strictRAG
┌──────────────────────────────┬──────────────────────┐
│                              │   terminal           │
│   Claude Code (60%)          ├──────────────────────┤
│                              │   git status (live)  │
└──────────────────────────────┴──────────────────────┘

Key idea: Claude Code + live git status + a shell, all with named panes. In non-git directories the git pane falls back to a plain shell.

See ccmdr/CCMDR_README.md for full usage.

ccli — Claude Code CLI Orchestrator

A TypeScript/React Ink CLI that spawns and tracks headless Claude Code instances via the Agent SDK. Auto-creates tmux workspaces using tx.

# Single instance (auto-creates tmux workspace via tx)
ccli "explain this codebase" --cwd ~/Projects/github/myapp

# Standalone mode (no tmux)
ccli --no-tmux "say hello"

# Multi-Claude (N instances in parallel)
ccli multi --config tasks.toml

Key idea: One command spawns a Claude instance with a proper tmux workspace — claude pane on the left, shell on the right.

cswitch — Claude Session Switcher

A Python TUI that discovers running Claude Code instances across iTerm2 windows/tabs and lets you switch between them instantly. Joins ps(1) output with iTerm2 AppleScript enumeration on the TTY field.

# Interactive TUI (Textual split-pane)
cswitch

# Or headless modes for scripting
cswitch --list              # Table of all Claude sessions
cswitch --preview 0         # Show content of session 0
cswitch --switch 2          # Jump to session 2
┌──────────────────────────┬──────────────────────────────────────┐
│  Session List (25%)      │  Preview (75%)                       │
│                          │                                      │
│  * strictRAG             │  Preview: strictRAG (W1:T1:S1)       │
│    redditmath            │  PID 12345                           │
│    claudetools           │  ──────────────────────────────────   │
│    n2                    │  > Running tests...                  │
│                          │  PASSED 42/42                        │
│                          │                                      │
├──────────────────────────┴──────────────────────────────────────┤
│  q Quit  r Refresh  Enter Switch                                │
└─────────────────────────────────────────────────────────────────┘

Key idea: Find any Claude session by name, preview its output, and jump to it — without manually hunting through iTerm2 tabs.

Quick Start

Prerequisites

  • macOS (tested on M2 MacBook Pro)
  • tmux 3.2+ (brew install tmux)
  • Python 3.10+ with libtmux (pip install 'libtmux>=0.53.0')
  • iTerm2 (for cswitch)
  • textual >= 6.0 (for cswitch TUI; cswitch --list works without it)
  • Node.js 18+ (for ccli)

Installation

tx is installed at ~/.claude/bin/tx (added to PATH via ~/.zshrc).

The shim uses an absolute Python path to work inside tmux sessions where conda may not be initialized. If you get "libtmux required" errors:

pip install 'libtmux>=0.53.0'
# Or edit ~/.claude/bin/tx to point PYTHON= at your preferred interpreter

cswitch is installed at ~/.claude/bin/cswitch (same pattern as tx).

If you get "textual required" errors in TUI mode:

pip install 'textual>=6.0'
# Or use --list mode which works without textual

ccli is built from source:

cd claudetools/ccli && npm install && npm run build

First Use — tx

# Create a workspace for any project
tx workspace strictRAG

# See what was created
tx list

# Output:
# Session: strictRAG
#   Window 0: main
#     Pane 0 "editor":   [zsh] ~/Projects/github/strictRAG
#     Pane 1 "terminal": [zsh] ~/Projects/github/strictRAG
#     Pane 2 "git":      [git] ~/Projects/github/strictRAG

# Attach to see it visually
tx attach strictRAG

First Use — ccli

# Spawns Claude in a tmux workspace
ccli "review the auth module" --cwd ~/Projects/github/myapp

# Layout created:
# ┌──────────────────┬──────────────────┐
# │  ccli · sonnet   │  ~/myapp         │
# │  Claude output   │  $               │
# │  streaming...    │                  │
# │  "claude"        │  "shell"         │
# └──────────────────┴──────────────────┘

tx Commands

Session lifecycle:
  tx new <session>                     Create session with one named pane
  tx window <session> <name>           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]  Split and name a new pane
  tx send <pane> <command>             Send command to a named pane
  tx read <pane> [--lines N] [--grep]  Read output from a named pane
  tx read <pane> --json                JSON output (AI-agent friendly)
  tx interrupt <pane>                  Ctrl+C a named pane

Monitoring:
  tx list                              Show all sessions and named panes
  tx status                            Compact overview of what's running

Aliases

Full Alias
tx list tx ls
tx read tx r
tx send tx s
tx interrupt tx stop
tx status tx st
tx workspace tx ws
tx attach tx a
tx detach tx d

Pane Addressing

Panes are addressed by name (primary) or index (fallback):

tx read tests                    # By name (searches current session first)
tx read strictRAG:tests          # By session:name (cross-session)
tx read 1                        # By index (fallback, active window)

ccli Usage

# Single instance with tmux workspace
ccli "explain this codebase" --cwd ~/Projects/github/myapp
ccli -m opus "review auth.py" --cwd ~/myapp

# Standalone (no tmux)
ccli --no-tmux "say hello"

# Multi-Claude orchestration
ccli multi --config tasks.toml

TOML Config (optional)

# ccli.toml — place in project root or ~/.config/ccli/config.toml
[defaults]
model = "sonnet"
max_turns = 10

[workspace]
layout = "minimal"

[[workspace.extra_panes]]
name = "git"
position = "below-shell"
size = "30%"
cmd = "git log --oneline -10"

[[instances]]
name = "backend"
prompt = "review auth module"
cwd = "~/Projects/github/myapp/backend"
model = "opus"

Architecture

┌─────────────────────────────────────────────────────────────┐
│  Claude Code (Bash tool) or User terminal                   │
└──────────┬──────────────────┬──────────────────┬────────────┘
           │                  │                  │
           ▼                  ▼                  ▼
┌──────────────────┐  ┌────────────────┐  ┌──────────────────┐
│  tx               │  │  ccli           │  │  cswitch          │
│  (Python/libtmux) │  │  (TS/React Ink) │  │  (Python/Textual) │
│  ~/.claude/bin/tx │  │  ccli/          │  │  ~/.claude/bin/   │
└──────────┬───────┘  └───────┬────────┘  └──────────┬───────┘
           │                  │ calls tx              │ AppleScript
           │                  │ via child_process     │ + ps(1)
           ▼                  ▼                       ▼
┌──────────────────────────────────┐  ┌──────────────────────┐
│  tmux server                     │  │  iTerm2              │
│  (sessions, windows, named panes)│  │  (windows, tabs)     │
└──────────────────────────────────┘  └──────────────────────┘

Design choices:

  • Zero MCP — no context overhead, CC calls tools via Bash
  • Compose, don't merge — tx (Python) and ccli (TypeScript) are separate tools with a clean subprocess boundary
  • Named panes via tmux pane titles (select-pane -T)
  • Launcher pattern — ccli creates tmux workspace, re-launches itself inside with --inside-tmux flag

File Structure

claudetools/
├── README.md                   # This file
├── CLAUDE.md                   # Project instructions
├── DONE.md                     # Completed work log
├── .gitignore
├── tx/                         # tmux tool (Python)
│   ├── src/
│   │   └── tx.py               # Single-file CLI (~900 lines)
│   └── docs/
│       ├── TMUX_PY.md          # Design doc + libtmux reference
│       ├── TX_USAGE.md         # Claude Code integration patterns
│       ├── ITERM_CC.md         # iTerm2 + CC integration patterns
│       └── ITERM2_PY.md        # iTerm2 Python API (future)
├── ccmdr/                      # Claude Code Commander (zsh)
│   ├── ccmdr                   # Executable script
│   └── CCMDR_README.md         # Usage documentation
├── ccli/                       # Claude Code CLI (TypeScript)
│   ├── package.json
│   ├── tsconfig.json
│   ├── ccli.toml               # Example config
│   ├── src/
│   │   ├── cli.tsx             # Entry point (launcher + multi)
│   │   ├── app.tsx             # Single-instance UI
│   │   ├── multi-app.tsx       # Multi-instance dashboard
│   │   ├── components/         # React Ink components
│   │   ├── hooks/              # Agent SDK, cost tracking, multi
│   │   └── utils/              # tmux.ts, config-toml.ts
│   └── docs/
│       └── PLAN.md
└── cswitch/                    # Claude Session Switcher (Python)
    ├── src/
    │   └── cswitch.py          # Single-file CLI + TUI (~560 lines)
    └── docs/
        └── DESIGN.md           # Design doc + implementation plan

~/.claude/bin/
├── tx                          # Executable shim -> tx/src/tx.py
├── ccmdr                       # Symlink -> ccmdr/ccmdr
└── cswitch                     # Executable shim -> cswitch/src/cswitch.py

Dependencies

Tool Dependency Version Purpose
tx tmux >= 3.2a Terminal multiplexer
tx Python >= 3.10 Runtime
tx libtmux >= 0.53.0 Python tmux API
ccmdr tx — Uses tx workspace under the hood
ccmdr zsh — Shell script runtime
ccli Node.js >= 18 Runtime
ccli @anthropic-ai/claude-agent-sdk latest Headless Claude Code
ccli React Ink 6.x Terminal React renderer
ccli smol-toml latest TOML config parser
cswitch Python >= 3.10 Runtime
cswitch iTerm2 — AppleScript session enumeration
cswitch textual >= 6.0 TUI framework (optional for --list mode)

License

MIT (when open-sourced)

Built: 2026-02-18 Author: nborwankar

About

CLI tools for supercharging Claude Code workflows — tx, ccli, cswitch, itool

Resources

Readme
Activity

Stars

1 star

Watchers

0 watching

Forks

1 fork
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages