# wraithyy/herdr-waypoint architecture

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

- Interactive diagram: https://gitdiagram.com/wraithyy/herdr-waypoint
- Repository: https://github.com/wraithyy/herdr-waypoint

## Overview

herdr-waypoint is a herdr plugin for saving folders as named waypoints and reopening them as focused workspaces. The main workflow saves the current workspace folder and label, then lets a user choose a saved waypoint in a terminal picker and create a workspace from it. The README documents both fzf and fallback pickers, rename/delete, previews, direct CLI saving, and keybinding setup. Relationships below follow those documented behaviors; source excerpts were unavailable, so uncertain internal wiring is omitted.

Main entry points: [`bin/pane-pick`](https://github.com/wraithyy/herdr-waypoint/blob/master/bin/pane-pick) (fzf Picker), [`bin/lib.sh`](https://github.com/wraithyy/herdr-waypoint/blob/master/bin/lib.sh) (Waypoint Operations), [`bin/pick-fallback`](https://github.com/wraithyy/herdr-waypoint/blob/master/bin/pick-fallback) (Fallback Picker), [`bin/action-add.sh`](https://github.com/wraithyy/herdr-waypoint/blob/master/bin/action-add.sh) (Add Action)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_save["Save Waypoints"]
  node_add_action["Add Action<br/>[action-add.sh]"]
  node_cli_add["CLI Add"]
end

subgraph group_pick["Pick And Open"]
  node_picker_action["Pick Action<br/>[open-pick.sh]"]
  node_pane_picker["Pane Picker"]
  node_fzf_picker["fzf Picker"]
  node_fallback_picker["Fallback Picker"]
end

subgraph group_store["Waypoint Store"]
  node_rename["Rename Command"]
  node_remove["Remove Command"]
  node_library["Waypoint Operations<br/>[lib.sh]"]
  node_waypoints[("Waypoints File")]
end

subgraph group_integrations["herdr Integration"]
  node_server["herdr Server"]
  node_workspace["Workspace Context"]
  node_workspace_create["Workspace Create"]
  node_keybinds["Keybinding Setup"]
end

node_user(("User"))
node_fzf["fzf"]
node_git["git status"]
node_directory_listing["ls -la"]

node_user -->|"save key"| node_add_action
node_server -->|"dispatches"| node_add_action
node_add_action -->|"reads context"| node_workspace
node_add_action -->|"adds waypoint"| node_library
node_user -->|"runs command"| node_cli_add
node_cli_add -->|"adds waypoint"| node_library
node_library -->|"reads and writes"| node_waypoints
node_user -->|"pick key"| node_picker_action
node_server -->|"dispatches"| node_picker_action
node_picker_action -->|"opens overlay"| node_pane_picker
node_pane_picker -.->|"uses when available"| node_fzf_picker
node_pane_picker -->|"otherwise uses"| node_fallback_picker
node_fzf_picker -->|"reads entries"| node_waypoints
node_fallback_picker -->|"reads entries"| node_waypoints
node_fzf_picker -->|"invokes"| node_rename
node_fzf_picker -->|"invokes"| node_remove
node_fallback_picker -->|"renames or removes"| node_library
node_rename -->|"renames"| node_library
node_remove -->|"removes"| node_library
node_fzf_picker -.->|"previews status"| node_git
node_fzf_picker -->|"fallback preview"| node_directory_listing
node_fzf_picker -->|"opens selection"| node_workspace_create
node_fallback_picker -->|"opens selection"| node_workspace_create
node_workspace_create -->|"creates focused workspace"| node_server
node_server -.->|"runs startup hook"| node_keybinds
node_keybinds -->|"binds actions"| node_server

click node_add_action "https://github.com/wraithyy/herdr-waypoint/blob/master/bin/action-add.sh"
click node_cli_add "https://github.com/wraithyy/herdr-waypoint/blob/master/bin/cli-add"
click node_picker_action "https://github.com/wraithyy/herdr-waypoint/blob/master/bin/open-pick.sh"
click node_pane_picker "https://github.com/wraithyy/herdr-waypoint/blob/master/bin/pane-pick"
click node_fzf_picker "https://github.com/wraithyy/herdr-waypoint/blob/master/bin/pane-pick"
click node_fallback_picker "https://github.com/wraithyy/herdr-waypoint/blob/master/bin/pick-fallback"
click node_rename "https://github.com/wraithyy/herdr-waypoint/blob/master/bin/wp-rename"
click node_remove "https://github.com/wraithyy/herdr-waypoint/blob/master/bin/wp-rm"
click node_library "https://github.com/wraithyy/herdr-waypoint/blob/master/bin/lib.sh"
click node_keybinds "https://github.com/wraithyy/herdr-waypoint/blob/master/bin/install-keybinds.sh"

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_add_action,node_cli_add,node_user toneBlue
class node_picker_action,node_pane_picker,node_fzf_picker,node_fallback_picker toneAmber
class node_rename,node_remove,node_library,node_waypoints toneMint
class node_server,node_workspace,node_workspace_create,node_keybinds toneRose
class node_fzf,node_git,node_directory_listing toneIndigo
```

## Components

### Save Waypoints

- [Add Action](https://github.com/wraithyy/herdr-waypoint/blob/master/bin/action-add.sh): `bin/action-add.sh`
- [CLI Add](https://github.com/wraithyy/herdr-waypoint/blob/master/bin/cli-add): `bin/cli-add`

### Pick And Open

- [Pick Action](https://github.com/wraithyy/herdr-waypoint/blob/master/bin/open-pick.sh): `bin/open-pick.sh`
- [Pane Picker](https://github.com/wraithyy/herdr-waypoint/blob/master/bin/pane-pick): `bin/pane-pick`
- [fzf Picker](https://github.com/wraithyy/herdr-waypoint/blob/master/bin/pane-pick): `bin/pane-pick`
- [Fallback Picker](https://github.com/wraithyy/herdr-waypoint/blob/master/bin/pick-fallback): `bin/pick-fallback`

### Waypoint Store

- [Rename Command](https://github.com/wraithyy/herdr-waypoint/blob/master/bin/wp-rename): `bin/wp-rename`
- [Remove Command](https://github.com/wraithyy/herdr-waypoint/blob/master/bin/wp-rm): `bin/wp-rm`
- [Waypoint Operations](https://github.com/wraithyy/herdr-waypoint/blob/master/bin/lib.sh): `bin/lib.sh`
- **Waypoints File**

### herdr Integration

- **herdr Server**
- **Workspace Context**
- **Workspace Create**
- [Keybinding Setup](https://github.com/wraithyy/herdr-waypoint/blob/master/bin/install-keybinds.sh): `bin/install-keybinds.sh`

### Other components

- **User**
- **fzf**
- **git status**
- **ls -la**

## Connections

- User → Add Action: save key
- herdr Server → Add Action: dispatches
- Add Action → Workspace Context: reads context
- Add Action → Waypoint Operations: adds waypoint
- User → CLI Add: runs command
- CLI Add → Waypoint Operations: adds waypoint
- Waypoint Operations → Waypoints File: reads and writes
- User → Pick Action: pick key
- herdr Server → Pick Action: dispatches
- Pick Action → Pane Picker: opens overlay
- Pane Picker → fzf Picker: uses when available
- Pane Picker → Fallback Picker: otherwise uses
- fzf Picker → Waypoints File: reads entries
- Fallback Picker → Waypoints File: reads entries
- fzf Picker → Rename Command: invokes
- fzf Picker → Remove Command: invokes
- Fallback Picker → Waypoint Operations: renames or removes
- Rename Command → Waypoint Operations: renames
- Remove Command → Waypoint Operations: removes
- fzf Picker → git status: previews status
- fzf Picker → ls -la: fallback preview
- fzf Picker → Workspace Create: opens selection
- Fallback Picker → Workspace Create: opens selection
- Workspace Create → herdr Server: creates focused workspace
- herdr Server → Keybinding Setup: runs startup hook
- Keybinding Setup → herdr Server: binds actions