# noumena-network/code architecture

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

- Interactive diagram: https://gitdiagram.com/noumena-network/code
- Repository: https://github.com/noumena-network/code

## Overview

1. **What this repo is**
   - Noumena Code is a terminal-first AI coding assistant.
   - The core app is TypeScript/React running in Bun, with an Ink-based terminal UI and Rust N-API modules for native integrations and performance-sensitive paths.
   - The distributed artifact is a single-file CLI binary produced by the build pipeline.

2. **Main runtime entrypoints**
   - `src/entrypoints/cli.tsx`, `src/main.tsx`, and `src/ink.ts` are the main application entry surfaces.
   - `src/commands/*` implements the slash-command layer and command-specific screens/flows.
   - Build and packaging are handled separately in `build/`, which emits the user-facing binary and packaging metadata.

3. **Terminal UI and render layer**
   - The interactive surface lives in `src/screens/REPL.tsx` and the many components under `src/components/`.
   - `src/ink/` is a custom terminal rendering/runtime layer, not just a UI library wrapper; it owns layout, terminal input, alternate screen handling, selection, screen diffing, and replay/testing contracts.
   - `src/state/` holds application state, while `src/context/` and `src/hooks/` provide the reactive wiring between session state and UI.

4. **Core session orchestration**
   - `src/session/` is the turn-by-turn orchestration layer.
   - It coordinates prompt submission, turn preparation, cancellation, replay/resume, bookkeeping, and post-processing for both interactive REPL usage and background/local query flows.
   - This is the main boundary between “user intent in the terminal” and “model/tool execution.”

5. **Tool execution subsystem**
   - `src/tools/` contains the tool implementations the assistant can invoke: shell/bash, file read/write/edit, grep/glob, web fetch/search, REPLs, MCP, tasks, agents, workflows, notifications, and more.
   - `src/services/tools/` handles orchestration, streaming execution, hooks, and tool lifecycle rather than the tool-specific UI.
   - Tool results are rendered back into the transcript via specialized message and component types in `src/components/messages/` and `src/components/permissions/`.

6. **Permission and safety boundary**
   - `src/auth/`, `src/utils/permissions/`, and `src/components/permissions/` define the policy layer that gates risky actions.
   - Permission handling covers shell/file/network actions, plan mode, sandboxing, trusted device/work secret flows, and capability checks.
   - This is a major architectural boundary: user approval or policy automation must succeed before many tools can execute.

7. **Model/API boundary**
   - `src/services/api/` and `src/utils/model/` are the outbound model/provider layer.
   - The repo supports Noumena-managed auth, OAuth login, API keys, BYOK workflows, rate limits, usage tracking, and OpenAI-compatible/Anthropic-style provider interactions.
   - This layer is where transcript content becomes model requests and where responses, receipts, retries, and quota/rate-limit behavior are handled.

8. **Remote, bridge, and distributed execution**
   - `src/remote/`, `src/bridge/`, `src/server/`, and `src/utils/swarm/` support remote-control and multi-session scenarios.
   - These modules manage remote session transport, bridge messaging, session discovery/history, peer/teammate coordination, and in-process vs tmux/pty-backed execution modes.
   - The architecture supports both local interactive control and remotely hosted or delegated execution paths.

9. **Extensibility surfaces**
   - `src/commands/`, `src/plugins/`, `src/skills/`, and `src/services/mcp/` are the extensibility layers.
   - Commands expose user-facing workflows; plugins add commands/tools/hooks/output styles; skills bundle reusable behaviors and prompts; MCP connects to external tool servers.
   - For an architecture diagram, treat these as pluggable capability layers loaded into the main session/tool pipeline.

10. **Memory, transcript, and background services**
   - `src/memdir/`, `src/services/sessionTranscript/`, `src/services/compact/`, `src/services/extractMemories/`, and `src/services/autoDream/` handle persistence and long-running assistant behavior.
   - These modules manage session memory extraction, compaction/collapse, transcript storage, and background summarization-style workflows.
   - They feed the session engine rather than replacing it.

11. **Native and non-TS accelerators**
   - `native/markdown-renderer-napi` and `native/openai-compat-ws-v2-napi` are Rust-backed N-API modules.
   - `rust/py_repl_host` is a Rust component used by the REPL tooling.
   - `src/shims/` and `src/native-ts/` provide TypeScript-facing adapters around native assets and platform-specific binaries.

12. **Operational concerns**
   - Telemetry/analytics live under `src/services/telemetry/` and `src/services/analytics/`.
   - Configuration, settings sync, migrations, session storage, and startup checks are spread across `src/utils/settings/`, `src/migrations/`, and related utilities.
   - This repo is built and tested with Bun plus Rust/Cargo; many tests are contract-style and cover PTY/tmux, native packaging, and terminal rendering behavior.

