# dsh-clipboard-history

English | [中文](README.zh.md)

A [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) (dsh)
plugin that monitors the system clipboard and keeps a recallable history of
multiple clipboard entries.

## What it does

- **Monitors** the system clipboard in the background (polling `pbpaste` on
  macOS, `xclip` on Linux, PowerShell on Windows) and records every text
  change into a persisted history file.
- **Persists** history across restarts at `$DSH_HOME/clipboard-history.json`.
- Exposes five tools to the agent:

| Tool | Purpose |
|---|---|
| `clipboard_list` | List recent history entries (id, time, size, preview). |
| `clipboard_get` | Recall the full text of one entry by id. |
| `clipboard_current` | Read the live clipboard content right now. |
| `clipboard_copy` | Write text to the system clipboard and record it. |
| `clipboard_clear` | Clear the stored history (keeps the live clipboard). |

## Install

```sh
# pnpm is required by the dsh plugin manager (enable via corepack if missing)
corepack enable

# from npm (once published)
dsh plugin --profile web add dsh-clipboard-history

# from a local checkout
dsh plugin --profile web add file:/absolute/path/to/dsh-clipboard-history
```

Then restart the web app (`dsh web`) so the new host plugin is loaded.

The `dsh plugin` command forwards to `pnpm` inside the profile directory and
reconciles `dsh.profile.bundles` automatically: because this package declares
`"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }`, it joins the profile's
patch-layer stack.

## Configuration

Edit the row in the profile's `cordis.patch.yml` (or the `config` block the
bundle inserted) to tune it:

```yaml
- id: clipboard-history
  config:
    pollIntervalMs: 700   # clipboard poll interval in ms
    maxHistory: 200       # max stored entries
    maxEntryChars: 50000  # max stored characters per entry
    previewChars: 160     # preview length in clipboard_list
    historyFile: clipboard-history.json  # relative to the DSH home
    poll: true            # false disables background monitoring
```

## Notes and limitations

- Text only. Image / file clipboards are ignored (they read as empty text).
- macOS is the primary target; Linux needs `xclip`, Windows uses PowerShell.
- The plugin lives in the host process, so it has access to the logged-in
  user's pasteboard without a native addon.