# yeachan-heo/gajae-code architecture

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

- Interactive diagram: https://gitdiagram.com/yeachan-heo/gajae-code
- Repository: https://github.com/yeachan-heo/gajae-code

## Overview

#### Purpose and entry points
Gajae-Code (`gjc`) is a Bun/TypeScript coding-agent harness for structured interview → plan → evidence-backed execution, optionally in tmux worktrees. Primary CLI startup and command dispatch are in `packages/coding-agent/src/cli.ts` and `packages/coding-agent/src/main.ts`; the published launcher is `packages/coding-agent/bin/gjc.js`. Interactive, print, and ACP modes branch from `packages/coding-agent/src/modes/`.

#### Session and agent execution core
`AgentSession` and the session manager own conversation state, model calls, tool invocation, streaming output, retries/fallbacks, and persistence. Session data is separated from UI and transports, enabling local TUI, headless CLI, SDK clients, and bots to drive the same runtime.
- `packages/coding-agent/src/session/agent-session.ts`
- `packages/coding-agent/src/session/session-manager.ts`
- `packages/agent/src/agent-loop.ts`

The agent loop consumes normalized provider streams, appends messages/tool results, enforces attempt scopes and resource accounting, then invokes maintenance such as compaction.

#### AI provider and credential boundary
`packages/ai` is the provider abstraction: model registry/selection, provider-specific request and streaming adapters, schema normalization, OAuth/API-key storage, retry policy, and usage accounting. This isolates the agent/session layer from OpenAI, Anthropic, Google, AWS Bedrock, Azure, Ollama, Cursor, GitHub Copilot, and other compatible endpoints.
- `packages/ai/src/api-registry.ts`
- `packages/ai/src/model-manager.ts`
- `packages/ai/src/providers/register-builtins.ts`
- `packages/ai/src/auth-storage.ts`

Auth broker and gateway services expose local credential/protocol mediation rather than embedding provider logic in every caller: `packages/ai/src/auth-broker/server.ts`, `packages/ai/src/auth-gateway/server.ts`.

#### Context durability and workflow control
The agent package maintains append-only context and compaction/summarization to stay within provider context limits. The coding-agent session layer persists histories, blobs, artifacts, session trees, and model/fallback state. GJC’s workflow state separately records durable deep-interview, ralplan, ultragoal, and team progress with validation and atomic writing.
- `packages/agent/src/append-only-context.ts`
- `packages/agent/src/compaction/compaction.ts`
- `packages/coding-agent/src/session/session-storage.ts`
- `packages/coding-agent/src/gjc-runtime/state-runtime.ts`
- `packages/coding-agent/src/gjc-runtime/ultragoal-runtime.ts`

This boundary makes execution evidence and workflow state survive process/UI restarts.

#### Tools, mutation, and local-runtime boundary
Tool registration connects model calls to constrained local capabilities: read/search/edit, shell/PTY, GitHub, browser, web search, MCP, LSP, notebook-style JS/Python evaluation, and optional desktop control. Editing and shell execution remain explicit tool boundaries, while extensions and hooks are loaded through dedicated capability and quarantine paths.
- `packages/coding-agent/src/tools/index.ts`
- `packages/coding-agent/src/edit/index.ts`
- `packages/coding-agent/src/exec/bash-executor.ts`
- `packages/coding-agent/src/runtime-mcp/manager.ts`
- `packages/coding-agent/src/extensibility/gjc-plugins/loader.ts`

Python execution uses a persistent kernel runtime; browser and computer control launch/manage external local processes and permissions.

#### User, automation, and remote-control surfaces
The terminal UI is a reusable component package rendered by interactive mode; controllers translate input/events into session operations. ACP supports editor-agent protocol clients. The SDK host/broker exposes session discovery, lifecycle, control, query, reverse RPC, and stdio/socket transport. Chat daemons adapt this protocol to Telegram, Discord, and Slack without terminal scraping.
- `packages/tui/src/tui.ts`
- `packages/coding-agent/src/modes/interactive-mode.ts`
- `packages/coding-agent/src/modes/acp/acp-agent.ts`
- `packages/coding-agent/src/sdk/host/host.ts`
- `packages/coding-agent/src/sdk/bus/engine.ts`

#### Native and platform infrastructure
Rust crates provide N-API native bindings for performance-sensitive and OS-dependent capabilities: PTYs, filesystem/search/edit primitives, screenshots/input, memory/process management, and isolation/copy mechanisms. The TypeScript native package loads platform binaries; release packages supply Darwin, Linux, and Windows variants.
- `crates/pi-natives/src/lib.rs`
- `crates/pi-natives/src/computer/mod.rs`
- `packages/natives/native/index.js`
- `packages/natives/scripts/build-native.ts`

