# joshmedeski/sesh architecture

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

- Interactive diagram: https://gitdiagram.com/joshmedeski/sesh
- Repository: https://github.com/joshmedeski/sesh

## Overview

Sesh is a CLI for discovering, creating, and switching tmux sessions. Its main user path is command invocation, session discovery, optional interactive selection, then connection to a tmux session; README-described workflows also include project configuration, previews, and worktree sessions. The graph includes those documented capabilities, while some links remain unverified because their command wiring or implementation was not sampled.

Main entry points: [`connector/session.go`](https://github.com/joshmedeski/sesh/blob/main/connector/session.go) (Connection Resolution), [`seshcli`](https://github.com/joshmedeski/sesh/tree/main/seshcli) (CLI Commands), [`worktree/worktree.go`](https://github.com/joshmedeski/sesh/blob/main/worktree/worktree.go) (Worktree Manager), [`lister/list.go`](https://github.com/joshmedeski/sesh/blob/main/lister/list.go) (Session Listing)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and Interaction"]
  node_entry["CLI Entry<br/>[main.go]"]
  node_commands["CLI Commands"]
  node_picker["Interactive Picker<br/>[tui.go]"]
end

subgraph group_sessions["Session Discovery"]
  node_config["Project Configuration<br/>[configurator.go]"]
  node_listing["Session Listing<br/>[list.go]"]
  node_cache["Listing Cache<br/>[caching_lister.go]"]
  node_format["Session Formatting<br/>[formatter.go]"]
  node_preview["Session Preview<br/>[previewer.go]"]
end

subgraph group_connect["Session Connection"]
  node_connect["Connection Resolution<br/>[session.go]"]
  node_startup["Session Startup<br/>[startup.go]"]
end

subgraph group_worktrees["Worktree Workflows"]
  node_worktree_cli["Worktree Commands<br/>[worktree.go]"]
  node_worktree["Worktree Manager<br/>[worktree.go]"]
end

subgraph group_runtime["Runtime Services"]
  node_tmux["tmux Operations<br/>[client.go]"]
  node_zoxide["zoxide Search<br/>[query.go]"]
  node_shell["Shell Execution<br/>[shell.go]"]
  node_git["Git Operations<br/>[git.go]"]
  node_github["GitHub Integration<br/>[github.go]"]
  node_browser["Browser Context<br/>[browser.go]"]
end

node_user(("User"))
node_tmux_service{{"tmux Server"}}
node_zoxide_service[("zoxide Database")]

node_user -->|"invokes"| node_entry
node_entry -->|"executes"| node_commands
node_commands -.->|"opens"| node_picker
node_commands -.->|"requests sessions"| node_listing
node_listing -->|"delegates listing"| node_cache
node_cache -->|"refreshes"| node_listing
node_listing -.->|"formats results"| node_format
node_picker -.->|"selects session"| node_connect
node_commands -.->|"loads settings"| node_config
node_commands -.->|"requests preview"| node_preview
node_connect -->|"resolves session"| node_listing
node_connect -->|"adds path"| node_zoxide
node_connect -->|"starts session setup"| node_startup
node_connect -->|"creates or focuses"| node_tmux
node_startup -->|"creates windows"| node_tmux
node_worktree_cli -->|"dispatches"| node_worktree
node_worktree -->|"resolves browser tab"| node_browser
node_worktree -->|"fetches repository"| node_git
node_worktree -->|"looks up pull request"| node_github
node_worktree -->|"connects worktree"| node_connect
node_tmux -.->|"queries clients"| node_tmux_service
node_zoxide -.->|"runs query"| node_shell
node_zoxide -.->|"searches paths"| node_zoxide_service

click node_entry "https://github.com/joshmedeski/sesh/blob/main/main.go"
click node_commands "https://github.com/joshmedeski/sesh/tree/main/seshcli"
click node_picker "https://github.com/joshmedeski/sesh/blob/main/picker/tui.go"
click node_config "https://github.com/joshmedeski/sesh/blob/main/configurator/configurator.go"
click node_listing "https://github.com/joshmedeski/sesh/blob/main/lister/list.go"
click node_cache "https://github.com/joshmedeski/sesh/blob/main/lister/caching_lister.go"
click node_format "https://github.com/joshmedeski/sesh/blob/main/formatter/formatter.go"
click node_preview "https://github.com/joshmedeski/sesh/blob/main/previewer/previewer.go"
click node_connect "https://github.com/joshmedeski/sesh/blob/main/connector/session.go"
click node_startup "https://github.com/joshmedeski/sesh/blob/main/startup/startup.go"
click node_tmux "https://github.com/joshmedeski/sesh/blob/main/tmux/client.go"
click node_zoxide "https://github.com/joshmedeski/sesh/blob/main/zoxide/query.go"
click node_shell "https://github.com/joshmedeski/sesh/blob/main/shell/shell.go"
click node_worktree_cli "https://github.com/joshmedeski/sesh/blob/main/seshcli/worktree.go"
click node_worktree "https://github.com/joshmedeski/sesh/blob/main/worktree/worktree.go"
click node_git "https://github.com/joshmedeski/sesh/blob/main/git/git.go"
click node_github "https://github.com/joshmedeski/sesh/blob/main/github/github.go"
click node_browser "https://github.com/joshmedeski/sesh/blob/main/browser/browser.go"

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_entry,node_commands,node_picker,node_user toneBlue
class node_config,node_listing,node_cache,node_format,node_preview,node_zoxide_service toneAmber
class node_connect,node_startup,node_tmux_service toneMint
class node_worktree_cli,node_worktree toneRose
class node_tmux,node_zoxide,node_shell,node_git,node_github,node_browser toneIndigo
```

## Components

### CLI and Interaction

- [CLI Entry](https://github.com/joshmedeski/sesh/blob/main/main.go): `main.go`
- [CLI Commands](https://github.com/joshmedeski/sesh/tree/main/seshcli): `seshcli`
- [Interactive Picker](https://github.com/joshmedeski/sesh/blob/main/picker/tui.go): `picker/tui.go`

### Session Discovery

- [Project Configuration](https://github.com/joshmedeski/sesh/blob/main/configurator/configurator.go): `configurator/configurator.go`
- [Session Listing](https://github.com/joshmedeski/sesh/blob/main/lister/list.go): `lister/list.go`
- [Listing Cache](https://github.com/joshmedeski/sesh/blob/main/lister/caching_lister.go): `lister/caching_lister.go`
- [Session Formatting](https://github.com/joshmedeski/sesh/blob/main/formatter/formatter.go): `formatter/formatter.go`
- [Session Preview](https://github.com/joshmedeski/sesh/blob/main/previewer/previewer.go): `previewer/previewer.go`

### Session Connection

- [Connection Resolution](https://github.com/joshmedeski/sesh/blob/main/connector/session.go): `connector/session.go`
- [Session Startup](https://github.com/joshmedeski/sesh/blob/main/startup/startup.go): `startup/startup.go`

### Worktree Workflows

- [Worktree Commands](https://github.com/joshmedeski/sesh/blob/main/seshcli/worktree.go): `seshcli/worktree.go`
- [Worktree Manager](https://github.com/joshmedeski/sesh/blob/main/worktree/worktree.go): `worktree/worktree.go`

### Runtime Services

- [tmux Operations](https://github.com/joshmedeski/sesh/blob/main/tmux/client.go): `tmux/client.go`
- [zoxide Search](https://github.com/joshmedeski/sesh/blob/main/zoxide/query.go): `zoxide/query.go`
- [Shell Execution](https://github.com/joshmedeski/sesh/blob/main/shell/shell.go): `shell/shell.go`
- [Git Operations](https://github.com/joshmedeski/sesh/blob/main/git/git.go): `git/git.go`
- [GitHub Integration](https://github.com/joshmedeski/sesh/blob/main/github/github.go): `github/github.go`
- [Browser Context](https://github.com/joshmedeski/sesh/blob/main/browser/browser.go): `browser/browser.go`

### Other components

- **User**
- **tmux Server**
- **zoxide Database**

## Connections

- User → CLI Entry: invokes (evidence: `README.md`)
- CLI Entry → CLI Commands: executes (evidence: `main.go`)
- CLI Commands → Interactive Picker: opens
- CLI Commands → Session Listing: requests sessions
- Session Listing → Listing Cache: delegates listing (evidence: `lister/caching_lister.go`)
- Listing Cache → Session Listing: refreshes (evidence: `lister/caching_lister.go`)
- Session Listing → Session Formatting: formats results
- Interactive Picker → Connection Resolution: selects session
- CLI Commands → Project Configuration: loads settings
- CLI Commands → Session Preview: requests preview
- Connection Resolution → Session Listing: resolves session (evidence: `connector/session.go`)
- Connection Resolution → zoxide Search: adds path (evidence: `connector/session.go`)
- Connection Resolution → Session Startup: starts session setup (evidence: `connector/session.go`)
- Connection Resolution → tmux Operations: creates or focuses (evidence: `connector/session.go`)
- Session Startup → tmux Operations: creates windows (evidence: `startup/startup.go`)
- Worktree Commands → Worktree Manager: dispatches (evidence: `seshcli/worktree.go`)
- Worktree Manager → Browser Context: resolves browser tab (evidence: `worktree/worktree.go`)
- Worktree Manager → Git Operations: fetches repository (evidence: `worktree/worktree.go`)
- Worktree Manager → GitHub Integration: looks up pull request (evidence: `worktree/worktree.go`)
- Worktree Manager → Connection Resolution: connects worktree (evidence: `worktree/worktree.go`)
- tmux Operations → tmux Server: queries clients
- zoxide Search → Shell Execution: runs query
- zoxide Search → zoxide Database: searches paths
