How it works - Qoder CN

Both SDKs run the Agent in a local qoderclicn process. The SDK exchanges JSONL messages and control requests with qoderclicn; qoderclicn calls the model service and executes approved tools.

Architecture

+------------------------- Application -----------------------------+
|  TypeScript query()                  Python query() / SDK client   |
|              message parsing, callbacks, session controls         |
+-------------------------------+-----------------------------------+
                                |
                   local JSONL over stdin/stdout
                                |
+-------------------------------v-----------------------------------+
|                         qoderclicn SDK mode                          |
|  protocol + session  ->  agent loop  ->  permission + tool runner |
+--------------------------+----------------------+------------------+
                           |                      |
                    model requests          local execution
                           |              files / commands / MCP
                           v                      |
                  Qoder model service             |
                           |                      |
                           +------ results -------+

One local runtime session is owned by one qoderclicn process. A string-based query() normally closes that session after the final result. Multi-turn APIs keep it alive while the application sends more input.

Startup and handshake

The default local session starts in this order:

Select the runtime. The SDK uses an explicitly configured qoderclicn path when provided; otherwise it finds the compatible runtime shipped with the package or available in the environment.
Start SDK mode. The SDK launches qoderclicn with structured streaming input and output enabled. The process inherits the configured working directory and environment.
Transfer authentication. The SDK resolves the selected authentication method and provides qoderclicn with a temporary, one-time authentication payload instead of writing the credential into the message stream.
Initialize capabilities. Before sending the first task, the SDK and qoderclicn exchange an initialize control request. This registers SDK-provided hooks, agents, skills, and in-process MCP servers, then returns the runtime capabilities and available resources.
Send the task. After initialization succeeds, the SDK sends the first user message and begins yielding qoderclicn messages to the application.

Initialization failures are reported before the task runs, which helps distinguish configuration or authentication problems from an Agent failure.

SDK and qoderclicn communication

For the default process transport, each protocol message is one JSON object on one line. The SDK reads and writes this JSON Lines (JSONL) stream; applications should use the typed SDK messages rather than parse process output directly.

Application
    |
    | SDK writes to qoderclicn stdin
    |   user messages
    |   control requests and matching control responses
    v
 qoderclicn
    |
    | qoderclicn writes to stdout
    |   system, assistant, task, hook, and result messages
    |   partial stream events when enabled
    |   control requests and matching control responses
    v
 SDK message iterator

 qoderclicn stderr --------------------> diagnostics (not protocol data)

There are two logical traffic types:

Agent messages carry user input, assistant content, tool activity, progress, and the final result.
Control messages perform initialization, interruption, session operations, permission decisions, hooks, and in-process MCP calls. A request_id pairs each control response with its request, so several operations can be in flight without confusing their results.

Either side can initiate a control request. The SDK can ask qoderclicn to interrupt the current turn; qoderclicn can ask the application to approve a tool or execute an SDK-hosted hook. The SDK routes inbound requests to the configured callback and returns the callback result to qoderclicn.

The qoderclicn agent loop

qoderclicn repeatedly calls the model until the task finishes or reaches a configured limit. Tool results from one iteration become context for the next:

user task + conversation history + instructions + tool definitions
                              |
                              v
                 build the next model request
                              |
                              v
                     stream model output
                              |
                 +------------+-------------+
                 |                          |
             text/content                 tool call
                 |                          |
        emit assistant events      check policy and hooks
                                            |
                                      execute the tool
                                            |
                                 append the tool result to history
                                            |
                                            +------> next loop

                  no more tool calls
                              |
                     run completion hooks
                              |
                     emit final result

Build context. qoderclicn combines the task, conversation history, system instructions, workspace configuration, available tools, and relevant hook context.
Ask the model. Model output is streamed. Text can be surfaced immediately, while complete tool requests are sent to the execution pipeline.
Authorize the action. qoderclicn applies tool availability, allow/ask/deny rules, permission callbacks, and pre-tool hooks. A denied tool produces a tool result explaining the denial; it is not executed.
Execute tools. The runtime dispatches approved built-in tools, MCP tools, or subagents and captures their results. Independent tool calls can run concurrently when it is safe to do so.
Continue with evidence. Tool results are appended to the conversation, and the model receives another turn to inspect the outcome and choose the next action.
Finish or stop. The loop ends when the model has no more tool calls, a completion hook accepts the result, or a configured limit, interruption, cancellation, or error stops the task.