The repository is a Bun workspace with Rust/Cargo native builds, optional tmux/worktrees, SQLite-backed session-related storage, and network dependencies for LLM providers, OAuth, web search, chat APIs, npm update checks, and plugin/MCP endpoints.

Main entry points: [`packages/coding-agent/src/modes/interactive-mode.ts`](https://github.com/yeachan-heo/gajae-code/blob/main/packages/coding-agent/src/modes/interactive-mode.ts) (Execution modes), [`packages/agent/src/agent-loop.ts`](https://github.com/yeachan-heo/gajae-code/blob/main/packages/agent/src/agent-loop.ts) (Agent loop), [`packages/coding-agent/src/tools/index.ts`](https://github.com/yeachan-heo/gajae-code/blob/main/packages/coding-agent/src/tools/index.ts) (Tool registry), [`packages/coding-agent/src/session/session-manager.ts`](https://github.com/yeachan-heo/gajae-code/blob/main/packages/coding-agent/src/session/session-manager.ts) (Session manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["Entry & surfaces"]
  node_launcher["Published launcher<br/>Bun launcher<br/>[gjc.js]"]
  node_cli["CLI dispatch<br/>[cli.ts]"]
  node_main["Application startup<br/>runtime bootstrap<br/>[main.ts]"]
  node_modes["Execution modes<br/>mode router"]
  node_tui["Terminal UI<br/>TUI components<br/>[tui.ts]"]
  node_acp["ACP agent<br/>editor protocol<br/>[acp-agent.ts]"]
  node_sdk["SDK host and bus<br/>remote control protocol<br/>[host.ts]"]
end

subgraph group_core["Agent runtime"]
  node_session_manager["Session manager<br/>session lifecycle<br/>[session-manager.ts]"]
  node_agent_session["Agent session<br/>conversation runtime<br/>[agent-session.ts]"]
  node_agent_loop{{"Agent loop<br/>execution loop<br/>[agent-loop.ts]"}}
  node_context["Append-only context<br/>context log"]
  node_compaction["Context compaction<br/>summarization<br/>[compaction.ts]"]
end

subgraph group_integration["Provider &amp; local integration"]
  node_ai_registry["AI registry and models<br/>provider abstraction<br/>[api-registry.ts]"]
  node_provider_builtins["Provider adapters<br/>provider registration"]
  node_auth["Auth broker and gateway<br/>credential mediation<br/>[server.ts]"]
  node_tools["Tool registry<br/>capability boundary<br/>[index.ts]"]
  node_mcp["Runtime MCP manager<br/>MCP integration<br/>[manager.ts]"]
  node_plugins["Plugin loader<br/>extension quarantine<br/>[loader.ts]"]
end

subgraph group_durability["Durability &amp; workflow"]
  node_session_storage[("Session storage<br/>persistent session store<br/>[session-storage.ts]")]
  node_workflow_state[("Workflow state<br/>durable workflow store<br/>[state-runtime.ts]")]
end

subgraph group_platform["Native platform"]
  node_natives{{"Native bindings<br/>N-API platform layer<br/>[index.js]"}}
  node_rust_natives["Rust native crate<br/>Rust implementation<br/>[lib.rs]"]
end

node_launcher -->|"starts"| node_cli
node_cli -->|"dispatches"| node_main
node_main -->|"selects"| node_modes
node_modes -->|"interactive UI"| node_tui
node_modes -->|"editor mode"| node_acp
node_modes -->|"drives sessions"| node_session_manager
node_sdk -->|"remote control"| node_session_manager
node_session_manager -->|"creates and restores"| node_agent_session
node_agent_session -->|"runs"| node_agent_loop
node_agent_loop -->|"model streams"| node_ai_registry
node_ai_registry -->|"uses adapters"| node_provider_builtins
node_ai_registry -->|"obtains credentials"| node_auth
node_agent_loop -->|"invokes tools"| node_tools
node_tools -->|"connects MCP"| node_mcp
node_tools -->|"loads extensions"| node_plugins
node_tools -->|"uses local capabilities"| node_natives
node_natives -->|"loads bindings"| node_rust_natives
node_agent_loop -->|"appends events"| node_context
node_context -->|"compacts when needed"| node_compaction
node_session_manager -->|"persists sessions"| node_session_storage
node_agent_session -->|"records workflow progress"| node_workflow_state

click node_launcher "https://github.com/yeachan-heo/gajae-code/blob/main/packages/coding-agent/bin/gjc.js"
click node_cli "https://github.com/yeachan-heo/gajae-code/blob/main/packages/coding-agent/src/cli.ts"
click node_main "https://github.com/yeachan-heo/gajae-code/blob/main/packages/coding-agent/src/main.ts"
click node_modes "https://github.com/yeachan-heo/gajae-code/blob/main/packages/coding-agent/src/modes/interactive-mode.ts"
click node_tui "https://github.com/yeachan-heo/gajae-code/blob/main/packages/tui/src/tui.ts"
click node_acp "https://github.com/yeachan-heo/gajae-code/blob/main/packages/coding-agent/src/modes/acp/acp-agent.ts"
click node_sdk "https://github.com/yeachan-heo/gajae-code/blob/main/packages/coding-agent/src/sdk/host/host.ts"
click node_session_manager "https://github.com/yeachan-heo/gajae-code/blob/main/packages/coding-agent/src/session/session-manager.ts"
click node_agent_session "https://github.com/yeachan-heo/gajae-code/blob/main/packages/coding-agent/src/session/agent-session.ts"
click node_agent_loop "https://github.com/yeachan-heo/gajae-code/blob/main/packages/agent/src/agent-loop.ts"
click node_context "https://github.com/yeachan-heo/gajae-code/blob/main/packages/agent/src/append-only-context.ts"
click node_compaction "https://github.com/yeachan-heo/gajae-code/blob/main/packages/agent/src/compaction/compaction.ts"
click node_ai_registry "https://github.com/yeachan-heo/gajae-code/blob/main/packages/ai/src/api-registry.ts"
click node_provider_builtins "https://github.com/yeachan-heo/gajae-code/blob/main/packages/ai/src/providers/register-builtins.ts"
click node_auth "https://github.com/yeachan-heo/gajae-code/blob/main/packages/ai/src/auth-broker/server.ts"
click node_tools "https://github.com/yeachan-heo/gajae-code/blob/main/packages/coding-agent/src/tools/index.ts"
click node_mcp "https://github.com/yeachan-heo/gajae-code/blob/main/packages/coding-agent/src/runtime-mcp/manager.ts"
click node_plugins "https://github.com/yeachan-heo/gajae-code/blob/main/packages/coding-agent/src/extensibility/gjc-plugins/loader.ts"
click node_session_storage "https://github.com/yeachan-heo/gajae-code/blob/main/packages/coding-agent/src/session/session-storage.ts"
click node_workflow_state "https://github.com/yeachan-heo/gajae-code/blob/main/packages/coding-agent/src/gjc-runtime/state-runtime.ts"
click node_natives "https://github.com/yeachan-heo/gajae-code/blob/main/packages/natives/native/index.js"
click node_rust_natives "https://github.com/yeachan-heo/gajae-code/blob/main/crates/pi-natives/src/lib.rs"

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_launcher,node_cli,node_main,node_modes,node_tui,node_acp,node_sdk toneBlue
class node_session_manager,node_agent_session,node_agent_loop,node_context,node_compaction toneAmber
class node_ai_registry,node_provider_builtins,node_auth,node_tools,node_mcp,node_plugins toneMint
class node_session_storage,node_workflow_state toneRose
class node_natives,node_rust_natives toneIndigo
```

## Components

### Entry & surfaces

- [Published launcher](https://github.com/yeachan-heo/gajae-code/blob/main/packages/coding-agent/bin/gjc.js): Bun launcher · `packages/coding-agent/bin/gjc.js`
- [CLI dispatch](https://github.com/yeachan-heo/gajae-code/blob/main/packages/coding-agent/src/cli.ts): CLI · `packages/coding-agent/src/cli.ts`
- [Application startup](https://github.com/yeachan-heo/gajae-code/blob/main/packages/coding-agent/src/main.ts): runtime bootstrap · `packages/coding-agent/src/main.ts`
- [Execution modes](https://github.com/yeachan-heo/gajae-code/blob/main/packages/coding-agent/src/modes/interactive-mode.ts): mode router · Interactive, print, and ACP modes select a session driver. · `packages/coding-agent/src/modes/interactive-mode.ts`
- [Terminal UI](https://github.com/yeachan-heo/gajae-code/blob/main/packages/tui/src/tui.ts): TUI components · `packages/tui/src/tui.ts`
- [ACP agent](https://github.com/yeachan-heo/gajae-code/blob/main/packages/coding-agent/src/modes/acp/acp-agent.ts): editor protocol · `packages/coding-agent/src/modes/acp/acp-agent.ts`
- [SDK host and bus](https://github.com/yeachan-heo/gajae-code/blob/main/packages/coding-agent/src/sdk/host/host.ts): remote control protocol · Provides lifecycle, control, query, and reverse RPC over stdio or sockets. · `packages/coding-agent/src/sdk/host/host.ts`

### Agent runtime

- [Session manager](https://github.com/yeachan-heo/gajae-code/blob/main/packages/coding-agent/src/session/session-manager.ts): session lifecycle · `packages/coding-agent/src/session/session-manager.ts`
- [Agent session](https://github.com/yeachan-heo/gajae-code/blob/main/packages/coding-agent/src/session/agent-session.ts): conversation runtime · Owns model calls, tool invocation, streaming, retries, and output. · `packages/coding-agent/src/session/agent-session.ts`
- [Agent loop](https://github.com/yeachan-heo/gajae-code/blob/main/packages/agent/src/agent-loop.ts): execution loop · Appends model and tool results while enforcing attempts and resource accounting. · `packages/agent/src/agent-loop.ts`
- [Append-only context](https://github.com/yeachan-heo/gajae-code/blob/main/packages/agent/src/append-only-context.ts): context log · `packages/agent/src/append-only-context.ts`
- [Context compaction](https://github.com/yeachan-heo/gajae-code/blob/main/packages/agent/src/compaction/compaction.ts): summarization · Maintains provider context limits. · `packages/agent/src/compaction/compaction.ts`

### Provider & local integration

- [AI registry and models](https://github.com/yeachan-heo/gajae-code/blob/main/packages/ai/src/api-registry.ts): provider abstraction · Selects models and normalizes provider requests and streams. · `packages/ai/src/api-registry.ts`
- [Provider adapters](https://github.com/yeachan-heo/gajae-code/blob/main/packages/ai/src/providers/register-builtins.ts): provider registration · Registers OpenAI, Anthropic, Google, Bedrock, Azure, Ollama, Copilot, and compatible endpoints. · `packages/ai/src/providers/register-builtins.ts`
- [Auth broker and gateway](https://github.com/yeachan-heo/gajae-code/blob/main/packages/ai/src/auth-broker/server.ts): credential mediation · Mediates OAuth and API-key access for local clients. · `packages/ai/src/auth-broker/server.ts`
- [Tool registry](https://github.com/yeachan-heo/gajae-code/blob/main/packages/coding-agent/src/tools/index.ts): capability boundary · Exposes constrained read, search, edit, shell, GitHub, browser, MCP, LSP, and evaluation tools. · `packages/coding-agent/src/tools/index.ts`
- [Runtime MCP manager](https://github.com/yeachan-heo/gajae-code/blob/main/packages/coding-agent/src/runtime-mcp/manager.ts): MCP integration · `packages/coding-agent/src/runtime-mcp/manager.ts`
- [Plugin loader](https://github.com/yeachan-heo/gajae-code/blob/main/packages/coding-agent/src/extensibility/gjc-plugins/loader.ts): extension quarantine · `packages/coding-agent/src/extensibility/gjc-plugins/loader.ts`

### Durability & workflow

- [Session storage](https://github.com/yeachan-heo/gajae-code/blob/main/packages/coding-agent/src/session/session-storage.ts): persistent session store · Stores histories, blobs, artifacts, session trees, and fallback state. · `packages/coding-agent/src/session/session-storage.ts`
- [Workflow state](https://github.com/yeachan-heo/gajae-code/blob/main/packages/coding-agent/src/gjc-runtime/state-runtime.ts): durable workflow store · Atomically records interview, plan, ultragoal, and team progress. · `packages/coding-agent/src/gjc-runtime/state-runtime.ts`

### Native platform

- [Native bindings](https://github.com/yeachan-heo/gajae-code/blob/main/packages/natives/native/index.js): N-API platform layer · Loads Rust-backed PTY, filesystem, search, edit, computer, and isolation capabilities. · `packages/natives/native/index.js`
- [Rust native crate](https://github.com/yeachan-heo/gajae-code/blob/main/crates/pi-natives/src/lib.rs): Rust implementation · `crates/pi-natives/src/lib.rs`

## Connections

- Published launcher → CLI dispatch: starts
- CLI dispatch → Application startup: dispatches
- Application startup → Execution modes: selects
- Execution modes → Terminal UI: interactive UI
- Execution modes → ACP agent: editor mode
- Execution modes → Session manager: drives sessions
- SDK host and bus → Session manager: remote control
- Session manager → Agent session: creates and restores
- Agent session → Agent loop: runs
- Agent loop → AI registry and models: model streams
- AI registry and models → Provider adapters: uses adapters
- AI registry and models → Auth broker and gateway: obtains credentials
- Agent loop → Tool registry: invokes tools
- Tool registry → Runtime MCP manager: connects MCP
- Tool registry → Plugin loader: loads extensions
- Tool registry → Native bindings: uses local capabilities
- Native bindings → Rust native crate: loads bindings
- Agent loop → Append-only context: appends events
- Append-only context → Context compaction: compacts when needed
- Session manager → Session storage: persists sessions
- Agent session → Workflow state: records workflow progress