# bombshell-dev/clack architecture

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

- Interactive diagram: https://gitdiagram.com/bombshell-dev/clack
- Repository: https://github.com/bombshell-dev/clack

## Overview

Clack provides interactive terminal prompts for JavaScript CLIs in two layers: ready-to-use, styled components and headless prompt primitives. The typical workflow is a CLI user interacting with a styled component, which configures a core prompt; the core handles terminal input, state and rendering, then resolves with a value or cancellation. The README also documents the headless-versus-styled distinction. The graph preserves major prompt and CLI presentation capabilities from the tree; edges are limited to relationships evidenced by the README or sampled source/index references.

Main entry points: [`packages/core/src/index.ts`](https://github.com/bombshell-dev/clack/blob/main/packages/core/src/index.ts) (Core exports), [`packages/core/src/prompts/prompt.ts`](https://github.com/bombshell-dev/clack/blob/main/packages/core/src/prompts/prompt.ts) (Prompt lifecycle), [`packages/core/src/prompts`](https://github.com/bombshell-dev/clack/tree/main/packages/core/src/prompts) (Selection primitives), [`packages/prompts/src/common.ts`](https://github.com/bombshell-dev/clack/blob/main/packages/prompts/src/common.ts) (Shared terminal styling)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_styled["Styled prompts"]
  node_prompt_api["Prompt components"]
  node_select["Select<br/>[select.ts]"]
  node_autocomplete["Autocomplete<br/>[autocomplete.ts]"]
  node_multi_select["Multi-select<br/>[multi-select.ts]"]
  node_group_multi["Grouped multi-select"]
  node_text_prompts["Text and date prompts"]
  node_prompt_extras["Prompt extras"]
end

subgraph group_presentation["CLI presentation"]
  node_task_ui["Task and progress UI"]
  node_logs_notes["Logs and notes"]
  node_shared_styling["Shared terminal styling<br/>[common.ts]"]
  node_option_layout["Option layout<br/>[limit-options.ts]"]
end

subgraph group_core["Headless core"]
  node_core_exports["Core exports<br/>[index.ts]"]
  node_core_prompt["Prompt lifecycle<br/>[prompt.ts]"]
  node_selection_primitives["Selection primitives"]
  node_input_primitives["Input primitives"]
  node_date_primitive["Date primitive<br/>[date.ts]"]
  node_group_primitive["Grouped selection primitive"]
  node_cursor_utils["Cursor utilities<br/>[cursor.ts]"]
  node_validation["Validation<br/>[validation.ts]"]
  node_schema["Standard Schema support<br/>[standard-schema.ts]"]
  node_settings["Prompt settings<br/>[settings.ts]"]
end

subgraph group_runtime["Terminal runtime"]
  node_terminal_io["Terminal input and output<br/>[index.ts]"]
end

node_cli_user(("CLI user"))

node_cli_user -->|"answers prompts"| node_prompt_api
node_prompt_api -->|"uses primitives"| node_core_exports
node_select -->|"formats output"| node_shared_styling
node_select -->|"limits options"| node_option_layout
node_select -->|"constructs prompt"| node_selection_primitives
node_autocomplete -->|"constructs prompt"| node_core_prompt
node_autocomplete -->|"formats output"| node_shared_styling
node_multi_select -->|"uses primitives"| node_selection_primitives
node_multi_select -->|"limits options"| node_option_layout
node_group_multi -->|"constructs prompt"| node_group_primitive
node_group_multi -->|"limits options"| node_option_layout
node_text_prompts -->|"wraps primitives"| node_input_primitives
node_text_prompts -->|"wraps primitive"| node_date_primitive
node_core_exports -->|"exports"| node_core_prompt
node_core_exports -->|"exports"| node_selection_primitives
node_core_exports -->|"exports"| node_input_primitives
node_core_exports -->|"exports"| node_date_primitive
node_core_exports -->|"exports"| node_group_primitive
node_core_prompt -->|"handles terminal I/O"| node_terminal_io
node_core_prompt -->|"runs validation"| node_validation
node_core_prompt -->|"reads settings"| node_settings
node_selection_primitives -->|"moves cursor"| node_cursor_utils
node_input_primitives -->|"moves cursor"| node_cursor_utils
node_date_primitive -->|"reads settings"| node_settings
node_validation -->|"validates schema"| node_schema
node_task_ui -.->|"uses styling"| node_shared_styling
node_logs_notes -.->|"uses styling"| node_shared_styling
node_prompt_extras -.->|"uses primitives"| node_core_exports

click node_prompt_api "https://github.com/bombshell-dev/clack/tree/main/packages/prompts/src"
click node_select "https://github.com/bombshell-dev/clack/blob/main/packages/prompts/src/select.ts"
click node_autocomplete "https://github.com/bombshell-dev/clack/blob/main/packages/prompts/src/autocomplete.ts"
click node_multi_select "https://github.com/bombshell-dev/clack/blob/main/packages/prompts/src/multi-select.ts"
click node_group_multi "https://github.com/bombshell-dev/clack/blob/main/packages/prompts/src/group-multi-select.ts"
click node_text_prompts "https://github.com/bombshell-dev/clack/tree/main/packages/prompts/src"
click node_prompt_extras "https://github.com/bombshell-dev/clack/tree/main/packages/prompts/src"
click node_task_ui "https://github.com/bombshell-dev/clack/tree/main/packages/prompts/src"
click node_logs_notes "https://github.com/bombshell-dev/clack/tree/main/packages/prompts/src"
click node_shared_styling "https://github.com/bombshell-dev/clack/blob/main/packages/prompts/src/common.ts"
click node_option_layout "https://github.com/bombshell-dev/clack/blob/main/packages/prompts/src/limit-options.ts"
click node_core_exports "https://github.com/bombshell-dev/clack/blob/main/packages/core/src/index.ts"
click node_core_prompt "https://github.com/bombshell-dev/clack/blob/main/packages/core/src/prompts/prompt.ts"
click node_selection_primitives "https://github.com/bombshell-dev/clack/tree/main/packages/core/src/prompts"
click node_input_primitives "https://github.com/bombshell-dev/clack/tree/main/packages/core/src/prompts"
click node_date_primitive "https://github.com/bombshell-dev/clack/blob/main/packages/core/src/prompts/date.ts"
click node_group_primitive "https://github.com/bombshell-dev/clack/blob/main/packages/core/src/prompts/group-multiselect.ts"
click node_cursor_utils "https://github.com/bombshell-dev/clack/blob/main/packages/core/src/utils/cursor.ts"
click node_validation "https://github.com/bombshell-dev/clack/blob/main/packages/core/src/utils/validation.ts"
click node_schema "https://github.com/bombshell-dev/clack/blob/main/packages/core/src/utils/standard-schema.ts"
click node_settings "https://github.com/bombshell-dev/clack/blob/main/packages/core/src/utils/settings.ts"
click node_terminal_io "https://github.com/bombshell-dev/clack/blob/main/packages/core/src/utils/index.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_prompt_api,node_select,node_autocomplete,node_multi_select,node_group_multi,node_text_prompts,node_prompt_extras,node_cli_user toneBlue
class node_task_ui,node_logs_notes,node_shared_styling,node_option_layout toneAmber
class node_core_exports,node_core_prompt,node_selection_primitives,node_input_primitives,node_date_primitive,node_group_primitive,node_cursor_utils,node_validation,node_schema,node_settings toneMint
class node_terminal_io toneRose
```

## Components

### Styled prompts

- [Prompt components](https://github.com/bombshell-dev/clack/tree/main/packages/prompts/src): `packages/prompts/src`
- [Select](https://github.com/bombshell-dev/clack/blob/main/packages/prompts/src/select.ts): `packages/prompts/src/select.ts`
- [Autocomplete](https://github.com/bombshell-dev/clack/blob/main/packages/prompts/src/autocomplete.ts): `packages/prompts/src/autocomplete.ts`
- [Multi-select](https://github.com/bombshell-dev/clack/blob/main/packages/prompts/src/multi-select.ts): `packages/prompts/src/multi-select.ts`
- [Grouped multi-select](https://github.com/bombshell-dev/clack/blob/main/packages/prompts/src/group-multi-select.ts): `packages/prompts/src/group-multi-select.ts`
- [Text and date prompts](https://github.com/bombshell-dev/clack/tree/main/packages/prompts/src): `packages/prompts/src`
- [Prompt extras](https://github.com/bombshell-dev/clack/tree/main/packages/prompts/src): `packages/prompts/src`

### CLI presentation

- [Task and progress UI](https://github.com/bombshell-dev/clack/tree/main/packages/prompts/src): `packages/prompts/src`
- [Logs and notes](https://github.com/bombshell-dev/clack/tree/main/packages/prompts/src): `packages/prompts/src`
- [Shared terminal styling](https://github.com/bombshell-dev/clack/blob/main/packages/prompts/src/common.ts): `packages/prompts/src/common.ts`
- [Option layout](https://github.com/bombshell-dev/clack/blob/main/packages/prompts/src/limit-options.ts): `packages/prompts/src/limit-options.ts`

### Headless core

- [Core exports](https://github.com/bombshell-dev/clack/blob/main/packages/core/src/index.ts): `packages/core/src/index.ts`
- [Prompt lifecycle](https://github.com/bombshell-dev/clack/blob/main/packages/core/src/prompts/prompt.ts): `packages/core/src/prompts/prompt.ts`
- [Selection primitives](https://github.com/bombshell-dev/clack/tree/main/packages/core/src/prompts): `packages/core/src/prompts`
- [Input primitives](https://github.com/bombshell-dev/clack/tree/main/packages/core/src/prompts): `packages/core/src/prompts`
- [Date primitive](https://github.com/bombshell-dev/clack/blob/main/packages/core/src/prompts/date.ts): `packages/core/src/prompts/date.ts`
- [Grouped selection primitive](https://github.com/bombshell-dev/clack/blob/main/packages/core/src/prompts/group-multiselect.ts): `packages/core/src/prompts/group-multiselect.ts`
- [Cursor utilities](https://github.com/bombshell-dev/clack/blob/main/packages/core/src/utils/cursor.ts): `packages/core/src/utils/cursor.ts`
- [Validation](https://github.com/bombshell-dev/clack/blob/main/packages/core/src/utils/validation.ts): `packages/core/src/utils/validation.ts`
- [Standard Schema support](https://github.com/bombshell-dev/clack/blob/main/packages/core/src/utils/standard-schema.ts): `packages/core/src/utils/standard-schema.ts`
- [Prompt settings](https://github.com/bombshell-dev/clack/blob/main/packages/core/src/utils/settings.ts): `packages/core/src/utils/settings.ts`

### Terminal runtime

- [Terminal input and output](https://github.com/bombshell-dev/clack/blob/main/packages/core/src/utils/index.ts): `packages/core/src/utils/index.ts`

### Other components

- **CLI user**

## Connections

- CLI user → Prompt components: answers prompts (evidence: `README.md`)
- Prompt components → Core exports: uses primitives (evidence: `README.md`)
- Select → Shared terminal styling: formats output (evidence: `packages/prompts/src/select.ts`)
- Select → Option layout: limits options (evidence: `packages/prompts/src/select.ts`)
- Select → Selection primitives: constructs prompt (evidence: `packages/prompts/src/select.ts`)
- Autocomplete → Prompt lifecycle: constructs prompt (evidence: `packages/prompts/src/autocomplete.ts`)
- Autocomplete → Shared terminal styling: formats output (evidence: `packages/prompts/src/autocomplete.ts`)
- Multi-select → Selection primitives: uses primitives (evidence: `packages/prompts/src/multi-select.ts`)
- Multi-select → Option layout: limits options (evidence: `packages/prompts/src/multi-select.ts`)
- Grouped multi-select → Grouped selection primitive: constructs prompt (evidence: `packages/prompts/src/group-multi-select.ts`)
- Grouped multi-select → Option layout: limits options (evidence: `packages/prompts/src/group-multi-select.ts`)
- Text and date prompts → Input primitives: wraps primitives (evidence: `packages/prompts/src/multi-line.ts`)
- Text and date prompts → Date primitive: wraps primitive (evidence: `packages/prompts/src/date.ts`)
- Core exports → Prompt lifecycle: exports (evidence: `packages/core/src/index.ts`)
- Core exports → Selection primitives: exports (evidence: `packages/core/src/index.ts`)
- Core exports → Input primitives: exports (evidence: `packages/core/src/index.ts`)
- Core exports → Date primitive: exports (evidence: `packages/core/src/index.ts`)
- Core exports → Grouped selection primitive: exports (evidence: `packages/core/src/index.ts`)
- Prompt lifecycle → Terminal input and output: handles terminal I/O (evidence: `packages/core/src/prompts/prompt.ts`)
- Prompt lifecycle → Validation: runs validation (evidence: `packages/core/src/prompts/prompt.ts`)
- Prompt lifecycle → Prompt settings: reads settings (evidence: `packages/core/src/prompts/prompt.ts`)
- Selection primitives → Cursor utilities: moves cursor (evidence: `packages/core/src/prompts/autocomplete.ts`)
- Input primitives → Cursor utilities: moves cursor (evidence: `packages/core/src/prompts/multi-line.ts`)
- Date primitive → Prompt settings: reads settings (evidence: `packages/core/src/prompts/date.ts`)
- Validation → Standard Schema support: validates schema (evidence: `packages/core/src/utils/validation.ts`)
- Task and progress UI → Shared terminal styling: uses styling (evidence: `packages/prompts/src/autocomplete.ts`)
- Logs and notes → Shared terminal styling: uses styling (evidence: `packages/prompts/src/autocomplete.ts`)
- Prompt extras → Core exports: uses primitives