The model never opens a file or starts a process by itself. It proposes a tool call; qoderclicn is the component that decides whether and how to execute it.

Tools, MCP, and subagents

qoderclicn presents the model with only the tools available to the session:

Built-in tools read and edit files, search the project, run commands, and perform other local operations.
MCP tools can come from an external MCP server or from an in-process server hosted by the SDK application. For an in-process server, qoderclicn sends an MCP control request to the SDK, the SDK calls the registered server, and the response returns over the same control channel.
Subagents run a delegated task with their own prompt and context, usually with a narrower tool set. Their final output returns to the parent Agent as a tool result.

Tool results become model context and SDK events. Large results may be shortened in the conversation while the runtime preserves enough information for the Agent to continue safely.

Context and session state

qoderclicn owns the live conversation state. The SDK owns the application callbacks and converts protocol objects into TypeScript or Python message types. As a session grows, qoderclicn monitors its model context usage. When needed, it compacts older history into a smaller representation before the next model request. This keeps a long task moving without requiring the application to rebuild the prompt, although important details should still be stored in files or explicit session state instead of relying on unlimited conversation memory. When session persistence is enabled, qoderclicn can store a transcript and resume it later. Resume and checkpoint behavior is described in Session Storage and Checkpoint.

Completion, errors, and cancellation

Applications should keep consuming messages until they receive a result or the iterator raises an error.

A successful or failed Agent turn is summarized by the final result message, including status and available usage information.
interrupt asks qoderclicn to stop the active turn while keeping a long-lived session available where supported.
Closing or aborting the SDK stream closes the transport. The process transport first attempts a graceful shutdown and escalates if qoderclicn does not exit.
A process start failure, invalid protocol message, lost runtime, or initialization timeout is surfaced as an SDK error rather than an Agent result.

See Session Control for the public control APIs and Cost and Usage for usage fields.

Security and data flow

The local process boundary does not mean the entire task stays on the local machine.

local application <---- local protocol ----> qoderclicn
                                               |
                                               +----> Qoder model service
                                               |      task context and results
                                               |
                                               +----> local or configured tools
                                                      possible side effects

Authentication is passed to qoderclicn separately from the JSONL message stream through a temporary payload that the SDK cleans up.
qoderclicn sends the model service the task context needed for inference, which can include prompt content, file excerpts, and tool results.
Tools execute in the qoderclicn environment and may read, write, or call other systems according to their configuration.
cwd, tool allowlists, permission rules, hooks, sandboxing, and infrastructure isolation are complementary controls. Configure them according to the consequences of the task.

For approval patterns and permission modes, see Permissions. For intercepting lifecycle events, see Hooks.

TypeScript and Python session shape

The runtime protocol is shared, but each SDK exposes a language-appropriate session API:

Scenario	TypeScript	Python
One prompt, one result	`query({ prompt: string, ... })`	`query(prompt=..., options=...)`
Multiple user messages	Pass an async message iterable to `query()`	Connect a `QoderSDKClient` and call `query()` again
Read output	`for await` over discriminated message unions	`async for` over typed message objects
Runtime controls	Methods on the returned query stream	Methods on `QoderSDKClient`

Next steps

Quick Start — run the first TypeScript or Python task
Streaming Output — handle full messages and partial events
Permissions — design approval and tool policies
Tools — provide custom tools to the Agent
SDK References — find the exact API for each language

​Architecture

​Startup and handshake

​SDK and qoderclicn communication

​The qoderclicn agent loop

​Tools, MCP, and subagents

​Context and session state

​Completion, errors, and cancellation

​Security and data flow

​TypeScript and Python session shape

​Next steps