13. **Useful architecture diagram framing**
   - A good diagram would show: terminal input/UI → session orchestration → model/API calls and tool execution → permission gates → transcript/state persistence → rendered response back to UI.
   - Around that core, show extension points for commands/plugins/skills/MCP and side channels for remote sessions, background tasks, telemetry, and native accelerators.

Main entry points: [`src/session`](https://github.com/noumena-network/code/tree/main/src/session) (Session engine), [`src/tools`](https://github.com/noumena-network/code/tree/main/src/tools) (Tool set), [`src/utils/permissions`](https://github.com/noumena-network/code/tree/main/src/utils/permissions) (Permissions), [`src/screens/REPL.tsx`](https://github.com/noumena-network/code/blob/main/src/screens/REPL.tsx) (REPL screen)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_grp_ui["Terminal UI"]
  node_n_cli["CLI entry<br/>entrypoint<br/>[cli.tsx]"]
  node_n_main["Main shell<br/>app bootstrap<br/>[main.tsx]"]
  node_n_inkrt["Ink runtime<br/>terminal runtime<br/>[ink.ts]"]
  node_n_repl["REPL screen<br/>interactive screen<br/>[REPL.tsx]"]
  node_n_state[("App state<br/>state store<br/>[AppState.tsx]")]
  node_n_contexts(("Reactive wiring<br/>contexts/hooks<br/>[context.ts]"))
end

subgraph group_grp_session["Session Core"]
  node_n_session{{"Session engine<br/>orchestrator"}}
end

subgraph group_grp_exec["Execution"]
  node_n_toolsvc{{"Tool service<br/>tool orchestration"}}
  node_n_tools["Tool set<br/>tool implementations"]
  node_n_perm{{"Permissions<br/>policy boundary"}}
  node_n_api[("Model/API<br/>provider boundary")]
  node_n_mem[("Memory & transcript<br/>persistence")]
end

subgraph group_grp_ext["Extensibility"]
  node_n_commands["Slash commands<br/>command layer<br/>[commands.ts]"]
  node_n_plugins["Plugins<br/>extensibility"]
  node_n_skills["Skills<br/>capability bundles"]
  node_n_mcp["MCP<br/>tool server bridge"]
end

subgraph group_grp_remote["Remote/Swarm"]
  node_n_remote["Remote control<br/>remote runtime"]
  node_n_bridge["Bridge layer<br/>messaging bridge"]
  node_n_swarm["Swarm runtime<br/>multi-session runtime"]
end

subgraph group_grp_native["Native"]
  node_n_native["Native addons<br/>rust napi"]
  node_n_shims["Native shims<br/>adapter layer"]
end

subgraph group_grp_build["Build"]
  node_n_build["Build pipeline<br/>packaging"]
end

node_n_cli -->|"boots"| node_n_main
node_n_main -->|"mounts"| node_n_inkrt
node_n_inkrt -->|"renders"| node_n_repl
node_n_repl -->|"reads/writes"| node_n_state
node_n_contexts -->|"binds"| node_n_state
node_n_commands -->|"dispatches"| node_n_session
node_n_repl -->|"submits turns"| node_n_session
node_n_session -->|"orchestrates"| node_n_toolsvc
node_n_toolsvc -->|"runs"| node_n_tools
node_n_toolsvc -->|"checks"| node_n_perm
node_n_tools -->|"requests approval"| node_n_perm
node_n_session -->|"calls model"| node_n_api
node_n_api -->|"records"| node_n_mem
node_n_mem -->|"feeds context"| node_n_session
node_n_remote -->|"transports"| node_n_bridge
node_n_bridge -->|"routes"| node_n_session
node_n_swarm -->|"coordinates"| node_n_session
node_n_swarm -->|"syncs policy"| node_n_perm
node_n_plugins -->|"extends"| node_n_commands
node_n_plugins -->|"extends"| node_n_tools
node_n_skills -->|"influences"| node_n_session
node_n_mcp -->|"exposes"| node_n_tools
node_n_mcp -->|"elicits"| node_n_perm
node_n_native -->|"adapts"| node_n_shims
node_n_shims -->|"accelerates"| node_n_inkrt
node_n_build -->|"packages"| node_n_native
node_n_build -->|"emits"| node_n_cli

click node_n_cli "https://github.com/noumena-network/code/blob/main/src/entrypoints/cli.tsx"
click node_n_main "https://github.com/noumena-network/code/blob/main/src/main.tsx"
click node_n_inkrt "https://github.com/noumena-network/code/blob/main/src/ink.ts"
click node_n_repl "https://github.com/noumena-network/code/blob/main/src/screens/REPL.tsx"
click node_n_state "https://github.com/noumena-network/code/blob/main/src/state/AppState.tsx"
click node_n_contexts "https://github.com/noumena-network/code/blob/main/src/context.ts"
click node_n_commands "https://github.com/noumena-network/code/blob/main/src/commands.ts"
click node_n_session "https://github.com/noumena-network/code/tree/main/src/session"
click node_n_toolsvc "https://github.com/noumena-network/code/tree/main/src/services/tools"
click node_n_tools "https://github.com/noumena-network/code/tree/main/src/tools"
click node_n_perm "https://github.com/noumena-network/code/tree/main/src/utils/permissions"
click node_n_api "https://github.com/noumena-network/code/tree/main/src/services/api"
click node_n_mem "https://github.com/noumena-network/code/tree/main/src/services/sessionTranscript"
click node_n_remote "https://github.com/noumena-network/code/tree/main/src/remote"
click node_n_bridge "https://github.com/noumena-network/code/tree/main/src/bridge"
click node_n_swarm "https://github.com/noumena-network/code/tree/main/src/utils/swarm"
click node_n_plugins "https://github.com/noumena-network/code/tree/main/src/plugins"
click node_n_skills "https://github.com/noumena-network/code/tree/main/src/skills"
click node_n_mcp "https://github.com/noumena-network/code/tree/main/src/services/mcp"
click node_n_native "https://github.com/noumena-network/code/tree/main/native"
click node_n_shims "https://github.com/noumena-network/code/tree/main/src/shims"
click node_n_build "https://github.com/noumena-network/code/tree/main/build"

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_n_cli,node_n_main,node_n_inkrt,node_n_repl,node_n_state,node_n_contexts,node_n_build toneBlue
class node_n_session toneAmber
class node_n_toolsvc,node_n_tools,node_n_perm,node_n_api,node_n_mem toneMint
class node_n_commands,node_n_plugins,node_n_skills,node_n_mcp toneRose
class node_n_remote,node_n_bridge,node_n_swarm toneIndigo
class node_n_native,node_n_shims toneTeal
```

## Components

### Terminal UI

Ink-based terminal surface, screens, components, state wiring, and input handling.

- [CLI entry](https://github.com/noumena-network/code/blob/main/src/entrypoints/cli.tsx): entrypoint · Main terminal app entry surface and startup wiring. · `src/entrypoints/cli.tsx`
- [Main shell](https://github.com/noumena-network/code/blob/main/src/main.tsx): app bootstrap · Top-level application bootstrap and runtime glue. · `src/main.tsx`
- [Ink runtime](https://github.com/noumena-network/code/blob/main/src/ink.ts): terminal runtime · Custom terminal rendering/runtime layer with layout, input, screen diffing, and replay contracts. · `src/ink.ts`
- [REPL screen](https://github.com/noumena-network/code/blob/main/src/screens/REPL.tsx): interactive screen · Primary interactive conversation surface and prompt loop UI. · `src/screens/REPL.tsx`
- [App state](https://github.com/noumena-network/code/blob/main/src/state/AppState.tsx): state store · Central app state and selectors used across UI and orchestration. · `src/state/AppState.tsx`
- [Reactive wiring](https://github.com/noumena-network/code/blob/main/src/context.ts): contexts/hooks · Context providers and hooks that connect session state to UI. · `src/context.ts`

### Session Core

Turn orchestration between prompt input, model/tool execution, replay, and bookkeeping.

- [Session engine](https://github.com/noumena-network/code/tree/main/src/session): orchestrator · Turn-by-turn orchestration between user intent, model/tool execution, cancellation, replay, and bookkeeping. · `src/session`

### Execution

Tool runtime, permissions, model/API boundary, and persistence/background services.

- [Tool service](https://github.com/noumena-network/code/tree/main/src/services/tools): tool orchestration · Streaming execution, hooks, and lifecycle management for tools. · `src/services/tools`
- [Tool set](https://github.com/noumena-network/code/tree/main/src/tools): tool implementations · Assistant-invokable tools such as shell, file, search, REPL, MCP, tasks, agents, workflows, and notifications. · `src/tools`
- [Permissions](https://github.com/noumena-network/code/tree/main/src/utils/permissions): policy boundary · Safety and approval layer for shell, file, network, plan mode, sandboxing, and trusted-device flows. · `src/utils/permissions`
- [Model/API](https://github.com/noumena-network/code/tree/main/src/services/api): provider boundary · Outbound model/provider clients, auth, usage tracking, retries, and quota/rate-limit behavior. · `src/services/api`
- [Memory & transcript](https://github.com/noumena-network/code/tree/main/src/services/sessionTranscript): persistence · Transcript storage, memory extraction, compaction, and long-running assistant background behavior. · `src/services/sessionTranscript`

### Extensibility

User-facing commands, plugins, skills, and MCP integration.

- [Slash commands](https://github.com/noumena-network/code/blob/main/src/commands.ts): command layer · User-facing command dispatcher and command-specific flows. · `src/commands.ts`
- [Plugins](https://github.com/noumena-network/code/tree/main/src/plugins): extensibility · Plugin discovery, loading, installation, trust, and output-style integration. · `src/plugins`
- [Skills](https://github.com/noumena-network/code/tree/main/src/skills): capability bundles · Reusable behavior and prompt bundles loaded into the assistant pipeline. · `src/skills`
- [MCP](https://github.com/noumena-network/code/tree/main/src/services/mcp): tool server bridge · Connections to external MCP tool servers and related auth/elicitation flows. · `src/services/mcp`

### Remote/Swarm

Remote control, bridges, peer sessions, and delegated execution paths.

- [Remote control](https://github.com/noumena-network/code/tree/main/src/remote): remote runtime · Remote sessions, bridge messaging, and transport for hosted or delegated execution. · `src/remote`
- [Bridge layer](https://github.com/noumena-network/code/tree/main/src/bridge): messaging bridge · Session bridging, messaging, peer coordination, and transport adapters. · `src/bridge`
- [Swarm runtime](https://github.com/noumena-network/code/tree/main/src/utils/swarm): multi-session runtime · In-process, tmux, and teammate execution modes with permission sync and coordination. · `src/utils/swarm`

### Native

Rust-backed and native-adjacent accelerators and shims.

- [Native addons](https://github.com/noumena-network/code/tree/main/native): rust napi · Rust-backed N-API modules for markdown rendering, websocket compatibility, and REPL hosting. · `native`
- [Native shims](https://github.com/noumena-network/code/tree/main/src/shims): adapter layer · TypeScript-facing adapters around native assets and platform-specific binaries. · `src/shims`

### Build

Packaging and binary production pipeline.

- [Build pipeline](https://github.com/noumena-network/code/tree/main/build): packaging · Build, audit, smoke, and packaging steps producing the distributed single-file CLI binary. · `build`

## Connections

- CLI entry → Main shell: boots · CLI entry bootstraps the application runtime.
- Main shell → Ink runtime: mounts · Main process initializes the terminal rendering/runtime layer.
- Ink runtime → REPL screen: renders · Ink runtime drives the interactive REPL surface.
- REPL screen → App state: reads/writes · REPL consumes and updates shared application state.
- Reactive wiring → App state: binds · Contexts and hooks expose state to components.
- Slash commands → Session engine: dispatches · Slash commands trigger session flows and specialized screens.
- REPL screen → Session engine: submits turns · Prompt input and UI events enter the session engine.
- Session engine → Tool service: orchestrates · Session engine delegates execution to the tool service.
- Tool service → Tool set: runs · Tool service executes concrete tool implementations.
- Tool service → Permissions: checks · Risky actions are gated through the permission boundary.
- Tool set → Permissions: requests approval · Tools surface permission requests before execution.
- Session engine → Model/API: calls model · Turns are converted into provider requests and responses.
- Model/API → Memory & transcript: records · Model and transcript outputs feed persistence and memory workflows.
- Memory & transcript → Session engine: feeds context · Stored transcript and memories are consumed by later turns.
- Remote control → Bridge layer: transports · Remote sessions exchange messages through bridge infrastructure.
- Bridge layer → Session engine: routes · Bridge messages are mapped into session dispatches.
- Swarm runtime → Session engine: coordinates · Swarm runtime manages local and teammate execution modes.
- Swarm runtime → Permissions: syncs policy · Swarm paths propagate permission state between participants.
- Plugins → Slash commands: extends · Plugins add commands and related surfaces.
- Plugins → Tool set: extends · Plugins contribute tools and hooks to the assistant pipeline.
- Skills → Session engine: influences · Skills contribute prompts and reusable behaviors during sessions.
- MCP → Tool set: exposes · MCP bridges external servers into the tool ecosystem.
- MCP → Permissions: elicits · External tool access is mediated by permissions and trust flows.
- Native addons → Native shims: adapts · Native modules are surfaced through TypeScript shims and asset loaders.
- Native shims → Ink runtime: accelerates · Terminal and rendering paths may use native-backed helpers.
- Build pipeline → Native addons: packages · Build pipeline compiles and packages Rust-backed modules.
- Build pipeline → CLI entry: emits · Build pipeline produces the distributed CLI artifact.