# sentriz/cliphist architecture

> Architecture diagram of the GitHub repository sentriz/cliphist, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/sentriz/cliphist
- Repository: https://github.com/sentriz/cliphist

## Overview

cliphist is a pipe-oriented Wayland clipboard-history manager. Its main workflow watches clipboard changes and stores them, lists selectable previews, then decodes a selected ID to restore the original bytes. It also supports metadata listing, deletion, expiration, and compaction. The sampled implementation is a single Go source file; README-described picker and image-preview integrations are shown where their paths are documented, but their internal behavior was not inspected.

Main entry points: [`cliphist.go`](https://github.com/sentriz/cliphist/blob/master/cliphist.go) (cliphist CLI), [`contrib`](https://github.com/sentriz/cliphist/tree/master/contrib) (Image picker scripts)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_commands["History commands"]
  node_cli["cliphist CLI<br/>[cliphist.go]"]
  node_store["Store clipboard<br/>[cliphist.go]"]
  node_list["List entries<br/>[cliphist.go]"]
  node_decode["Decode entry<br/>[cliphist.go]"]
  node_delete["Delete entry<br/>[cliphist.go]"]
  node_deletequery["Delete by query<br/>[cliphist.go]"]
  node_wipe["Wipe / expire<br/>[cliphist.go]"]
  node_compact["Compact history<br/>[cliphist.go]"]
end

subgraph group_data["History data"]
  node_metadata["Metadata and previews<br/>[cliphist.go]"]
  node_db[("BoltDB history<br/>[cliphist.go]")]
end

subgraph group_integrations["Picker integrations"]
  node_picker["Menu / picker"]
  node_imagepickers["Image picker scripts"]
end

node_user(("User"))
node_watcher(("wl-paste watcher"))
node_wlcopy["wl-copy"]

node_user -->|"starts watch"| node_watcher
node_watcher -->|"pipes clipboard"| node_cli
node_user -->|"runs command"| node_cli
node_cli -->|"dispatches"| node_store
node_cli -->|"dispatches"| node_list
node_cli -->|"dispatches"| node_decode
node_cli -->|"dispatches"| node_delete
node_cli -->|"dispatches"| node_deletequery
node_cli -->|"dispatches"| node_wipe
node_cli -->|"dispatches"| node_compact
node_store -->|"writes entries"| node_db
node_store -->|"records metadata"| node_metadata
node_list -->|"reads entries"| node_db
node_list -->|"formats fields"| node_metadata
node_list -->|"pipes listing"| node_picker
node_picker -->|"pipes selection"| node_decode
node_decode -->|"reads original bytes"| node_db
node_decode -->|"pipes restored bytes"| node_wlcopy
node_delete -->|"deletes selected"| node_db
node_deletequery -->|"deletes matches"| node_db
node_wipe -->|"removes entries"| node_db
node_wipe -->|"compacts afterward"| node_compact
node_compact -->|"rewrites store"| node_db
node_imagepickers -.->|"uses listing"| node_list
node_imagepickers -.->|"uses restoration"| node_decode

click node_cli "https://github.com/sentriz/cliphist/blob/master/cliphist.go"
click node_store "https://github.com/sentriz/cliphist/blob/master/cliphist.go"
click node_list "https://github.com/sentriz/cliphist/blob/master/cliphist.go"
click node_decode "https://github.com/sentriz/cliphist/blob/master/cliphist.go"
click node_delete "https://github.com/sentriz/cliphist/blob/master/cliphist.go"
click node_deletequery "https://github.com/sentriz/cliphist/blob/master/cliphist.go"
click node_wipe "https://github.com/sentriz/cliphist/blob/master/cliphist.go"
click node_compact "https://github.com/sentriz/cliphist/blob/master/cliphist.go"
click node_metadata "https://github.com/sentriz/cliphist/blob/master/cliphist.go"
click node_db "https://github.com/sentriz/cliphist/blob/master/cliphist.go"
click node_imagepickers "https://github.com/sentriz/cliphist/tree/master/contrib"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_cli,node_store,node_list,node_decode,node_delete,node_deletequery,node_wipe,node_compact,node_user toneBlue
class node_metadata,node_db toneAmber
class node_picker,node_imagepickers toneMint
class node_watcher,node_wlcopy toneIndigo
```

## Components

### History commands

- [cliphist CLI](https://github.com/sentriz/cliphist/blob/master/cliphist.go): `cliphist.go`
- [Store clipboard](https://github.com/sentriz/cliphist/blob/master/cliphist.go): `cliphist.go`
- [List entries](https://github.com/sentriz/cliphist/blob/master/cliphist.go): `cliphist.go`
- [Decode entry](https://github.com/sentriz/cliphist/blob/master/cliphist.go): `cliphist.go`
- [Delete entry](https://github.com/sentriz/cliphist/blob/master/cliphist.go): `cliphist.go`
- [Delete by query](https://github.com/sentriz/cliphist/blob/master/cliphist.go): `cliphist.go`
- [Wipe / expire](https://github.com/sentriz/cliphist/blob/master/cliphist.go): `cliphist.go`
- [Compact history](https://github.com/sentriz/cliphist/blob/master/cliphist.go): `cliphist.go`

### History data

- [Metadata and previews](https://github.com/sentriz/cliphist/blob/master/cliphist.go): `cliphist.go`
- [BoltDB history](https://github.com/sentriz/cliphist/blob/master/cliphist.go): `cliphist.go`

### Picker integrations

- **Menu / picker**
- [Image picker scripts](https://github.com/sentriz/cliphist/tree/master/contrib): `contrib`

### Other components

- **User**
- **wl-paste watcher**
- **wl-copy**

## Connections

- User → wl-paste watcher: starts watch
- wl-paste watcher → cliphist CLI: pipes clipboard
- User → cliphist CLI: runs command
- cliphist CLI → Store clipboard: dispatches
- cliphist CLI → List entries: dispatches
- cliphist CLI → Decode entry: dispatches
- cliphist CLI → Delete entry: dispatches
- cliphist CLI → Delete by query: dispatches
- cliphist CLI → Wipe / expire: dispatches
- cliphist CLI → Compact history: dispatches
- Store clipboard → BoltDB history: writes entries
- Store clipboard → Metadata and previews: records metadata
- List entries → BoltDB history: reads entries
- List entries → Metadata and previews: formats fields
- List entries → Menu / picker: pipes listing
- Menu / picker → Decode entry: pipes selection
- Decode entry → BoltDB history: reads original bytes
- Decode entry → wl-copy: pipes restored bytes
- Delete entry → BoltDB history: deletes selected
- Delete by query → BoltDB history: deletes matches
- Wipe / expire → BoltDB history: removes entries
- Wipe / expire → Compact history: compacts afterward
- Compact history → BoltDB history: rewrites store
- Image picker scripts → List entries: uses listing
- Image picker scripts → Decode entry: uses restoration