# evilmartians/lefthook architecture

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

- Interactive diagram: https://gitdiagram.com/evilmartians/lefthook
- Repository: https://github.com/evilmartians/lefthook

## Overview

Lefthook is a Go-based Git hooks manager: developers configure hook jobs, install Git hook scripts, and Git-triggered or manually requested hooks run filtered commands and report results. Configuration supports local and remote files; installation also includes AI-assistant-specific hooks, and self-update is a separate CLI capability. The graph follows the principal CLI-to-hook workflow and key internals. Unsampled subsystem links are omitted unless documented in the README or supported by the source index.

Main entry points: [`internal/command/run.go`](https://github.com/evilmartians/lefthook/blob/master/internal/command/run.go) (Command handlers), [`internal/command/install.go`](https://github.com/evilmartians/lefthook/blob/master/internal/command/install.go) (Hook installer), [`internal/git/repo.go`](https://github.com/evilmartians/lefthook/blob/master/internal/git/repo.go) (Git repository), [`internal/run/controller/controller.go`](https://github.com/evilmartians/lefthook/blob/master/internal/run/controller/controller.go) (Job controller)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_cli["CLI and commands"]
  node_cli["Lefthook CLI<br/>[run.go]"]
  node_commands["Command handlers<br/>[run.go]"]
  node_updater["Self updater<br/>[updater.go]"]
end

subgraph group_setup["Hook setup"]
  node_installer["Hook installer<br/>[install.go]"]
  node_ai_hooks["AI hook setup<br/>[install_ai.go]"]
  node_hook_scripts["Git hook scripts<br/>[templates.go]"]
end

subgraph group_config["Configuration"]
  node_config_loader["Config loader<br/>[loader.go]"]
  node_config_model["Hook and job config<br/>[hook.go]"]
end

subgraph group_execution["Hook execution"]
  node_run_entry["Hook run entry<br/>[run.go]"]
  node_controller["Job controller<br/>[controller.go]"]
  node_filter["File filtering<br/>[filter.go]"]
  node_command_builder["Command builder<br/>[build_command.go]"]
  node_executor["Process executor<br/>[executor.go]"]
  node_results["Run results<br/>[result.go]"]
end

subgraph group_platform["Git and system"]
  node_repo["Git repository<br/>[repo.go]"]
  node_git_wrapper["Git operations<br/>[cmd.go]"]
end

node_developer(("Developer"))
node_git(("Git client"))
node_release_service(("GitHub releases"))
node_shell(("User commands"))

node_developer -->|"invokes"| node_cli
node_cli -->|"dispatches"| node_commands
node_commands -->|"loads config"| node_config_loader
node_commands -->|"uses repository"| node_repo
node_commands -->|"runs hook"| node_run_entry
node_commands -.->|"installs hooks"| node_installer
node_installer -->|"reads config"| node_config_loader
node_installer -->|"uses Git"| node_repo
node_installer -->|"renders scripts"| node_hook_scripts
node_installer -.->|"sets up AI hooks"| node_ai_hooks
node_git -->|"triggers hooks"| node_hook_scripts
node_config_loader -->|"loads remote config"| node_repo
node_commands -->|"builds jobs"| node_config_model
node_run_entry -->|"delegates"| node_controller
node_controller -->|"creates executor"| node_executor
node_command_builder -->|"uses filters"| node_filter
node_controller -->|"uses Git state"| node_repo
node_controller -->|"returns results"| node_results
node_executor -.->|"runs commands"| node_shell
node_developer -.->|"requests update"| node_updater
node_updater -->|"fetches release"| node_release_service
node_repo -->|"delegates Git"| node_git_wrapper

click node_cli "https://github.com/evilmartians/lefthook/blob/master/cmd/run.go"
click node_commands "https://github.com/evilmartians/lefthook/blob/master/internal/command/run.go"
click node_installer "https://github.com/evilmartians/lefthook/blob/master/internal/command/install.go"
click node_ai_hooks "https://github.com/evilmartians/lefthook/blob/master/internal/command/install_ai.go"
click node_hook_scripts "https://github.com/evilmartians/lefthook/blob/master/internal/templates/templates.go"
click node_config_loader "https://github.com/evilmartians/lefthook/blob/master/internal/config/loader.go"
click node_config_model "https://github.com/evilmartians/lefthook/blob/master/internal/config/hook.go"
click node_run_entry "https://github.com/evilmartians/lefthook/blob/master/internal/run/run.go"
click node_controller "https://github.com/evilmartians/lefthook/blob/master/internal/run/controller/controller.go"
click node_filter "https://github.com/evilmartians/lefthook/blob/master/internal/run/controller/filter/filter.go"
click node_command_builder "https://github.com/evilmartians/lefthook/blob/master/internal/run/controller/command/build_command.go"
click node_executor "https://github.com/evilmartians/lefthook/blob/master/internal/run/controller/exec/executor.go"
click node_results "https://github.com/evilmartians/lefthook/blob/master/internal/run/result/result.go"
click node_repo "https://github.com/evilmartians/lefthook/blob/master/internal/git/repo.go"
click node_git_wrapper "https://github.com/evilmartians/lefthook/blob/master/internal/git/wrapper/cmd.go"
click node_updater "https://github.com/evilmartians/lefthook/blob/master/internal/updater/updater.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_cli,node_commands,node_updater,node_git,node_shell toneBlue
class node_installer,node_ai_hooks,node_hook_scripts toneAmber
class node_config_loader,node_config_model toneMint
class node_run_entry,node_controller,node_filter,node_command_builder,node_executor,node_results toneRose
class node_repo,node_git_wrapper,node_developer,node_release_service toneIndigo
```

## Components

### CLI and commands

- [Lefthook CLI](https://github.com/evilmartians/lefthook/blob/master/cmd/run.go): `cmd/run.go`
- [Command handlers](https://github.com/evilmartians/lefthook/blob/master/internal/command/run.go): `internal/command/run.go`
- [Self updater](https://github.com/evilmartians/lefthook/blob/master/internal/updater/updater.go): `internal/updater/updater.go`

### Hook setup

- [Hook installer](https://github.com/evilmartians/lefthook/blob/master/internal/command/install.go): `internal/command/install.go`
- [AI hook setup](https://github.com/evilmartians/lefthook/blob/master/internal/command/install_ai.go): `internal/command/install_ai.go`
- [Git hook scripts](https://github.com/evilmartians/lefthook/blob/master/internal/templates/templates.go): `internal/templates/templates.go`

### Configuration

- [Config loader](https://github.com/evilmartians/lefthook/blob/master/internal/config/loader.go): `internal/config/loader.go`
- [Hook and job config](https://github.com/evilmartians/lefthook/blob/master/internal/config/hook.go): `internal/config/hook.go`

### Hook execution

- [Hook run entry](https://github.com/evilmartians/lefthook/blob/master/internal/run/run.go): `internal/run/run.go`
- [Job controller](https://github.com/evilmartians/lefthook/blob/master/internal/run/controller/controller.go): `internal/run/controller/controller.go`
- [File filtering](https://github.com/evilmartians/lefthook/blob/master/internal/run/controller/filter/filter.go): `internal/run/controller/filter/filter.go`
- [Command builder](https://github.com/evilmartians/lefthook/blob/master/internal/run/controller/command/build_command.go): `internal/run/controller/command/build_command.go`
- [Process executor](https://github.com/evilmartians/lefthook/blob/master/internal/run/controller/exec/executor.go): `internal/run/controller/exec/executor.go`
- [Run results](https://github.com/evilmartians/lefthook/blob/master/internal/run/result/result.go): `internal/run/result/result.go`

### Git and system

- [Git repository](https://github.com/evilmartians/lefthook/blob/master/internal/git/repo.go): `internal/git/repo.go`
- [Git operations](https://github.com/evilmartians/lefthook/blob/master/internal/git/wrapper/cmd.go): `internal/git/wrapper/cmd.go`

### Other components

- **Developer**
- **Git client**
- **GitHub releases**
- **User commands**

## Connections

- Developer → Lefthook CLI: invokes
- Lefthook CLI → Command handlers: dispatches (evidence: `cmd/run.go`)
- Command handlers → Config loader: loads config (evidence: `internal/command/run.go`)
- Command handlers → Git repository: uses repository (evidence: `internal/command/run.go`)
- Command handlers → Hook run entry: runs hook (evidence: `internal/command/run.go`)
- Command handlers → Hook installer: installs hooks
- Hook installer → Config loader: reads config (evidence: `internal/command/install.go`)
- Hook installer → Git repository: uses Git (evidence: `internal/command/install.go`)
- Hook installer → Git hook scripts: renders scripts (evidence: `internal/command/install.go`)
- Hook installer → AI hook setup: sets up AI hooks
- Git client → Git hook scripts: triggers hooks
- Config loader → Git repository: loads remote config (evidence: `internal/config/loader.go`)
- Command handlers → Hook and job config: builds jobs (evidence: `internal/command/run.go`)
- Hook run entry → Job controller: delegates (evidence: `internal/run/run.go`)
- Job controller → Process executor: creates executor (evidence: `internal/run/controller/controller.go`)
- Command builder → File filtering: uses filters (evidence: `internal/run/controller/command/build_command.go`)
- Job controller → Git repository: uses Git state (evidence: `internal/run/controller/controller.go`)
- Job controller → Run results: returns results (evidence: `internal/run/controller/controller.go`)
- Process executor → User commands: runs commands
- Developer → Self updater: requests update
- Self updater → GitHub releases: fetches release (evidence: `internal/updater/updater.go`)
- Git repository → Git operations: delegates Git (evidence: `internal/git/repo.go`)
