# google/zx architecture

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

- Interactive diagram: https://gitdiagram.com/google/zx
- Repository: https://github.com/google/zx

## Overview

zx is a JavaScript/TypeScript shell-scripting runtime: users write scripts with a tagged command API, and can run them through a CLI that accepts local, stdin, or remote scripts. The main runtime wraps process execution, streams, and shell command construction; the package also provides convenience helpers, CLI dependency installation, Markdown scripts, and a REPL. The graph reflects the sampled calls and imports plus README capabilities; unsampled implementation details are represented only where their paths are supported.

Main entry points: [`src/core.ts`](https://github.com/google/zx/blob/main/src/core.ts) (Process promises), [`src/cli.ts`](https://github.com/google/zx/blob/main/src/cli.ts) (CLI runner), [`src/goods.ts`](https://github.com/google/zx/blob/main/src/goods.ts) (Script utilities), [`src/index.ts`](https://github.com/google/zx/blob/main/src/index.ts) (Public API)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["User entrypoints"]
  node_cli["CLI runner<br/>[cli.ts]"]
  node_scriptinput["Script input"]
  node_markdown["Markdown transform<br/>[md.ts]"]
  node_repl["Interactive REPL<br/>[repl.ts]"]
  node_deps["Dependency installer<br/>[deps.ts]"]
end

subgraph group_runtime["Process runtime"]
  node_api["Public API<br/>[index.ts]"]
  node_process["Process promises<br/>[core.ts]"]
  node_spawn["Spawn adapter<br/>[vendor-core.ts]"]
  node_logger["Logging<br/>[log.ts]"]
  node_errors["Process errors<br/>[error.ts]"]
end

subgraph group_helpers["Script helpers"]
  node_goods["Script utilities<br/>[goods.ts]"]
  node_markdownapi["Markdown utilities<br/>[md.ts]"]
  node_vendor["Optional dependencies<br/>[vendor-extra.ts]"]
end

subgraph group_internals["Runtime internals"]
  node_vendorcore["Platform adapters<br/>[vendor-core.ts]"]
  node_util["Shared utilities<br/>[util.ts]"]
  node_bus["Override registry<br/>[internals.ts]"]
  node_versions["Version metadata<br/>[versions.ts]"]
end

node_user(("Script author"))
node_shell["Shell process"]

node_user -->|"runs scripts"| node_cli
node_user -->|"writes commands"| node_api
node_scriptinput -->|"supplies input"| node_cli
node_cli -->|"transforms Markdown"| node_markdown
node_cli -->|"starts REPL"| node_repl
node_cli -->|"installs dependencies"| node_deps
node_cli -->|"imports runtime API"| node_api
node_api -->|"exports process API"| node_process
node_process -->|"builds commands"| node_spawn
node_spawn -->|"executes commands"| node_shell
node_process -->|"emits log events"| node_logger
node_process -->|"raises failures"| node_errors
node_process -->|"uses utilities"| node_util
node_goods -->|"uses command API"| node_process
node_goods -->|"uses helpers"| node_util
node_goods -->|"uses fetch and parsing"| node_vendor
node_markdownapi -->|"uses helpers"| node_util
node_deps -->|"resolves dependencies"| node_vendor
node_deps -->|"runs installer command"| node_process
node_vendor -->|"registers overrides"| node_bus
node_vendorcore -->|"registers adapters"| node_bus
node_logger -->|"uses terminal formatting"| node_vendorcore
node_process -->|"uses process adapters"| node_vendorcore
node_api -->|"exports helpers"| node_goods
node_api -->|"exports integrations"| node_vendor
node_goods -->|"exports versions"| node_versions

click node_cli "https://github.com/google/zx/blob/main/src/cli.ts"
click node_markdown "https://github.com/google/zx/blob/main/src/md.ts"
click node_repl "https://github.com/google/zx/blob/main/src/repl.ts"
click node_deps "https://github.com/google/zx/blob/main/src/deps.ts"
click node_api "https://github.com/google/zx/blob/main/src/index.ts"
click node_process "https://github.com/google/zx/blob/main/src/core.ts"
click node_spawn "https://github.com/google/zx/blob/main/src/vendor-core.ts"
click node_logger "https://github.com/google/zx/blob/main/src/log.ts"
click node_errors "https://github.com/google/zx/blob/main/src/error.ts"
click node_goods "https://github.com/google/zx/blob/main/src/goods.ts"
click node_markdownapi "https://github.com/google/zx/blob/main/src/md.ts"
click node_vendor "https://github.com/google/zx/blob/main/src/vendor-extra.ts"
click node_vendorcore "https://github.com/google/zx/blob/main/src/vendor-core.ts"
click node_util "https://github.com/google/zx/blob/main/src/util.ts"
click node_bus "https://github.com/google/zx/blob/main/src/internals.ts"
click node_versions "https://github.com/google/zx/blob/main/src/versions.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_scriptinput,node_markdown,node_repl,node_deps toneBlue
class node_api,node_process,node_spawn,node_logger,node_errors toneAmber
class node_goods,node_markdownapi,node_vendor toneMint
class node_vendorcore,node_util,node_bus,node_versions toneRose
class node_user,node_shell toneIndigo
```

## Components

### User entrypoints

- [CLI runner](https://github.com/google/zx/blob/main/src/cli.ts): `src/cli.ts`
- **Script input**
- [Markdown transform](https://github.com/google/zx/blob/main/src/md.ts): `src/md.ts`
- [Interactive REPL](https://github.com/google/zx/blob/main/src/repl.ts): `src/repl.ts`
- [Dependency installer](https://github.com/google/zx/blob/main/src/deps.ts): `src/deps.ts`

### Process runtime

- [Public API](https://github.com/google/zx/blob/main/src/index.ts): `src/index.ts`
- [Process promises](https://github.com/google/zx/blob/main/src/core.ts): `src/core.ts`
- [Spawn adapter](https://github.com/google/zx/blob/main/src/vendor-core.ts): `src/vendor-core.ts`
- [Logging](https://github.com/google/zx/blob/main/src/log.ts): `src/log.ts`
- [Process errors](https://github.com/google/zx/blob/main/src/error.ts): `src/error.ts`

### Script helpers

- [Script utilities](https://github.com/google/zx/blob/main/src/goods.ts): `src/goods.ts`
- [Markdown utilities](https://github.com/google/zx/blob/main/src/md.ts): `src/md.ts`
- [Optional dependencies](https://github.com/google/zx/blob/main/src/vendor-extra.ts): `src/vendor-extra.ts`

### Runtime internals

- [Platform adapters](https://github.com/google/zx/blob/main/src/vendor-core.ts): `src/vendor-core.ts`
- [Shared utilities](https://github.com/google/zx/blob/main/src/util.ts): `src/util.ts`
- [Override registry](https://github.com/google/zx/blob/main/src/internals.ts): `src/internals.ts`
- [Version metadata](https://github.com/google/zx/blob/main/src/versions.ts): `src/versions.ts`

### Other components

- **Script author**
- **Shell process**

## Connections

- Script author → CLI runner: runs scripts (evidence: `README.md`)
- Script author → Public API: writes commands (evidence: `README.md`)
- Script input → CLI runner: supplies input (evidence: `src/cli.ts`)
- CLI runner → Markdown transform: transforms Markdown (evidence: `src/cli.ts`)
- CLI runner → Interactive REPL: starts REPL (evidence: `src/cli.ts`)
- CLI runner → Dependency installer: installs dependencies (evidence: `src/cli.ts`)
- CLI runner → Public API: imports runtime API (evidence: `src/cli.ts`)
- Public API → Process promises: exports process API (evidence: `src/index.ts`)
- Process promises → Spawn adapter: builds commands (evidence: `src/core.ts`)
- Spawn adapter → Shell process: executes commands (evidence: `README.md`)
- Process promises → Logging: emits log events (evidence: `src/core.ts`)
- Process promises → Process errors: raises failures (evidence: `src/core.ts`)
- Process promises → Shared utilities: uses utilities (evidence: `src/core.ts`)
- Script utilities → Process promises: uses command API (evidence: `src/goods.ts`)
- Script utilities → Shared utilities: uses helpers (evidence: `src/goods.ts`)
- Script utilities → Optional dependencies: uses fetch and parsing (evidence: `src/goods.ts`)
- Markdown utilities → Shared utilities: uses helpers (evidence: `src/md.ts`)
- Dependency installer → Optional dependencies: resolves dependencies (evidence: `src/deps.ts`)
- Dependency installer → Process promises: runs installer command (evidence: `src/deps.ts`)
- Optional dependencies → Override registry: registers overrides (evidence: `src/vendor-extra.ts`)
- Platform adapters → Override registry: registers adapters (evidence: `src/vendor-core.ts`)
- Logging → Platform adapters: uses terminal formatting (evidence: `src/log.ts`)
- Process promises → Platform adapters: uses process adapters (evidence: `src/core.ts`)
- Public API → Script utilities: exports helpers (evidence: `src/index.ts`)
- Public API → Optional dependencies: exports integrations (evidence: `src/index.ts`)
- Script utilities → Version metadata: exports versions (evidence: `src/goods.ts`)
