How it works

Both SDKs run the Agent in a local qodercli process. The SDK exchanges JSONL messages and control requests with qodercli; qodercli 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-----------------------------------+
|                         qodercli 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 qodercli 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 qodercli path when provided; otherwise it finds the compatible runtime shipped with the package or available in the environment.
Start SDK mode. The SDK launches qodercli 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 qodercli 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 qodercli 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 qodercli 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 qodercli 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 qodercli stdin
    |   user messages
    |   control requests and matching control responses
    v
 qodercli
    |
    | qodercli 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

 qodercli 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 qodercli to interrupt the current turn; qodercli 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 qodercli.

The qodercli agent loop

qodercli 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. qodercli 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. qodercli 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; qodercli is the component that decides whether and how to execute it.

Tools, MCP, and subagents

qodercli 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, qodercli 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

qodercli 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, qodercli 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, qodercli 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 qodercli 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 qodercli 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 ----> qodercli
                                               |
                                               +----> Qoder model service
                                               |      task context and results
                                               |
                                               +----> local or configured tools
                                                      possible side effects

Authentication is passed to qodercli separately from the JSONL message stream through a temporary payload that the SDK cleans up.
qodercli sends the model service the task context needed for inference, which can include prompt content, file excerpts, and tool results.
Tools execute in the qodercli 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 qodercli communication

​The qodercli 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