Concepts

Architecture

Gajae Code is a layered runtime. From CLI launch to model streams, every layer has a clear responsibility — and the public workflow surface stays small on purpose.

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 the selected mode — interactive TUI, print, RPC, RPC-UI, or ACP.

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 · RPC · RPC-UI · ACP

The layers

CLI & modes

The gjc binary registers commands such as setup, deep-interview, ralplan, ultragoal, and team, 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.

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

Registers commands and dispatches interactive, print, RPC, RPC-UI, and ACP modes.

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, team state, 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.