# agkozak/zsh-z architecture

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

- Interactive diagram: https://gitdiagram.com/agkozak/zsh-z
- Repository: https://github.com/agkozak/zsh-z

## Overview

Zsh-z is a Zsh directory-history plugin: it records visited directories, ranks them by frecency, and uses partial matches to jump to a likely destination. Users can also list or remove entries and complete directory matches. Prompt-time recording writes asynchronously; documented safeguards include file locking, bounded lock waits, and private database permissions. The repository provides no source excerpts, so the relationships below are limited to capabilities and flows explicitly described in the README.

Main entry points: [`zsh-z.plugin.zsh`](https://github.com/agkozak/zsh-z/blob/master/zsh-z.plugin.zsh) (Z command), [`_zshz`](https://github.com/agkozak/zsh-z/blob/master/_zshz) (Tab completion)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_interaction["Shell interaction"]
  node_command["Z command<br/>[zsh-z.plugin.zsh]"]
  node_completion["Tab completion"]
end

subgraph group_history["Directory history"]
  node_recording["Prompt recording<br/>[zsh-z.plugin.zsh]"]
  node_matching["Frecency matching<br/>[zsh-z.plugin.zsh]"]
  node_listing["History listing and removal<br/>[zsh-z.plugin.zsh]"]
  node_database[("Directory database")]
end

subgraph group_safety["Write safety"]
  node_locking["File locking<br/>[zsh-z.plugin.zsh]"]
end

node_user(("Shell user"))
node_zshsystem["zsh/system"]
node_destination["Target directory"]

node_user -->|"runs"| node_command
node_command -->|"matches paths"| node_matching
node_matching -->|"reads history"| node_database
node_command -->|"jumps to"| node_destination
node_user -->|"requests completion"| node_completion
node_completion -->|"completes from"| node_database
node_user -->|"lists or removes"| node_listing
node_listing -->|"updates history"| node_database
node_recording -->|"writes visits"| node_database
node_recording -->|"guards writes"| node_locking
node_locking -->|"uses locking"| node_zshsystem

click node_command "https://github.com/agkozak/zsh-z/blob/master/zsh-z.plugin.zsh"
click node_completion "https://github.com/agkozak/zsh-z/blob/master/_zshz"
click node_recording "https://github.com/agkozak/zsh-z/blob/master/zsh-z.plugin.zsh"
click node_matching "https://github.com/agkozak/zsh-z/blob/master/zsh-z.plugin.zsh"
click node_listing "https://github.com/agkozak/zsh-z/blob/master/zsh-z.plugin.zsh"
click node_locking "https://github.com/agkozak/zsh-z/blob/master/zsh-z.plugin.zsh"

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_command,node_completion,node_user toneBlue
class node_recording,node_matching,node_listing,node_database toneAmber
class node_locking toneMint
class node_zshsystem,node_destination toneIndigo
```

## Components

### Shell interaction

- [Z command](https://github.com/agkozak/zsh-z/blob/master/zsh-z.plugin.zsh): `zsh-z.plugin.zsh`
- [Tab completion](https://github.com/agkozak/zsh-z/blob/master/_zshz): `_zshz`

### Directory history

- [Prompt recording](https://github.com/agkozak/zsh-z/blob/master/zsh-z.plugin.zsh): `zsh-z.plugin.zsh`
- [Frecency matching](https://github.com/agkozak/zsh-z/blob/master/zsh-z.plugin.zsh): `zsh-z.plugin.zsh`
- [History listing and removal](https://github.com/agkozak/zsh-z/blob/master/zsh-z.plugin.zsh): `zsh-z.plugin.zsh`
- **Directory database**

### Write safety

- [File locking](https://github.com/agkozak/zsh-z/blob/master/zsh-z.plugin.zsh): `zsh-z.plugin.zsh`

### Other components

- **Shell user**
- **zsh/system**
- **Target directory**

## Connections

- Shell user → Z command: runs (evidence: `README.md`)
- Z command → Frecency matching: matches paths (evidence: `README.md`)
- Frecency matching → Directory database: reads history (evidence: `README.md`)
- Z command → Target directory: jumps to (evidence: `README.md`)
- Shell user → Tab completion: requests completion (evidence: `README.md`)
- Tab completion → Directory database: completes from (evidence: `README.md`)
- Shell user → History listing and removal: lists or removes (evidence: `README.md`)
- History listing and removal → Directory database: updates history (evidence: `README.md`)
- Prompt recording → Directory database: writes visits (evidence: `README.md`)
- Prompt recording → File locking: guards writes (evidence: `README.md`)
- File locking → zsh/system: uses locking (evidence: `README.md`)