cliptools

A small collection of Zsh utilities for capturing command output, file contents, and clipboard bundles in a format that is easy for humans and LLMs to consume.

The tools revolve around a simple JSONL session log and a stable, machine-readable bundle format. Everything is designed to support fast iteration when working with ChatGPT/Codex and to keep the captured context clean, explicit, and reproducible.

---

Commands

clipfiles

Capture one or more files into the clipboard as a bundle, and record each file into the session ledger as a JSON entry.

Each file is wrapped in:

##### BEGIN FILE: path (size bytes)
```lang filename="path"
… contents …

END FILE

Supports:

- project-relative paths
- skipping binary files
- truncation via `--max-bytes`
- full-path annotation via `filename="…"`;

Ledger is truncated by default. Use `--append` to preserve the previous
entries and regenerate the full bundle:

clipfiles --append file1 file2 …

### `cliprun`
Runs a command, captures its stdout/stderr into the ledger, and produces
a clipboard bundle containing:

- a `##### BEGIN CMD` block showing the command
- a block for stdout (if nonempty)
- a block for stderr (if nonempty)

Usage:

cliprun jj show abc123

Ledger entries:

{"ts": "...", "type": "cmd", "cmd": ["jj","show","abc123"]} {"ts": "...", "type": "stdout", "text": "…"} {"ts": "...", "type": "stderr", "text": "…"} # only if stderr existed

Clipboard always reflects the *entire* session unless `--fresh` is used.
By default each `cliprun` truncates the ledger; pass `--append` to keep
earlier entries and re-render everything.

### `cliprender`
Re-renders the current ledger into a bundle without changing the log.

Useful when:

- you want to revisit earlier steps  
- the clipboard was overwritten  
- or you’re chaining append operations

### `clipclear`
Clears the session ledger and empties the clipboard.

Equivalent to:

~/.cliptools/session.jsonl pbcopy < /dev/null

---

## Session Ledger Format (JSONL)

Every operation appends one JSON object per entry to:

~/.cliptools/session.jsonl

Supported entry types:

```jsonl
{"ts": "...", "type": "file",   "path": "a.txt", "blob": "…raw file…"}
{"ts": "...", "type": "cmd",    "cmd": ["ls", "-la"]}
{"ts": "...", "type": "stdout", "text": "…"}
{"ts": "...", "type": "stderr", "text": "…"}

The ledger is the source of truth.
clipfiles, cliprun, and cliprender all produce clipboard output by serializing the ledger into the human/LLM-friendly bundle format.

---

Bundle Format

The rendered clipboard always begins with:

##### FILE BUNDLE (N entries) #####

Each entry is wrapped in a structured block that clearly marks its type and origin. This format is stable so downstream tools (including LLMs) can reliably parse it.

Example for a command run:

##### BEGIN CMD: ["ls"] (1 entries)
```text
ls

END CMD

Example for captured stdout:

BEGIN STDOUT (42 bytes)

hello
world

END STDOUT

All file, command, and text blocks use triple-quoted Markdown fences.

---

## Behavior-Driven Tests (optional but recommended)

The `features/` directory contains Gherkin-style feature files and a
lightweight runner written in Zsh. These define the **contract** for
cliptools behavior.

Run all tests:

```zsh
./features/runner.sh

Run a specific feature:

./features/runner.sh features/basic.feature

Scenarios verify:

• triple-quoted file blocks
• ledger entry counts
• clipboard contents
• run/capture semantics
• append semantics
• whitespace behavior around fences

This ensures cliptools remains stable and predictable as you iterate.

---

Philosophy

cliptools keeps a low profile:

• no external dependencies
• pure Zsh + macOS clipboard tools
• explicit append flag when you want to keep history
• structured clipboard bundles for LLM workflows
• stable test-backed behavior

The goal is simple: make it easy to hand rich, reproducible context to an agent without copy/paste gymnastics or ambiguous state.

Environment toggles (for testing/CI)

• CLIPTOOLS_LEDGER — override the default ledger path (e.g., point to a temp file in CI).
• CLIPTOOLS_FAKE_CLIPBOARD — if set, clipboard writes go to this file instead of pbcopy; reads in tests can cat the same file. Useful in headless or sandboxed environments where the macOS clipboard is unavailable.