# kunchenguid/gnhf architecture

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

- Interactive diagram: https://gitdiagram.com/kunchenguid/gnhf
- Repository: https://github.com/kunchenguid/gnhf

## Overview

gnhf is a CLI for running coding agents in an iterative, Git-backed improvement loop. The user supplies an objective; the run prepares or resumes run state, builds an iteration prompt, invokes an agent, and records successful work as commits and notes. Failures, limits, interruptions, and usage waits are managed by the orchestrator; the CLI presents live status and a final summary. The README also documents worktree and push modes. Some subsystem links reflect README-described behavior because the corresponding source was not sampled.

Main entry points: [`src/cli.ts`](https://github.com/kunchenguid/gnhf/blob/main/src/cli.ts) (CLI entry), [`src/core/orchestrator.ts`](https://github.com/kunchenguid/gnhf/blob/main/src/core/orchestrator.ts) (Iteration orchestrator), [`src/core/run.ts`](https://github.com/kunchenguid/gnhf/blob/main/src/core/run.ts) (Run state files), [`src/core/git.ts`](https://github.com/kunchenguid/gnhf/blob/main/src/core/git.ts) (Git operations)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["CLI and interaction"]
  node_cli["CLI entry<br/>[cli.ts]"]
  node_config["Config loading<br/>[config.ts]"]
  node_sleep["Sleep prevention<br/>[sleep.ts]"]
end

subgraph group_loop["Run orchestration"]
  node_orchestrator["Iteration orchestrator<br/>[orchestrator.ts]"]
  node_prompt["Iteration prompt"]
  node_summary["Exit summary<br/>[exit-summary.ts]"]
  node_telemetry["Telemetry<br/>[telemetry.ts]"]
end

subgraph group_agents["Agent execution"]
  node_agentfactory["Agent factory<br/>[factory.ts]"]
  node_adapters["Agent adapters"]
end

subgraph group_state["Git and run state"]
  node_runstate["Run state files<br/>[run.ts]"]
  node_gitops["Git operations<br/>[git.ts]"]
end

subgraph group_display["Terminal experience"]
  node_renderer["Live terminal renderer<br/>[renderer.ts]"]
  node_renderdiff["Terminal diff rendering<br/>[renderer-diff.ts]"]
end

node_user(("User"))
node_agentclis["Coding agent CLIs"]
node_repository[("Git repository")]

node_user -->|"starts run"| node_cli
node_cli -->|"loads options"| node_config
node_cli -->|"creates or resumes"| node_runstate
node_cli -->|"starts loop"| node_orchestrator
node_cli -->|"displays status"| node_renderer
node_cli -.->|"optionally prevents"| node_sleep
node_orchestrator -->|"builds prompt"| node_prompt
node_orchestrator -->|"creates agent"| node_agentfactory
node_agentfactory -->|"selects adapter"| node_adapters
node_adapters -->|"invokes agent"| node_agentclis
node_orchestrator -->|"commits or resets"| node_gitops
node_gitops -->|"updates branch"| node_repository
node_orchestrator -->|"records iterations"| node_runstate
node_runstate -->|"stores run files"| node_repository
node_cli -->|"checks branch diff"| node_gitops
node_cli -->|"builds final summary"| node_summary
node_orchestrator -->|"records usage"| node_telemetry
node_renderer -->|"renders cells"| node_renderdiff
node_orchestrator -->|"emits state"| node_renderer

click node_cli "https://github.com/kunchenguid/gnhf/blob/main/src/cli.ts"
click node_config "https://github.com/kunchenguid/gnhf/blob/main/src/core/config.ts"
click node_orchestrator "https://github.com/kunchenguid/gnhf/blob/main/src/core/orchestrator.ts"
click node_prompt "https://github.com/kunchenguid/gnhf/blob/main/src/templates/iteration-prompt.ts"
click node_agentfactory "https://github.com/kunchenguid/gnhf/blob/main/src/core/agents/factory.ts"
click node_adapters "https://github.com/kunchenguid/gnhf/tree/main/src/core/agents"
click node_runstate "https://github.com/kunchenguid/gnhf/blob/main/src/core/run.ts"
click node_gitops "https://github.com/kunchenguid/gnhf/blob/main/src/core/git.ts"
click node_summary "https://github.com/kunchenguid/gnhf/blob/main/src/core/exit-summary.ts"
click node_renderer "https://github.com/kunchenguid/gnhf/blob/main/src/renderer.ts"
click node_renderdiff "https://github.com/kunchenguid/gnhf/blob/main/src/renderer-diff.ts"
click node_sleep "https://github.com/kunchenguid/gnhf/blob/main/src/core/sleep.ts"
click node_telemetry "https://github.com/kunchenguid/gnhf/blob/main/src/core/telemetry.ts"

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_config,node_sleep,node_user toneBlue
class node_orchestrator,node_prompt,node_summary,node_telemetry,node_repository toneAmber
class node_agentfactory,node_adapters toneMint
class node_runstate,node_gitops toneRose
class node_renderer,node_renderdiff,node_agentclis toneIndigo
```

## Components

### CLI and interaction

- [CLI entry](https://github.com/kunchenguid/gnhf/blob/main/src/cli.ts): `src/cli.ts`
- [Config loading](https://github.com/kunchenguid/gnhf/blob/main/src/core/config.ts): `src/core/config.ts`
- [Sleep prevention](https://github.com/kunchenguid/gnhf/blob/main/src/core/sleep.ts): `src/core/sleep.ts`

### Run orchestration

- [Iteration orchestrator](https://github.com/kunchenguid/gnhf/blob/main/src/core/orchestrator.ts): `src/core/orchestrator.ts`
- [Iteration prompt](https://github.com/kunchenguid/gnhf/blob/main/src/templates/iteration-prompt.ts): `src/templates/iteration-prompt.ts`
- [Exit summary](https://github.com/kunchenguid/gnhf/blob/main/src/core/exit-summary.ts): `src/core/exit-summary.ts`
- [Telemetry](https://github.com/kunchenguid/gnhf/blob/main/src/core/telemetry.ts): `src/core/telemetry.ts`

### Agent execution

- [Agent factory](https://github.com/kunchenguid/gnhf/blob/main/src/core/agents/factory.ts): `src/core/agents/factory.ts`
- [Agent adapters](https://github.com/kunchenguid/gnhf/tree/main/src/core/agents): `src/core/agents`

### Git and run state

- [Run state files](https://github.com/kunchenguid/gnhf/blob/main/src/core/run.ts): `src/core/run.ts`
- [Git operations](https://github.com/kunchenguid/gnhf/blob/main/src/core/git.ts): `src/core/git.ts`

### Terminal experience

- [Live terminal renderer](https://github.com/kunchenguid/gnhf/blob/main/src/renderer.ts): `src/renderer.ts`
- [Terminal diff rendering](https://github.com/kunchenguid/gnhf/blob/main/src/renderer-diff.ts): `src/renderer-diff.ts`

### Other components

- **User**
- **Coding agent CLIs**
- **Git repository**

## Connections

- User → CLI entry: starts run
- CLI entry → Config loading: loads options
- CLI entry → Run state files: creates or resumes
- CLI entry → Iteration orchestrator: starts loop
- CLI entry → Live terminal renderer: displays status
- CLI entry → Sleep prevention: optionally prevents
- Iteration orchestrator → Iteration prompt: builds prompt
- Iteration orchestrator → Agent factory: creates agent
- Agent factory → Agent adapters: selects adapter
- Agent adapters → Coding agent CLIs: invokes agent
- Iteration orchestrator → Git operations: commits or resets
- Git operations → Git repository: updates branch
- Iteration orchestrator → Run state files: records iterations
- Run state files → Git repository: stores run files
- CLI entry → Git operations: checks branch diff
- CLI entry → Exit summary: builds final summary
- Iteration orchestrator → Telemetry: records usage
- Live terminal renderer → Terminal diff rendering: renders cells
- Iteration orchestrator → Live terminal renderer: emits state