Metadata-Version: 2.4
Name: clipgate
Version: 0.1.4
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Rust
Classifier: Topic :: Utilities
License-File: LICENSE
Summary: Terminal-native typed clipboard
Keywords: clipboard,developer-tools,cli,ai,productivity
Home-Page: https://clipgate.github.io
Author: Alok Tiwari
License: Proprietary
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: Documentation, https://clipgate.github.io/docs/
Project-URL: Homepage, https://clipgate.github.io
Project-URL: Releases, https://clipgate.github.io/releases/
Project-URL: Support, https://clipgate.github.io/support/

_ ClipGate" width="700">

Terminal-native typed clipboard.

[![Website](https://img.shields.io/badge/site-clipgate.github.io-00d4ff?style=flat-square&logo=github)](https://clipgate.github.io)
[![Built with Rust](https://img.shields.io/badge/built_with-Rust-dea584?style=flat-square)](https://www.rust-lang.org/)
[![220+ tests](https://img.shields.io/badge/tests-220%2B_passing-2ecc71?style=flat-square)]()
[![4.6MB binary](https://img.shields.io/badge/binary-4.6MB-f59e0b?style=flat-square)]()

ClipGate terminal quick reference

## Copy. Classify. Retrieve.

```bash
echo "TypeError: x is undefined" | cg copy         # auto-classified as 'error'
echo "git push origin main" | cg copy -v            # cg: command 01KN3K4Q (confidence: 0.80)
echo "sk_live_abc123secret" | cg copy               # cg: secret 01KN3K5R (secret, memory-only)
cg list                                              # see your typed clipboard history
cg paste -t error                                    # get exactly what you need
cg pack -t error -n 5 | claude "fix these"           # bundle errors for AI
```

No more losing that error trace you copied 5 minutes ago. No more scrolling through clipboard history hoping to find the right thing. **Clip Gate auto-classifies everything you copy** into developer-meaningful types and lets you retrieve by type, not by order.

---

## Why?

Your clipboard holds one thing. You copy dozens per session — errors get overwritten by paths, commands vanish, that stack trace from 3 minutes ago is gone forever.

Clipboard history tools exist, but they show you a flat list sorted by time. You need clipboard *intelligence* — knowing *what* each item is and retrieving by type. And when you're working with AI assistants, instead of copy-pasting errors one by one, `cg pack` bundles them with metadata and pipes directly to Claude, ChatGPT, or Cursor.

---

## Install

**Quick install (macOS & Linux)**
```bash
curl -fsSL https://clipgate.github.io/install.sh | sh
```

**PyPI (any platform with Python)**
```bash
pip install clipgate
```

No Rust toolchain needed. Installs the `cg` binary on your PATH. Works on macOS, Linux, and Windows.

**Homebrew (macOS & Linux)**
```bash
brew install clipgate/tap/cg
```

**Manual download**

Use the official [Release Notes](https://clipgate.github.io/releases/) page for versioned binaries and checksums.

**Development build (internal)**

This repo is private. For internal development or packaging work:
```bash
cargo build --release
# Binary at target/release/cg
```

---

## Content Types

Clip Gate detects **13 types** automatically, ordered by classification priority:

| Type | Example | Detection |
|------|---------|-----------|
| `secret` | `sk_live_1234567890abcdefghij` | 15 exact patterns (AWS, GitHub, Stripe, etc.) + Shannon entropy ≥ 4.5 |
| `error` | `TypeError: Cannot read property 'x'` | Stack traces, error prefixes, traceback keywords |
| `sha` | `a1b2c3d4e5f6...` (40+ hex chars) | Git SHAs, SHA-256/512 checksums |
| `diff` | `diff --git a/main.rs b/main.rs` | Git diffs, unified diff format, hunk headers (`@@`) |
| `path` | `/home/user/project/src/main.rs` | Absolute paths, relative (`./`), home (`~/`) |
| `json` | `{"status": "ok", "count": 42}` | Valid JSON objects and arrays |
| `url` | `https://github.com/clip-gate` | HTTP/HTTPS URLs, localhost:port, www.* domains |
| `sql` | `SELECT id FROM users WHERE active = true` | SQL keywords (SELECT, INSERT, UPDATE, DELETE, JOIN, etc.) |
| `ip` | `192.168.1.1:8080` | IPv4/IPv6 addresses with optional port and CIDR notation |
| `env` | `DATABASE_URL=postgres://localhost/db` | KEY=VALUE pairs in UPPER_SNAKE_CASE, `export` statements |
| `docker` | `FROM rust:1.75-slim` | Dockerfile instructions (FROM, RUN, COPY, etc.) and docker CLI commands |
| `command` | `cargo build --release` | Shell syntax: pipes, flags, `&&`, `sudo`, common CLIs |
| `text` | everything else | Default fallback |

When multiple patterns match, the highest-priority type wins. Each classification includes a confidence score from 0.0 to 1.0.

Secrets are automatically detected, stored in memory only (never written to SQLite), and expire after 5 minutes.

---

## Commands

### `cg copy`

Store text and auto-classify it.

```bash
echo "some text" | cg copy                  # pipe from stdin
cg copy "literal text here"                  # pass as argument
cg copy --from-clipboard                     # read from system clipboard
cg copy -t command -l "deploy"               # override type, add label
cg copy --ttl 60                             # auto-expire after 60 seconds
cg copy --no-persist                         # memory-only (like secrets)
cg copy --policy memory                      # explicit storage policy
cg copy -q                                   # suppress stderr output
```

| Flag | Description |
|------|-------------|
| `-t`, `--type` | Override auto-classification |
| `-l`, `--label` | Attach a human-readable label |
| `--from-clipboard` | Read from system clipboard instead of stdin/arg |
| `--ttl` | Time-to-live in seconds |
| `--no-persist` | Store in memory only, skip SQLite |
| `--policy` | Storage policy: `persist`, `memory`, or `expire` |

By default, `cg copy` prints a one-line confirmation to stderr (e.g., `cg: error 01KN3K4Q`). Use `--quiet` for silence, `--verbose` for full detail.

---

### `cg paste`

Retrieve an item by type, label, or ID.

```bash
cg paste                                     # most recent item (any type)
cg paste -t error                            # most recent error
cg paste -t sha -n 3                         # third most recent SHA
cg paste -i 01KN3K4Q                         # by exact ULID
cg paste -l "deploy"                         # by label
cg paste --secret                            # include secrets in results
cg paste --to-clipboard                      # send to system clipboard
cg paste --with-metadata                     # include type, confidence, timestamp
cg paste --confirm                           # prompt before pasting secrets
```

| Flag | Description |
|------|-------------|
| `-t`, `--type` | Filter by content type |
| `-l`, `--label` | Filter by label |
| `-i`, `--id` | Retrieve by exact ULID |
| `-n`, `--nth` | Nth most recent match (default: 1) |
| `--secret` | Include secret-type items |
| `--confirm` | Interactive confirmation for secrets |
| `--to-clipboard` | Write result to system clipboard |
| `--with-metadata` | Output type, confidence, timestamps |

**Piping:** `cg paste` outputs to stdout, so pipe to commands that **read stdin** — `cat`, `pbcopy`, `grep`, `wc`, `xargs`, etc. Note: `echo` does *not* read stdin, so `cg paste | echo` won't work — use `cg paste | cat` instead.

---

### `cg list`

Show clipboard history as a table.

```bash
cg list                                      # recent items, default limit
cg list -t error                             # only errors
cg list -l 50                                # last 50 items
cg list --all                                # everything, no limit
cg list --plain                              # no box-drawing, plain text
cg list -f json                              # JSON output
```

| Flag | Description |
|------|-------------|
| `-t`, `--type` | Filter by content type |
| `-l`, `--limit` | Max items to show |
| `--all` | Show all items (no limit) |
| `--plain` | Plain text output (no table borders) |
| `-f`, `--format` | Output format: `table`, `json`, `plain` |

---

### `cg search`

Full-text search across clipboard history.

```bash
cg search "TypeError"                        # search by keyword
cg search "deploy" -t command                # search within type
cg search "main.rs" -l 5                     # limit results
```

| Flag | Description |
|------|-------------|
| `-t`, `--type` | Restrict search to a content type |
| `-l`, `--limit` | Max results to return |

---

### `cg pack`

Bundle clipboard items into AI-ready context. The `-t` flag is repeatable.

```bash
cg pack -t error -n 3                        # last 3 errors, text format
cg pack -t error -n 5 | claude "fix"         # pipe to Claude
cg pack -t error -t command -n 10            # errors + commands together
cg pack -f json | jq .                       # structured JSON output
cg pack -f markdown >> issue.md              # for GitHub issues
cg pack --no-header                          # skip the metadata header
cg pack --reverse                            # oldest first
```

| Flag | Description |
|------|-------------|
| `-t`, `--type` | Content type(s) to include (repeatable) |
| `-n`, `--count` | Number of items to pack |
| `-f`, `--format` | Output format: `text`, `json`, `markdown` |
| `--header` / `--no-header` | Include/exclude metadata header |
| `--reverse` | Reverse chronological order |

---

### `cg inspect`

Show how an item was classified — the full breakdown of candidates and scores.

```bash
cg inspect -i 01KN3K4Q                       # inspect by ID
cg inspect -t error                          # inspect most recent error
```

| Flag | Description |
|------|-------------|
| `-i`, `--id` | Item ULID to inspect |
| `-t`, `--type` | Inspect most recent item of this type |

---

### `cg get`

Interactive fuzzy picker powered by fzf.

```bash
cg get                                       # pick from all items
cg get -t error                              # pick from errors only
cg get -l 20                                 # show last 20 items
```

| Flag | Description |
|------|-------------|
| `-t`, `--type` | Filter by content type |
| `-l`, `--limit` | Max items to show in picker |

Requires [fzf](https://github.com/junegunn/fzf) to be installed. Run `cg doctor` to check.

---

### `cg clear`

Delete items from history.

```bash
cg clear -n 2                                # delete 2nd most recent item
cg clear -n 1 -t error                       # delete the latest error
cg clear -t error                            # delete all errors
cg clear --older-than 7d                     # delete items older than 7 days
cg clear -i 01KN3K4Q                         # delete specific item
cg clear --confirm                           # prompt before deleting
```

| Flag | Description |
|------|-------------|
| `-n`, `--nth` | Delete the Nth most recent item (1 = latest) |
| `-t`, `--type` | Delete all items of this type |
| `--older-than` | Delete items older than duration (e.g., `7d`, `24h`) |
| `-i`, `--id` | Delete specific item by ULID |
| `--confirm` | Require confirmation before deleting |

---

### `cg watch`

Start the background clipboard watcher. Polls the system clipboard and auto-classifies new content.

```bash
cg watch                                     # foreground mode (Ctrl+C to stop)
cg watch --daemon                            # background daemon
cg watch --status                            # check if watcher is running
cg watch --stop                              # stop the daemon
```

| Flag | Description |
|------|-------------|
| `--daemon` | Run in background |
| `--status` | Check daemon status via PID file |
| `--stop` | Stop running daemon (SIGTERM) |

The watcher polls every 500ms (configurable), deduplicates via SHA-256 hashing, debounces at 150ms, and stores items through the full classify → guard → store pipeline.

---

### `cg config`

View or modify configuration.

```bash
cg config show                               # print full config
cg config get display.verbose                # get a specific value
cg config set display.verbose true           # always show verbose output
cg config set display.quiet true             # suppress output by default
cg config set display.color false            # disable colors
cg config set history.max_items 10000        # keep more history
cg config set secrets.ttl_seconds 600        # secrets expire in 10 min
```

| Setting | Values | Description |
|---------|--------|-------------|
| `display.verbose` | true/false | Default verbose mode (overridden by -v/-q flags) |
| `display.quiet` | true/false | Default quiet mode (overridden by -v/-q flags) |
| `display.color` | true/false | Enable/disable colored output |
| `history.max_items` | 100–50000 | Maximum items in history |
| `secrets.ttl_seconds` | number | Secret auto-expire time in seconds |

---

### `cg mcp`

Start the MCP (Model Context Protocol) server for AI tool integration.

```bash
cg mcp                                       # starts on stdio
```

Exposes 6 tools over JSON-RPC 2.0 via stdio: `clipboard_get_latest`, `clipboard_get_by_type`, `clipboard_list`, `clipboard_list_types`, `clipboard_search`, `clipboard_pack`. Compatible with Claude Code, Cursor, and any MCP-aware client.

---

### `cg shell-init`

Generate shell aliases and helper functions.

```bash
eval "$(cg shell-init)"                      # auto-detect shell
eval "$(cg shell-init zsh)"                  # explicit shell
```

Add to your `.zshrc`, `.bashrc`, or `config.fish` for persistent aliases.

---

### `cg completions`

Generate shell completion scripts for tab-completion of commands, flags, and arguments.

```bash
cg completions bash > ~/.bash_completion.d/cg        # Bash
cg completions zsh  > ~/.zfunc/_cg                    # Zsh
cg completions fish > ~/.config/fish/completions/cg.fish  # Fish
cg completions powershell > _cg.ps1                   # PowerShell
```

After generating, reload your shell or source the file. For Zsh, ensure `~/.zfunc` is in your `fpath`:
```bash
# Add to .zshrc before compinit
fpath=(~/.zfunc $fpath)
autoload -Uz compinit && compinit
```

---

### `cg doctor`

Run 7 system health checks.

```bash
cg doctor
```

Checks: clipboard adapter availability, SQLite database connectivity, config file validity, fzf installation, shell environment, secret pattern count, and watcher daemon status. Each check reports `[ok]`, `[warn]`, or `[FAIL]`.

---

### `cg push`

Push a clipboard item onto a named stack (LIFO). Save context before switching tasks.

```bash
cg push                                      # push latest item → default stack
cg push -s deploy                            # push onto named stack
cg push -t error                             # push latest error
cg push -i 01KN3K4Q                          # push specific item by ID
```

| Flag | Description |
|------|-------------|
| `-s`, `--stack` | Stack name (default: `default`) |
| `-t`, `--type` | Push latest item of this type |
| `-i`, `--id` | Push specific item by ULID |

---

### `cg pop`

Pop an item from a named stack. Restores saved context.

```bash
cg pop                                       # pop from default stack
cg pop -s deploy                             # pop from named stack
cg pop --peek                                # view top item without removing
cg pop --all                                 # pop all items from stack
cg pop --to-clipboard                        # write popped item to system clipboard
```

| Flag | Description |
|------|-------------|
| `-s`, `--stack` | Stack name (default: `default`) |
| `--peek` | View top item without removing it |
| `--all` | Pop all items |
| `--to-clipboard` | Write result to system clipboard |

---

### `cg stack`

Manage named stacks.

```bash
cg stack list                                # show all stacks with item counts
cg stack clear deploy                        # clear a named stack
```

---

### `cg version`

Print version with logo.

```bash
cg version
```

---

### Global Flags

These flags apply to every command:

| Flag | Description |
|------|-------------|
| `--config` | Path to config file (overrides default) |
| `--db` | Path to SQLite database (overrides default) |
| `-q`, `--quiet` | Suppress all non-essential output |
| `-v`, `--verbose` | Show detailed output with confidence scores |
| `--no-color` | Disable colored output |

---

## Configuration

Zero-config by default. Optional config at `~/.config/clip-gate/config.yml` (respects `XDG_CONFIG_HOME`):

```yaml
version: 1

history:
  max_items: 5000           # 100–50,000
  max_age_days: 30          # 1–365
  max_size_mb: 50           # 10–500
  db_path: null             # override SQLite location
  dedup_window_sec: 300     # deduplication window

watch:
  enabled: false
  debounce_ms: 150
  poll_interval_ms: 500

secrets:
  auto_detect: true
  store: false              # if true, secrets persist to disk (dangerous)
  ttl_seconds: 300          # auto-expire after 5 minutes
  warn_on_paste: true
  patterns: []              # user-defined secret patterns

classifier:
  fallback_threshold: 0.3   # below this → 'text'
  secret_threshold: 0.7     # above this → 'secret'
  custom_types: {}          # reserved for extensibility

display:
  color: true
  preview_chars: 80
  time_format: "relative"
  verbose: false            # default verbose mode
  quiet: false              # default quiet mode

fzf:
  enabled: true
  preview: true
  height: "40%"

mcp:
  enabled: false
  socket_path: null
```

---

## Shell Integration

```bash
eval "$(cg shell-init)"   # add to .zshrc / .bashrc / config.fish
```

**Aliases:**

| Alias | Command | What it does |
|-------|---------|-------------|
| `cgc` | `cg copy` | Quick copy |
| `cgp` | `cg paste` | Quick paste |
| `cge` | `cg paste -t error` | Paste latest error |
| `cgf` | `cg paste -t path` | Paste latest path |
| `cgs` | `cg paste -t sha` | Paste latest SHA |
| `cgl` | `cg list` | List history |
| `cgg` | `cg get` | Interactive fzf picker |

**Helper functions:**

```bash
# Run a command and auto-capture its output to clipboard
cgr cargo test              # runs cargo test, pipes output to cg copy

# Pack items and copy the bundle to system clipboard
cgpack -t error -n 3        # packs 3 errors, sends to pbcopy/xclip
```

---

## AI Integration

### Context Packing

Bundle clipboard items into AI-ready context — pipe directly to Claude, ChatGPT, or Aider:

```bash
cg pack -t error -n 3                                # last 3 errors, text format
cg pack -t error -n 5 | claude "fix these"           # pipe to Claude Code
cg pack -t error -f json | jq .                      # structured output
cg pack -t error -f markdown >> issue.md             # for GitHub issues
cg pack -t error -t command -n 10                    # multiple types
```

### MCP Server

For AI tools that support Model Context Protocol (Claude Code, Cursor):

```bash
cg mcp   # starts MCP server on stdio
```

Your AI assistant gets direct access to 6 tools:

| MCP Tool | Description |
|----------|-------------|
| `clipboard_get_latest` | Most recent item of any type |
| `clipboard_get_by_type` | Most recent item of a specific type |
| `clipboard_list` | List items with optional type filter and limit |
| `clipboard_list_types` | Statistics per type (count, age) |
| `clipboard_search` | Full-text search with optional type filter |
| `clipboard_pack` | Bundle items for export |

---

