Metadata-Version: 2.4
Name: copa-cli
Version: 0.9.5
Summary: Command Palette — smart command tracking, ranking, and sharing for your shell
Author: Mark Stanford
License-Expression: MIT
Project-URL: Homepage, https://github.com/MaStanford/copa
Project-URL: Repository, https://github.com/MaStanford/copa
Project-URL: Issues, https://github.com/MaStanford/copa/issues
Keywords: cli,command-palette,shell,fzf,productivity
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: System :: Shells
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: click>=8.0
Provides-Extra: mcp
Requires-Dist: mcp; extra == "mcp"
Provides-Extra: ollama
Requires-Dist: requests; extra == "ollama"
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: ruff; extra == "dev"
Dynamic: license-file

# Copa — Command Palette for your shell

[![CI](https://github.com/MaStanford/copa/actions/workflows/ci.yml/badge.svg)](https://github.com/MaStanford/copa/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/copa-cli)](https://pypi.org/project/copa-cli/)
[![Python](https://img.shields.io/pypi/pyversions/copa-cli)](https://pypi.org/project/copa-cli/)

Copa tracks the commands you run, ranks them by frequency and recency, and gives you instant fuzzy search via fzf. Think of it as a smart, searchable, shareable upgrade to shell history.

![Copa Demo](demos/00-hero.gif)

## Features

- **Smart ranking** — commands scored by `2*log(1+freq) + 8*0.5^(age/3d)`, so frequent _and_ recent commands float to the top
- **FTS search** — full-text search across commands and their descriptions
- **fzf integration** — Ctrl+R opens a fuzzy-searchable command palette with preview pane; searches across commands _and_ their descriptions
- **Tab completion** — Copa supplements zsh's tab completion for _any_ command using your command history database
- **Auto-evolution** — `copa evolve` finds your most-used commands from zsh history and promotes them
- **LLM descriptions** — `copa fix --auto` uses Claude or ollama to generate descriptions for undescribed commands
- **Script protocol** — `#@ Description:` / `#@ Usage:` / `#@ Purpose:` / `#@ Flag:` headers in your scripts are auto-detected by `copa scan` across all `$PATH` directories
- **Flag documentation** — document command flags with descriptions; flags are searchable, visible in the preview pane, and preserved in `.copa` exports
- **Inline suggestions** — ghost text appears as you type; Tab accepts or opens a completion menu with the suggestion highlighted
- **Groups & Ctrl+G** — organize commands by project, device, or workflow; assign groups inline from the fzf palette with Ctrl+G
- **Bulk operations** — Ctrl+B enters select mode for batch group assignment, batch deletion, or batch LLM description
- **Recipes** — save multi-step command sequences as named recipes; `copa recipe run deploy` executes steps sequentially; share recipes via `.copa` files
- **Directory-aware suggestions** — commands used in the current directory are boosted in suggestions; automatic, configurable, zero-effort
- **Sharing & `copa create`** — export/import command sets as `.copa` JSON files; `copa create` scaffolds a `.copa` file from an existing group
- **Set filtering** — scope list, search, and fzf to a specific shared set with `--set`
- **MCP server** — expose your commands to Claude Code (or any MCP client)
- **Zero latency** — precmd hook records usage in the background

> **Note:** Copa requires **zsh**. It is not compatible with bash, fish, or PowerShell.

## Install

### Prerequisites

- **Python 3.12+**
- **zsh** — Copa's shell integration (precmd hooks, ZLE widgets, inline suggestions) is zsh-only
- **fzf** — required for Ctrl+R command palette

```bash
# macOS
brew install fzf

# Linux (apt)
sudo apt install fzf

# or see https://github.com/junegunn/fzf#installation
```

### Install Copa

```bash
pip install copa-cli
# or from source:
git clone https://github.com/MaStanford/copa.git
cd copa
pip install -e .

# Optional: ollama backend for LLM descriptions
pip install copa-cli[ollama]
```

### Setup

Run the interactive setup wizard:

```bash
copa setup
```

This walks you through everything:

1. Checks that **fzf** is installed (tells you how to install if missing)
2. Creates the Copa database (`~/.copa/copa.db`)
3. Adds shell integration to your `~/.zshrc` (prompts for confirmation)
4. Optionally imports your zsh history

Then activate Copa in your current terminal:

```bash
source ~/.zshrc
```

### What shell integration does

The `eval "$(copa init zsh)"` line added to your `.zshrc` does three things:

1. **Records every command you run** — a `precmd` hook silently calls `copa _record` in the background after each command, building up frequency and recency data with zero latency impact.
2. **Replaces Ctrl+R** — the default zsh reverse-history-search is replaced with Copa's fzf-powered command palette (see below).
3. **Supplements tab completion** — Copa registers as a completer so that any command gets completion candidates from your Copa database. The behavior is configurable (`fallback`, `hybrid`, `always`, or `never`) — see [Tab Completion](#tab-completion).

### Manual setup

If you prefer to set up manually instead of using `copa setup`:

```bash
# Add shell integration to ~/.zshrc
echo 'eval "$(copa init zsh)"' >> ~/.zshrc

# Activate in current terminal
source ~/.zshrc

# Import your history (optional)
copa sync
```

## Ctrl+R — fzf Command Palette

Once shell integration is sourced, pressing **Ctrl+R** opens an fzf-powered command palette instead of the default zsh reverse search. This is Copa's primary interface.

![Ctrl+R Palette](demos/04-ctrl-r-palette.gif)

### What you see

Copa pipes every tracked command into fzf with aligned columns:

```
 command text (padded)  ┃  [group]  freq×N
```

The left panel shows the command text. The right panel shows metadata: a pin indicator, group badge (dim magenta), and frequency count (dim). Descriptions and flag documentation are not shown in the list — they appear in the preview pane but are still included as a hidden field that fzf searches. This means typing "bluetooth" in fzf will find a command whose description mentions "bluetooth" even if the command text doesn't contain it.

**fzf searches across all fields** — the command text, group names, descriptions, and flag documentation. A hidden search field contains the full description and flag text so fzf's fuzzy matching covers everything even though only the command and metadata columns are displayed.

This is the key difference from plain zsh Ctrl+R: you're not just searching raw history text, you're searching annotated, described, ranked commands.

### Modes

The header shows available modes. Press **Ctrl+R** again while fzf is open to cycle:

| Mode       | Sort order                  | Use case                             |
| ---------- | --------------------------- | ------------------------------------ |
| `all`      | Score (frequency + recency) | Default — best commands float to top |
| `frequent` | Frequency only              | Find your most-used commands         |
| `recent`   | Last used time              | Find commands you ran recently       |
| `recipes`  | Run count                   | Browse and run multi-step recipes    |

### Keybindings

While the fzf palette is open, these keys are available:

| Key        | Action               | Effect                                                                       |
| ---------- | -------------------- | ---------------------------------------------------------------------------- |
| **Ctrl+R** | Cycle mode           | all → frequent → recent → recipes → all                                      |
| **Ctrl+X** | Compose              | Opens a numbered menu to append shell operators (`\|`, `&&`, `>`, `&`, etc.) |
| **Ctrl+S** | Scope by group       | Opens inline group list — Enter filters to that group, ESC returns to all    |
| **Ctrl+G** | Assign group         | Opens inline group list — Enter assigns the group to the highlighted command |

![Groups and Scoping](demos/05-groups-and-scoping.gif)

| Key        | Action        | Effect                                                              |
| ---------- | ------------- | ------------------------------------------------------------------- |
| **Ctrl+N** | Cycle group   | Cycles through groups: (all) → group1 → group2 → ... → (all)        |
| **Ctrl+D** | Describe      | Generate/edit a description using LLM (with tty-aware input)        |
| **Ctrl+F** | Edit flags    | Add flag documentation to the highlighted command                   |
| **Ctrl+B** | Select mode   | Enter multi-select for bulk operations (see below)                  |
| **Ctrl+H** | Toggle header | Show/hide the key hints for more screen space                       |
| **ESC**    | Cancel/back   | In scope/group mode: returns to command list. Otherwise: closes fzf |

Keybindings are configurable via `~/.copa/config.toml`. See [Configuration](#configuration).

### Select mode (bulk operations)

![Bulk Operations](demos/06-bulk-operations.gif)

Press **Ctrl+B** from the Ctrl+R palette to enter **select mode**. This opens a new fzf view with multi-select enabled:

- **Tab** toggles selection on individual commands
- **Ctrl+R** cycles modes (all → frequent → recent) just like the main palette
- **Enter** confirms your selection and shows the batch action menu
- **ESC** cancels and returns to your prompt

After selecting commands, Copa shows a batch action menu:

```
Selected 5 command(s).
  g = assign group
  d = delete
  a = auto-describe (LLM)
  q = cancel
Action:
```

| Action | What it does                                                                           |
| ------ | -------------------------------------------------------------------------------------- |
| **g**  | Assign all selected commands to a group (or clear their group)                         |
| **d**  | Delete all selected commands (with confirmation)                                       |
| **a**  | Auto-generate descriptions for all selected commands using your configured LLM backend |

This is useful for organizing large command sets — select 20 undescribed commands and batch-describe them, or move a set of related commands into a group in one step.

### Preview pane

The right side shows a detail card for the highlighted command: full description, usage, purpose, flag documentation, score breakdown, frequency, last used, source, group, shared set, and tags.

### Result

Selecting a command places it directly into your shell prompt (without executing it), so you can review or edit before pressing Enter.

## Tab Completion

![Tab Menu Select](demos/03-tab-menu-select.gif)

Copa supplements zsh's built-in tab completion for **any** command — not just Copa's own CLI. Once `copa.zsh` is sourced, Copa registers as a completer in zsh's completion system.

### Completion modes

![Completion Modes](demos/10-completion-modes.gif)

Copa supports four completion modes, configured via `~/.copa/config.toml`:

| Mode       | Behavior                                                                      |
| ---------- | ----------------------------------------------------------------------------- |
| `fallback` | **(default)** Only show Copa completions when native completers found nothing |
| `hybrid`   | Show Copa completions alongside native completions (in a separate group)      |
| `always`   | Copa completions replace native completions                                   |
| `never`    | Disable Copa tab completion entirely                                          |

```toml
# ~/.copa/config.toml
[completion]
mode = "fallback"    # fallback | hybrid | always | never
branding = true      # show "Copa history" group header
```

### How it works

When you press Tab, Copa queries its database for commands matching what you've typed so far and suggests the next word(s):

```
$ adb shell dump<TAB>
→ dumpsys  dumpstate
```

Copa looks at your tracked commands starting with `adb shell dump` and extracts the next word from each match. Candidates are deduplicated and ordered by frequency.

### Examples

```bash
# Complete subcommands for adb
adb <TAB>
→ shell  devices  logcat  push  pull  ...

# Complete arguments deeper in the command
adb shell cmd bluetooth_manager <TAB>
→ enable  disable  ...
```

This works automatically once `copa.zsh` is sourced — no extra setup needed. The more commands you use (and track with Copa), the better the completions get.

Copa's own CLI completions (`copa li<TAB>` → `list`) continue to work as before via Click's built-in completion.

## Inline Suggestions (Ghost Text)

| Tab Mode 1 (direct accept)                         | Tab Mode 2 (menu select, default)                  |
| -------------------------------------------------- | -------------------------------------------------- |
| ![Tab Mode 1](demos/02a-suggestions-tab-mode1.gif) | ![Tab Mode 2](demos/02b-suggestions-tab-mode2.gif) |

Copa shows grey ghost text after your cursor as you type — the best matching command from your database, ranked by frequency and recency. This works like fish shell's autosuggestions or zsh-autosuggestions, with zero plugin dependencies.

### How it works

As you type, Copa queries its database for commands starting with your current input and displays the highest-scored match as dim grey text after the cursor. The suggestion updates on every keystroke.

```
$ git pu█sh origin main     ← grey ghost text
```

### Keybindings

| Key                 | Suggestion showing                                                                                                                                  | No suggestion                                                          |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| Type chars          | Insert char, re-fetch suggestion                                                                                                                    | Insert char, fetch suggestion                                          |
| Backspace           | Delete char, **latch** (suppress suggestions)                                                                                                       | Delete char normally                                                   |
| **Tab**             | `tab_accept=1`: accept full suggestion. `tab_accept=2` (default): open completion menu with suggestion highlighted at top, native completions below | If latched: unlatch + re-fetch suggestion. Else: normal tab completion |
| **Down**            | Open completion menu with suggestion highlighted at top                                                                                             | History navigation                                                     |
| **Right arrow**     | Accept one word, re-fetch                                                                                                                           | Move cursor right                                                      |
| **Cmd+Right / End** | Accept full suggestion                                                                                                                              | Move to end of line                                                    |
| Enter               | Clear suggestion, execute                                                                                                                           | Execute                                                                |
| Esc                 | Dismiss suggestion                                                                                                                                  | Normal Esc                                                             |
| Up                  | Clear suggestion, navigate history                                                                                                                  | History navigation                                                     |
| Ctrl+R              | Clear suggestion, open fzf                                                                                                                          | Open fzf                                                               |

### Tab accept mode

Copa supports two Tab behaviors when a suggestion is showing:

**Menu select** (`tab_accept = 2`, default):

1. Press **Tab** — ghost text clears, a completion menu opens with the Copa suggestion highlighted at the top, alongside native completions below
2. Press **Tab** to cycle through options, **Shift+Tab** to cycle backward
3. Press **Enter** or **Space** — accepts the highlighted item
4. Press **Escape** — cancels the menu, restores your original text
5. Use **arrow keys** to navigate if you want a different completion

This gives you a chance to see alternatives before committing. The Copa suggestion is always the first item in the menu.

**Inline accept** (`tab_accept = 1`):

- Press **Tab** — the suggestion is accepted directly into your command line. One keystroke, done.

### Completion menu navigation

When the completion menu is open (from Tab in `tab_accept = 2` mode or from normal tab completion):

| Key            | Action                                       |
| -------------- | -------------------------------------------- |
| **Tab**        | Cycle forward through completions                          |
| **Shift+Tab**  | Cycle backward through completions                         |
| **Enter**      | Accept the highlighted completion (no trailing space added) |
| **Space**      | Accept the highlighted completion and add a space           |
| **Escape**     | Cancel — dismiss menu, restore original text                |
| **Arrow keys** | Navigate between completions                                |

### Backspace latch

Pressing Backspace clears the current suggestion and **latches** — suppresses further suggestions while you edit. This prevents suggestions from re-appearing as you retype after correcting a mistake. Ctrl+W (backward-kill-word) also latches.

Press **Tab** to unlatch and re-enable suggestions. The next new prompt (Enter) also resets the latch automatically.

### Configuration

```toml
# ~/.copa/config.toml
[suggest]
enabled = true       # set to false to disable inline suggestions
min_length = 2       # minimum characters before querying (default: 2)
tab_accept = 2       # 1 = Tab accepts directly, 2 = Tab opens menu first (default)
color = 242          # ghost text color (256-color palette, default: 242 mid-grey)
```

The `color` value is a [256-color palette](https://en.wikipedia.org/wiki/ANSI_escape_code#8-bit) number. Some useful values: `240` (darker grey), `242` (default mid-grey), `245` (lighter grey), `8` (bright black), `244` (light grey).

Inline suggestions are enabled by default. Set `enabled = false` to disable them entirely (zero performance overhead when disabled).

## Quick Start

```bash
# Check your setup
copa doctor

# Import your shell history
copa sync

# Add a command manually
copa add "adb shell cmd bluetooth_manager enable" -d "Enable Bluetooth" -g bluetooth

# Add a command with flag documentation
copa add "flash_all" -d "Flash AOSP build" -f "--wipe: Wipe userdata" -f "-v: Verbose"

# Pin your most important commands to the top
copa pin 42

# Edit a command's metadata
copa edit 42 -d "New description" -g mygroup

# List top commands by score
copa list

# List as JSON (for scripting)
copa list --json

# Search by keyword
copa search bluetooth

# Create a .copa file from a group (or scaffold an empty one)
copa create -g bluetooth

# Auto-promote frequent commands from history
copa evolve -k 20

# Auto-promote and generate descriptions in one pass
copa evolve -k 20 --auto

# Generate descriptions with LLM
copa fix --auto

# Scan $PATH for scripts with metadata
copa scan

# Open fzf command palette (or press Ctrl+R)
copa fzf-list --mode all | fzf
```

## LLM-Powered Descriptions

Copa can use an LLM to auto-generate descriptions for your undescribed commands. Two backends are supported:

### Configure

```bash
copa configure
```

This prompts you to choose a backend:

- **claude** (default) — shells out to the `claude` CLI. No API key needed if Claude Code is already authenticated.
- **ollama** — calls a local ollama server at `localhost:11434`. Copa checks that ollama is installed and running, prompts for a model name, and offers to pull it if missing.

Settings are stored in the Copa database (`meta` table).

### Bulk descriptions with `copa fix --auto`

```bash
# First, add undescribed commands
copa evolve -k 20

# Then generate descriptions with LLM suggestions
copa fix --auto

# Or do both in one step
copa evolve -k 20 --auto
```

With `--auto`, each command gets an LLM-generated suggestion:

```
  [42] adb shell dumpsys bluetooth_manager
  Suggestion: Dump Bluetooth manager state
  Description [Dump Bluetooth manager state]:
```

- Press **Enter** to accept the suggestion
- **Type** a replacement to override it
- Press **q** to quit

Without `--auto`, `copa fix` behaves as before (blank prompt, Enter to skip).

### Single command description

```bash
copa describe 42
```

Generates a description for a specific command by ID. Same accept/edit flow as `fix --auto`.

![Flags and Describe](demos/09-flags-and-describe.gif)

## Script Metadata Protocol

Copa recognizes `#@` headers in script files (checked in the first 50 lines):

```bash
#!/bin/bash
#@ Description: Flash AOSP build to connected device
#@ Usage: flash_all.py <build-dir> -w [--skip firmware vendor_boot ...]
#@ Purpose: Streamline the device flashing workflow
#@ Flag: -w, --wipe: Wipe userdata before flashing
#@ Flag: --skip <parts>: Skip specific partitions
#@ Flag: -n, --dry-run: Show what would be done without flashing
```

When scanned, Description, Usage, Purpose, and Flags are stored and displayed in the Ctrl+R preview pane:

```
Description: Flash AOSP build to connected device
Usage:       flash_all.py <build-dir> -w [--skip firmware vendor_boot ...]
Purpose:     Streamline the device flashing workflow

Flags:
  -w, --wipe           Wipe userdata before flashing
  --skip <parts>       Skip specific partitions
  -n, --dry-run        Show what would be done without flashing
```

### Supported headers

| Header                           | Effect                                          |
| -------------------------------- | ----------------------------------------------- |
| `#@ Description: <text>`         | Sets the command description (highest priority) |
| `#@ Usage: <text>`               | Usage / invocation syntax                       |
| `#@ Purpose: <text>`             | Why the script exists / when to use it          |
| `#@ Flag: <flag>: <description>` | Document a flag/option (repeatable)             |

Scripts without `#@` headers still work — Copa falls back to legacy patterns (`# Description:`, `# Purpose:`, Python docstrings, generic comments).

### Scan scripts

```bash
copa scan               # scans all $PATH directories
copa scan --dir ~/bin   # scan a specific directory
```

## Sharing

![Sharing](demos/07-sharing.gif)

Export a group as a `.copa` file:

```bash
# Using copa create (recommended — creates a .copa file you can edit)
copa create -g bluetooth

# Or using share export (direct export)
copa share export bluetooth -o bluetooth.copa
```

Share it with your team (via git, Slack, or any file share):

```bash
copa share load bluetooth.copa
copa share load /path/to/team/commands.copa
copa share sync /path/to/team/copa-files/
```

### Example shared sets

Copa ships with ready-to-use `.copa` files in the [`examples/`](examples/) directory:

| File                                                          | Description                            |
| ------------------------------------------------------------- | -------------------------------------- |
| [`git.copa`](examples/git.copa)                               | Essential Git commands                 |
| [`docker.copa`](examples/docker.copa)                         | Docker container management            |
| [`python-dev.copa`](examples/python-dev.copa)                 | Python development workflow            |
| [`npm.copa`](examples/npm.copa)                               | Node.js package management             |
| [`network.copa`](examples/network.copa)                       | Network diagnostics                    |
| [`curl-http.copa`](examples/curl-http.copa)                   | HTTP requests and API testing          |
| [`ssh-remote.copa`](examples/ssh-remote.copa)                 | SSH, SCP, and remote server management |
| [`adb.copa`](examples/adb.copa)                               | Android Debug Bridge                   |
| [`aws.copa`](examples/aws.copa)                               | AWS CLI cloud infrastructure           |
| [`terraform.copa`](examples/terraform.copa)                   | Terraform infrastructure-as-code       |
| [`k8s.copa`](examples/k8s.copa)                               | Kubernetes cluster management          |
| [`systemd.copa`](examples/systemd.copa)                       | Linux service management               |
| [`sysadmin.copa`](examples/sysadmin.copa)                     | System administration                  |
| [`process-monitoring.copa`](examples/process-monitoring.copa) | Process management and debugging       |
| [`disk-files.copa`](examples/disk-files.copa)                 | Disk usage and file management         |
| [`tmux.copa`](examples/tmux.copa)                             | Terminal multiplexer sessions          |
| [`homebrew.copa`](examples/homebrew.copa)                     | Homebrew package manager (macOS)       |

Load any of them:

```bash
copa share load examples/git.copa
copa share load examples/docker.copa
```

### Filtering by shared set

Once you've loaded shared sets, you can scope commands to just that set:

```bash
# List only commands from the bluetooth shared set
copa list --set bluetooth

# Search within a shared set
copa search "enable" --set bluetooth

# fzf filtered to a shared set
copa fzf-list --mode set --set bluetooth | fzf
```

You can also filter by source type:

```bash
copa search "adb" --source shared
copa list --source scan
```

Create an alias for quick set-scoped search:

```bash
alias copa-bt='copa fzf-list --set bluetooth | fzf'
```

### `.copa` file format

```json
{
  "copa_version": "1.0",
  "name": "bluetooth",
  "description": "Bluetooth commands for Android devices",
  "author": "markstanford",
  "commands": [
    {
      "command": "adb shell cmd bluetooth_manager enable",
      "description": "Enable Bluetooth",
      "tags": ["bt", "android"]
    },
    {
      "command": "flash_all",
      "description": "Flash AOSP build to device",
      "tags": ["aosp"],
      "flags": {
        "-w, --wipe": "Wipe userdata before flashing",
        "--skip <parts>": "Skip specific partitions"
      }
    }
  ],
  "recipes": [
    {
      "name": "bt-debug",
      "description": "Enable BT and start logging",
      "steps": [
        {"command": "adb shell cmd bluetooth_manager enable", "description": "Enable BT"},
        {"command": "adb logcat -s bt_btif | tee bt.log", "description": "Start BT logging"}
      ]
    }
  ]
}
```

## Recipes

![Recipes Demo](demos/12-recipes.gif)

Recipes are named, ordered sequences of commands — like a script, but tracked and shareable through Copa.

### Creating recipes

```bash
# Simple recipe
copa recipe add deploy \
  -s 'npm run build' \
  -s 'docker build -t app .' \
  -s 'docker push app'

# With descriptions (use :: separator)
copa recipe add deploy \
  -d "Full production deploy" \
  -g devops \
  -s 'npm run build :: Build the project' \
  -s 'npm run test :: Run test suite' \
  -s 'docker push app :: Push to registry'
```

### Running recipes

```bash
# Run all steps sequentially
copa recipe run deploy

# Preview without executing
copa recipe run deploy --dry-run

# Continue past failures
copa recipe run deploy --no-stop-on-error
```

### Managing recipes

```bash
copa recipe list              # List all recipes
copa recipe list --json       # JSON output
copa recipe show deploy       # Show steps
copa recipe remove deploy     # Delete a recipe
```

### Sharing recipes

Recipes are included in `.copa` files automatically — when you export a group, its recipes come along:

```bash
copa share export devops -o devops.copa    # includes recipes in that group
copa share load devops.copa                # imports commands AND recipes
```

See `examples/docker.copa` and `examples/deploy.copa` for recipe examples.

## MCP Server (Claude Code integration)

Copa includes an MCP server so Claude Code can search and add commands.

Install the MCP dependency:

```bash
pip install copa-cli[mcp]
```

Add to your Claude Code MCP config (`.mcp.json` in your project or home dir):

```json
{
  "mcpServers": {
    "copa": {
      "command": "python3",
      "args": ["-m", "copa.mcp_server"]
    }
  }
}
```

Available MCP tools:

- `copa_search` — search commands by keyword
- `copa_list_commands` — list commands ranked by score
- `copa_list_groups` — list all groups
- `copa_get_stats` — usage statistics
- `copa_add_command` — add a command
- `copa_update_description` — update a description
- `copa_delete_command` — delete a command by ID
- `copa_set_group` — set or change a command's group
- `copa_update_flags` — update flag documentation for a command
- `copa_pin_command` — pin or unpin a command
- `copa_create_group` — create a group with commands
- `copa_bulk_add` — bulk add commands
- `copa_share_load` — load a .copa file as a shared set
- `copa_share_list` — list all loaded shared sets
- `copa_share_remove` — remove a shared set
- `copa_export_group` — export a group as a .copa file
- `copa_recipe_list` — list all recipes
- `copa_recipe_show` — show a recipe's steps
- `copa_recipe_add` — create a recipe from ordered steps
- `copa_recipe_remove` — remove a recipe

## Configuration

Copa is configured via `~/.copa/config.toml`. All settings are optional — Copa uses sensible defaults.

```toml
# ~/.copa/config.toml

# Keybindings for the Ctrl+R fzf palette
# Values are fzf key names: ctrl-<letter>, alt-<letter>, ctrl-/
# ctrl-r and enter are reserved and cannot be reassigned
[keys]
compose = "ctrl-x"          # open compose submenu (|, &&, >, &, 2>&1, 2>/dev/null)
describe = "ctrl-d"         # LLM describe
group = "ctrl-g"            # assign group (inline modal)
flags = "ctrl-f"            # edit flags
filter_group = "ctrl-s"     # scope by group (inline modal)
cycle_group = "ctrl-n"      # cycle through groups
select = "ctrl-b"           # enter select mode (bulk operations)
toggle_header = "ctrl-h"    # show/hide key hints

# Tab completion behavior
[completion]
mode = "fallback"           # fallback | hybrid | always | never
branding = true             # show "Copa history" group header

# Inline suggestions (ghost text)
[suggest]
enabled = true              # set to false to disable
min_length = 2              # minimum chars before querying
tab_accept = 2              # 1 = accept directly, 2 = open menu first
color = 242                 # ghost text color (256-color palette)
directory_aware = true      # boost suggestions from the current directory

# Fzf layout
[layout]
height = "80%"              # fzf height (default: 80%)
preview_size = "40%"        # preview pane width (default: 40%)
```

### Compose submenu

![Composition](demos/08-composition.gif)

Press **Ctrl+X** while a command is highlighted to open the compose submenu — an fzf-powered operator picker with arrow keys, Tab, and highlighting:

| Operator      | Behavior   | What happens                                                |
|---------------|------------|-------------------------------------------------------------|
| `\|`          | continue   | Appends `\|` and re-opens fzf to select the next command    |
| `&&`          | continue   | Appends `&&` and re-opens fzf to chain another command      |
| `>`           | continue   | Appends `>` and re-opens fzf for the target                 |
| `&`           | close      | Appends `&` and closes — run in background                  |
| `2>&1`        | close      | Appends `2>&1` and closes — merge stderr                    |
| `2>/dev/null` | close      | Appends `2>/dev/null` and closes — suppress stderr          |

"Continue" operators re-open fzf so you can build multi-command pipelines. "Close" operators place the final command in your prompt. Press **Esc** to cancel and return to the main palette.

When chaining, the prompt shows your accumulated command: `copa [git pull && ]>`.

## End-to-End Workflow

![Workflow](demos/11-workflow.gif)

## CLI Reference

| Command                                                  | Purpose                                                     |
| -------------------------------------------------------- | ----------------------------------------------------------- |
| `copa setup`                                             | Interactive setup wizard                                    |
| `copa add "cmd" -d "desc" -g group -f "flag: desc"`      | Save a command (with optional flags)                        |
| `copa edit ID [-d desc] [-g group] [-f flags] [--pin]`   | Edit a command's metadata                                   |
| `copa remove ID`                                         | Remove a command                                            |
| `copa pin ID`                                            | Pin a command to the top                                    |
| `copa unpin ID`                                          | Unpin a command                                             |
| `copa list [-g group] [-s source] [--set name] [--json]` | List by score                                               |
| `copa search "query" [-g group] [--set name] [--json]`   | FTS search                                                  |
| `copa create -g group [-o file]`                         | Create a .copa file from a group                            |
| `copa stats`                                             | Usage statistics                                            |
| `copa doctor`                                            | Check setup and diagnose issues                             |
| `copa sync`                                              | Import from zsh history                                     |
| `copa scan [--dir path]`                                 | Import script metadata from $PATH                           |
| `copa evolve [-k 20] [--auto]`                           | Auto-add frequent commands (with optional LLM descriptions) |
| `copa fix [--auto]`                                      | Add missing descriptions (with optional LLM)                |
| `copa describe ID`                                       | Generate description for one command                        |
| `copa configure`                                         | Set LLM backend (claude/ollama)                             |
| `copa share export GROUP -o file`                        | Export group                                                |
| `copa share load SOURCE`                                 | Load shared set                                             |
| `copa share list`                                        | List shared sets                                            |
| `copa share sync DIR`                                    | Sync .copa files from dir                                   |
| `copa import FILE [-g group]`                            | Import commands from markdown                               |
| `copa recipe add NAME -s 'cmd' [-s 'cmd' ...]`          | Create a multi-step recipe                                  |
| `copa recipe list [--json]`                              | List all recipes                                            |
| `copa recipe show NAME`                                  | Show a recipe's steps                                       |
| `copa recipe run NAME [--dry-run]`                       | Run a recipe's steps sequentially                           |
| `copa recipe remove NAME`                                | Remove a recipe                                             |
| `copa reset`                                             | Wipe database and start fresh (keeps config)                |
| `copa uninstall`                                         | Remove Copa data and show cleanup steps                     |

## How Scoring Works

```
score = 2.0 * log(1 + frequency) + 8.0 * 0.5^(age_seconds / 3_days)
```

Pinned commands get a +1000 bonus. The 3-day half-life means commands used in the last few days are strongly favored — a command used today scores ~8.0 recency, after 3 days ~4.0, after a week ~1.6.

When `directory_aware = true` (default), commands get a bonus based on where you are: +5.0 for the same directory, +2.0 for a parent or child directory. This means `git push` suggests your project's branch, not another repo's.

## License

MIT
