Metadata-Version: 2.1
Name: claude-hfi-paste
Version: 1.1.0
Summary: Cross-platform paste support wrapper for claude-hfi (Human Feedback Interface)
Author: tlqbao
License: MIT
Project-URL: Homepage, https://github.com/tlqbao/claude-hfi-paste
Project-URL: Issues, https://github.com/tlqbao/claude-hfi-paste/issues
Keywords: claude,hfi,paste,terminal,pty,clipboard
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Terminals
Classifier: Topic :: Utilities
Requires-Python: >=3.7
Description-Content-Type: text/markdown
License-File: LICENSE

# claude-hfi-paste

**Cross-platform paste support for `claude-hfi`.**

`claude-hfi` (Human Feedback Interface) uses an Ink-based terminal UI that doesn't support standard clipboard paste. This lightweight wrapper fixes that by running `claude-hfi` inside a PTY proxy that intercepts paste events and injects them as keystrokes.

## The Problem

When running `claude-hfi`, you can't paste text (interface codes, file paths, etc.) using `Ctrl+Shift+V` (Linux) or `Cmd+V` (macOS). The Ink framework's input handler doesn't process bracketed paste sequences from the terminal.

## The Solution

This wrapper:

1. Runs `claude-hfi` inside a PTY pair
2. Enables **Bracketed Paste Mode** on your real terminal
3. When you paste, intercepts the `\e[200~...\e[201~` markers
4. Strips the markers and sends the text **character-by-character** into `claude-hfi` — as if you typed it
5. **Multiline support**: Newlines are sent as `Alt+Enter` (`ESC+CR`) so line breaks are preserved without triggering submit

**Zero dependencies** — uses only Python 3.10+ stdlib.

## Install

### Option 1: pip (recommended)

```bash
pip install claude-hfi-paste
```

### Option 2: Single-file download

```bash
# Download the standalone script
curl -fsSL https://raw.githubusercontent.com/YOUR_ORG/claude-hfi-paste/main/chfi-standalone.py \
  -o ~/.local/bin/chfi
chmod +x ~/.local/bin/chfi
```

### Option 3: From source

```bash
git clone https://github.com/YOUR_ORG/claude-hfi-paste.git
cd claude-hfi-paste
pip install .
```

## Usage

Instead of running `claude-hfi` directly, use `chfi`:

```bash
cd /path/to/your/project
chfi --vscode          # same as: claude-hfi --vscode
chfi --tmux            # same as: claude-hfi --tmux
chfi --continue        # same as: claude-hfi --continue
chfi --help            # passthrough, no wrapper overhead
chfi --version         # passthrough, no wrapper overhead
```

All `claude-hfi` flags are forwarded transparently.

### Paste

| Platform | Shortcut |
|----------|----------|
| Linux (X11/Wayland) | `Ctrl+Shift+V` |
| macOS (Terminal/iTerm2) | `Cmd+V` |
| Fallback (any) | `Ctrl+V` triggers clipboard read |

### Locating `claude-hfi`

The wrapper looks for `claude-hfi` in this order:

1. `$CLAUDE_HFI_PATH` environment variable
2. Current directory (`./claude-hfi`)
3. `~/Downloads/claude-hfi`
4. `/usr/local/bin/claude-hfi`
5. `~/.local/bin/claude-hfi`

## Platform Support

| Platform | Clipboard Tool | Status |
|----------|---------------|--------|
| Linux X11 | `xclip` or `xsel` | ✅ |
| Linux Wayland | `wl-paste` | ✅ |
| macOS | `pbpaste` (built-in) | ✅ |

## How It Works

```
┌─────────────────────────────────────────────┐
│  Your Terminal (gnome-terminal / iTerm2)    │
│                                             │
│  Ctrl+Shift+V sends:                       │
│    \e[200~ hello-code \e[201~              │
│              │                              │
│              ▼                              │
│  ┌───────────────────────┐                  │
│  │   chfi (PTY wrapper)  │                  │
│  │                       │                  │
│  │  1. Detect paste      │                  │
│  │  2. Strip markers     │                  │
│  │  3. \\n → Alt+Enter    │                  │
│  │  4. Send char-by-char │                  │
│  │              │        │                  │
│  └──────────────┼────────┘                  │
│                 ▼                            │
│  ┌───────────────────────┐                  │
│  │   claude-hfi (Ink)    │                  │
│  │                       │                  │
│  │  Receives: h e l l o  │                  │
│  │  (as individual keys) │                  │
│  └───────────────────────┘                  │
└─────────────────────────────────────────────┘
```

## Transparent Design

- **`--help`, `--version`**: Exec `claude-hfi` directly — zero overhead
- **Piped stdin**: Exec directly — wrapper only activates for interactive use
- **Signals**: `SIGINT`, `SIGTERM`, `SIGHUP`, `SIGQUIT`, `SIGWINCH` all forwarded
- **Exit codes**: Preserved from `claude-hfi`
- **TTY detection**: `claude-hfi` sees a real PTY — colors, cursor, everything works
- **No stdout pollution**: Wrapper messages go to stderr only

## License

MIT
