How noumena-network/code works
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: session Session engine · tools Tool set · permissions Permissions · REPL.tsx REPL screen
Components 22
Terminal UI
Ink-based terminal surface, screens, components, state wiring, and input handling.
- CLI entry · Main terminal app entry surface and startup wiring.
src/entrypoints/cli.tsx - Main shell · Top-level application bootstrap and runtime glue.
src/main.tsx - Ink runtime · Custom terminal rendering/runtime layer with layout, input, screen diffing, and replay contracts.
src/ink.ts - REPL screen · Primary interactive conversation surface and prompt loop UI.
src/screens/REPL.tsx - App state · Central app state and selectors used across UI and orchestration.
src/state/AppState.tsx - Reactive wiring · 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 · 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 · Streaming execution, hooks, and lifecycle management for tools.
src/services/tools - Tool set · Assistant-invokable tools such as shell, file, search, REPL, MCP, tasks, agents, workflows, and notifications.
src/tools - Permissions · Safety and approval layer for shell, file, network, plan mode, sandboxing, and trusted-device flows.
src/utils/permissions - Model/API · Outbound model/provider clients, auth, usage tracking, retries, and quota/rate-limit behavior.
src/services/api - Memory & transcript · 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 · User-facing command dispatcher and command-specific flows.
src/commands.ts - Plugins · Plugin discovery, loading, installation, trust, and output-style integration.
src/plugins - Skills · Reusable behavior and prompt bundles loaded into the assistant pipeline.
src/skills - MCP · 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 · Remote sessions, bridge messaging, and transport for hosted or delegated execution.
src/remote - Bridge layer · Session bridging, messaging, peer coordination, and transport adapters.
src/bridge - Swarm 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 · Rust-backed N-API modules for markdown rendering, websocket compatibility, and REPL hosting.
native - Native shims · TypeScript-facing adapters around native assets and platform-specific binaries.
src/shims
Build
Packaging and binary production pipeline.
- Build pipeline · Build, audit, smoke, and packaging steps producing the distributed single-file CLI binary.
build
Connections 27
- 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.