Concepts

Architecture

Gajae Code is a layered runtime. From CLI launch to model streams, every layer has a clear responsibility — and SDK WebSocket, Coordinator MCP, and ACP each have a deliberately separate integration boundary.

The big picture

A normal session starts at the gjc binary, routes through command handling into session creation, then runs a stateful agent loop that streams model events, executes tools, records results, and hands state back to an interactive TUI, print, or ACP client. Applications attach to one running session through its loopback SDK WebSocket; external controllers coordinate multiple sessions through Coordinator MCP.

cli.ts           # register commands, parse options, pick a mode
  └─ main.ts     # adapt options into a session, dispatch the mode
       └─ sdk.ts # assemble settings, models, auth, skills, tools, prompt
            └─ agent-core      # stateful turn loop over the model stream
                 └─ mode       # interactive TUI · print · ACP

The layers

CLI & modes

The gjc binary registers commands such as setup, deep-interview, ralplan, ultragoal, and autoresearch, plus the default launch path. It adapts CLI options into a session and dispatches the chosen mode. The SDK layer assembles settings, the model registry, auth, workspace/context discovery, skills, rules, tools, and the system prompt before constructing the agent.

For external control, a top-level session publishes its loopback SDK discovery record at <repo>/.gjc/state/sdk/<sessionId>.json. Use its url and credential only for that session's WebSocket handshake. Use Coordinator MCP, rather than per-session WebSocket control, when a controller must coordinate multiple sessions and durable bounded turns.

Agent runtime

A stateful turn loop transforms context, calls the model stream, executes tool calls, appends tool results, and emits lifecycle events. Around the loop sits mutable state, subscriptions, prompt/continue/abort APIs, message queues, provider session state, telemetry, and compaction for long sessions.

Provider boundary

A single provider/model boundary handles LLM access: a model registry and resolution, provider implementations, auth, streaming, usage accounting, and retry/overflow handling. One clean interface keeps providers swappable and the rest of the runtime provider-agnostic.

Tools

A built-in tool registry exposes file, code, and runtime operations — reading, editing, AST tools, eval, find/search, LSP, the browser, task/subagent orchestration, IRC, todo, web search, and write. The model works against this fixed, reviewable tool surface.

Native & TUI

Rust crates exposed through N-API accelerate search, diff, syntax highlighting, shell execution, PTY sessions, token counting, and workspace scanning. The terminal UI framework renders the interactive experience: components, keybindings, autocomplete, image support, and the core render loop.

CLI & modescoding-agent

The gjc binary registers commands (setup, deep-interview, ralplan, ultragoal, autoresearch) and dispatches interactive, print, ACP, and Autoresearch missions. The SDK WebSocket and Coordinator MCP are separate external integration boundaries.

Agent runtimeagent

The stateful turn loop: transform context, stream the model, run tools, append results, emit events.

Provider boundaryai

Model registry, providers, auth, streaming, usage, and retry/overflow behind one interface.

Toolsread · edit · bash · lsp

A fixed registry for file, code, and runtime work, plus subagents, search, browser, and more.

Native & TUInatives · tui

Rust N-API helpers for search, diff, syntax, and shell; the framework that renders the TUI.

Workflow state on disk

Runtime state, specs, plans, goals, research missions, and local overrides live under .gjc/ in the working repository or worktree. Default workflow skills and role-agent prompts are bundled in source, so a missing project .gjc directory never removes the default workflow surface; project and user overrides are still discovered when present.

The public surface is intentionally fixed at four workflow skills and four role agents. Gajae Code improves by making that small method better, not by growing a skill zoo.