@qoder-ai/qoder-agent-sdk
v1.0.59
Published
TypeScript SDK for building Qoder-powered coding agents.
Readme
@qoder-ai/qoder-agent-sdk
TypeScript SDK for building applications on top of Qoder Agent.
The SDK starts qodercli for you, streams agent messages back to Node.js, and
lets your application configure tools, permissions, working directories, MCP
servers, hooks, and interactive sessions.
For compression billing messages, see 压缩费用消息接口.
Installation
npm install @qoder-ai/qoder-agent-sdk zodPrerequisites:
- Node.js 18+
- A Qoder account or another authentication method supported by your host application
zod is a peer dependency used when you define MCP tool schemas. Keep it
installed if your application uses SDK tools or MCP integration.
Runtime Behavior
query() always runs through a process-wide qodercli daemon. The first query
starts that daemon and reuses it for later queries in the same process; pass
options.daemon to bind a query to a daemon you started yourself with
startDaemon(). The daemon owns the CLI process boundary, so the SDK does not
spawn a separate CLI per query. Call shutdownDaemon() before your host
process exits to stop the shared daemon.
During npm install, the postinstall script downloads the CLI binary selected
by the package's pinned CLI version into dist/_bundled; worker packages also
deliver the worker runtime into dist/_worker.
The daemon launches qodercli either as a native process carrier or as a Node
worker runtime. startDaemon() / initDaemon() accept
launchMode: 'process' | 'worker'; without it, the first query's
options.transport (ProcessTransport or WorkerTransport) selects the
carrier, otherwise the package's DEFAULT_RUNTIME_TRANSPORT applies. Worker
mode launches the bundled dist/_worker runtime, or the runtime passed through
pathToQoderWorkerRuntime; when no worker runtime is available the daemon
falls back to the process carrier. A later query whose launch mode differs from
the ready daemon is rejected with DaemonConfigurationConflictError.
The process carrier uses pathToQoderCLIExecutable when provided, then
QODERCLI_PATH, then the bundled CLI, then a locally installed qodercli.
JavaScript CLI entries run through executable (or the SDK host's Node binary).
Options.transport, ProcessTransport, and WorkerTransport remain
available: selecting either transport no longer spawns a per-query process or
worker, it selects the shared daemon's carrier. Query options that configure
the CLI process, such as pathToQoderCLIExecutable, executable,
executableArgs, env, proxy, vpcEndpoint, and auth, configure the
shared daemon instead. Because the daemon is shared, every query in one process
must pass compatible daemon-level options.
options.extraHeaders accepts a Record<string, string> for the first Qoder
main-model request of the first queryable input and its network retries. Later
tool continuations, subagents, and queries do not inherit these headers. Existing
built-in headers take precedence. Use a paired CLI build with extra_headers
support. For example, after the host obtains the user's paid-usage confirmation:
query({
prompt,
options: {
...options,
extraHeaders: { "Cosy-Paid-Confirmed": "true" },
},
});If your environment blocks install scripts or network downloads, skip postinstall runtime downloads:
QODER_SKIP_DOWNLOAD=1 npm install @qoder-ai/qoder-agent-sdk zodQODER_SKIP_DOWNLOAD only affects install-time downloads. Point the daemon at
an existing qodercli with:
export QODERCLI_PATH=/absolute/path/to/qodercliAuthentication
Every SDK query needs an explicit authentication option.
| Authentication method | Identity | Use case |
| --- | --- | --- |
| Personal Access Token (PAT) | A Qoder user | Automation that needs the user's permissions and data |
| Service Account | An organization workload | Services and jobs that should not depend on a personal account |
| Local qodercli session | The signed-in user | Interactive development on a workstation |
For a PAT, generate a token at qoder.com/account/integrations, store it in a secret manager, and expose it through the default environment variable:
export QODER_PERSONAL_ACCESS_TOKEN=your-tokenimport { accessTokenFromEnv, query } from "@qoder-ai/qoder-agent-sdk";
const q = query({
prompt: "Summarize this repository.",
options: {
auth: accessTokenFromEnv(),
cwd: process.cwd(),
},
});For a Service Account, read the key from your secret manager and pass it directly to the SDK:
import { query, serviceAccount } from "@qoder-ai/qoder-agent-sdk";
// Get the Service Account key from the host's secret manager adapter.
const serviceAccountKey = await readSecret("qoder-service-account-key");
const q = query({
prompt: "Summarize this repository.",
options: {
auth: serviceAccount({ serviceAccountKey }),
cwd: process.cwd(),
},
});The SDK and CLI obtain and refresh short-lived Service Account tokens for this
authentication method. A host can retain the Service Account key and use
serviceAccount({ fetchServiceAccountToken }) to obtain and refresh
short-lived SATs for qodercli. See the
host callback example for a
complete Token exchange and query. To reuse a signed-in developer
workstation, use qodercliAuth(). See the
SDK authentication guide for
complete setup instructions and security guidance.
Quick Start
Create demo.mjs:
import { qodercliAuth, query } from "@qoder-ai/qoder-agent-sdk";
const q = query({
prompt: process.argv.slice(2).join(" ") || "Explain what this project does.",
options: {
auth: qodercliAuth(),
cwd: process.cwd(),
},
});
try {
for await (const message of q) {
console.dir(message, { depth: null });
}
} finally {
await q.close();
}Run it:
node demo.mjs "List the important files in this repository."Basic Usage
query() runs a single SDK query and returns an async iterator of response
messages.
import { qodercliAuth, query } from "@qoder-ai/qoder-agent-sdk";
const q = query({
prompt: "Explain this repository.",
options: {
auth: qodercliAuth(),
cwd: process.cwd(),
systemPrompt: "You are a helpful assistant.",
maxTurns: 1,
},
});
for await (const message of q) {
if (message.type !== "assistant") {
continue;
}
for (const block of message.message.content) {
if (block.type === "text") {
console.log(block.text);
}
}
}Business Attribution
For Qoder integrations, set product on the daemon and type on each query. See the short integration guide.
Code Security
Built-in code security is disabled by default in SDK sessions. Enable only the capabilities the integration needs:
const q = query({
prompt: "Review this repository for security issues.",
options: {
auth: qodercliAuth(),
cwd: process.cwd(),
securityScan: {
l1StaticCheck: true,
l2LightweightScan: true,
l3DeepScan: false,
},
},
});Omitted switches remain disabled. The top-level option is authoritative for the SDK session. Enabling any switch also makes the native security skill available; project and file scans do not have a separate switch.
Tools and Permissions
Qoder Agent can use tools such as file reads, file edits, shell commands, and
MCP tools. allowedTools is an approval allowlist: listed tools are
auto-approved, while unlisted tools continue through permissionMode and
canUseTool for a decision. It does not remove tools from the agent's
available toolset. To block tools, use disallowedTools.
import { qodercliAuth, query } from "@qoder-ai/qoder-agent-sdk";
const q = query({
prompt: "Update the README introduction.",
options: {
auth: qodercliAuth(),
cwd: process.cwd(),
allowedTools: ["Read", "Edit"],
disallowedTools: ["Bash"],
permissionMode: "acceptEdits",
},
});For application-specific approval flows, provide canUseTool:
import { qodercliAuth, query } from "@qoder-ai/qoder-agent-sdk";
const q = query({
prompt: "Inspect the source code, but do not run shell commands.",
options: {
auth: qodercliAuth(),
cwd: process.cwd(),
canUseTool: async (toolName) => {
if (toolName === "Bash") {
return {
behavior: "deny",
message: "Shell commands are disabled here.",
};
}
return { behavior: "allow" };
},
},
});Plan Mode
Plan Mode is independent from tool permissions. Set its initial state with
planMode; the SDK applies it after the CLI handshake and before the first
user message, while preserving the underlying permissionMode:
const q = query({
prompt: "Plan a safe migration for this repository.",
options: {
auth: qodercliAuth(),
cwd: process.cwd(),
permissionMode: "default",
planMode: true,
},
});For a live streaming session, use q.setPlanMode(true | false) to switch the
state and q.getPlanMode() to read the authoritative current state. These APIs
require a CLI that advertises the plan_mode_v1 capability.
For compatibility with existing consumers, system/init.permissionMode is
projected as "plan" while Plan Mode is active. This does not replace the
underlying tool permission mode; after leaving Plan Mode, the field reports
that mode again. Use the Plan APIs and plan_mode_changed events as the
authoritative Plan state.
Working Directory
Use cwd to run the agent in a specific project directory:
import { qodercliAuth, query } from "@qoder-ai/qoder-agent-sdk";
const q = query({
prompt: "Analyze this project.",
options: {
auth: qodercliAuth(),
cwd: "/path/to/project",
},
});Interactive Sessions
Use an async iterable prompt when you need a long-lived, bidirectional session instead of a single string prompt.
import { qodercliAuth, query } from "@qoder-ai/qoder-agent-sdk";
function userMessage(text: string) {
return {
type: "user",
message: { role: "user", content: [{ type: "text", text }] },
parent_tool_use_id: null,
};
}
async function* conversation() {
yield userMessage("Inspect this project and summarize the main modules.");
yield userMessage("Now list the files that are most likely to need review.");
}
const q = query({
prompt: conversation(),
options: {
auth: qodercliAuth(),
cwd: process.cwd(),
},
});
for await (const message of q) {
console.dir(message, { depth: null });
}The returned Query object is useful for chat interfaces, follow-up prompts,
interrupts, runtime permission changes, MCP server management, and other
workflows that need state across multiple turns. Runtime helpers include
q.streamInput(...), q.interrupt(), q.setPermissionMode(...),
q.mcpAuthenticate(...), and q.mcpSubmitOAuthCallbackUrl(...).
Streaming user messages support three delivery priorities:
priority: "now"stops the current response and handles the message immediately.priority: "next"is the default and handles the message at the next suitable point.priority: "later"waits until the current response finishes.
shouldQuery: false adds the message to the conversation without starting a
response by itself. Its processing time still follows priority.
Assign uuid to messages that need delivery tracking or cancellation.
Do not reuse UUIDs within a session. await q.interrupt() stops the current
response without closing the session. await q.cancelAsyncMessage(uuid) returns
true when the queued message is cancelled and false when it can no longer
be cancelled.
External Session Storage
Queries persist their local session by default. Set persistSession: false for
an ephemeral query that must not create resumable session state. Ephemeral
queries cannot use sessionStore because mirroring starts from locally
committed transcript entries.
Use sessionStore when a host needs durable transcripts outside the local
machine. The SDK mirrors entries after qodercli commits them locally. A later
process can restore the same session before qodercli starts:
qodercli commit -> SDK append(key, entries) -> external store
external store -> SDK load(key) -> temporary QODER_CONFIG_DIR -> qodercli resumeimport {
InMemorySessionStore,
qodercliAuth,
query,
} from "@qoder-ai/qoder-agent-sdk";
const sessionStore = new InMemorySessionStore();
const first = query({
prompt: "Inspect this project.",
options: {
auth: qodercliAuth(),
cwd: "/path/to/project",
sessionStore,
},
});
for await (const message of first) {
console.dir(message, { depth: null });
}
const resumed = query({
prompt: "Continue the analysis.",
options: {
auth: qodercliAuth(),
cwd: "/path/to/project",
resume: "11111111-1111-4111-8111-111111111111",
sessionStore,
},
});Every store implements append(key, entries) and load(key). Implement
listSessions(projectKey) for continue: true and session listing,
listSubkeys(key) to restore and inspect child-agent transcripts, and
delete(key) for deletion. Entries are opaque JSON objects and must remain in
append order. A child transcript uses an opaque subpath such as
subagents/agent-<id>; the key does not include the on-disk .jsonl
extension.
When load() returns null or an empty array for an explicit resume, the SDK
falls back to the same local session ID. Store-backed continue starts a new
session when listSessions() has no restorable session. Unsafe subpaths are
ignored, and missing or empty child transcripts do not prevent restoration of
the main session.
sessionStoreFlush: "batched" is the default. "eager" starts each append
without waiting for the result boundary. Final append failures are emitted as
non-fatal system/mirror_error messages. Each append batch is submitted once:
the SDK does not retry a mutation whose commit outcome may be unknown.
loadTimeoutMs defaults to 60,000 ms.
Session storage cannot be combined with persistSession: false, file
checkpointing, or the Cloud Agent runtime. It works on daemon-backed queries.
Use
importSessionToStore(sessionId, store, options) to copy an existing local main
transcript, child-agent transcripts, and metadata into a store.
A Query can replace the CLI Artifact snapshot with an App-owned cumulative snapshot. Configure the callback on that Query:
import { join } from "node:path";
import {
qodercliAuth,
query,
type ResolveSessionArtifacts,
} from "@qoder-ai/qoder-agent-sdk";
const resolveSessionArtifacts: ResolveSessionArtifacts = async (
localSessionId,
cwd,
) => ({
artifacts: [
{
path: join(cwd, "outputs/report.pdf"),
displayPath: "outputs/report.pdf",
name: "report.pdf",
kind: "presented",
group: { key: "outputs", name: "Outputs" },
relativePath: "report.pdf",
},
],
});
const running = query({
prompt: "Create a report.",
options: {
auth: qodercliAuth(),
cwd: "/path/to/project",
resolveSessionArtifacts,
},
});The callback receives the local Session ID and working directory. Return the
current full snapshot; artifacts: [] clears it. If the callback is omitted or
rejects, the CLI snapshot remains in effect.
Production stores
The SDK exports the SessionStore interface but does not ship a
production-ready external storage implementation. Implement the interface
against shared storage operated by your application, then validate its
append/load ordering, project isolation, subkey handling, and deletion behavior
with the shared conformance suite under examples/session-stores/.
Custom Tools
You can expose JavaScript or TypeScript functions to Qoder Agent as in-process SDK MCP servers. This avoids managing a separate MCP subprocess for simple application-local tools.
import {
createSdkMcpServer,
qodercliAuth,
query,
tool,
} from "@qoder-ai/qoder-agent-sdk";
import { z } from "zod";
const server = createSdkMcpServer({
name: "my-tools",
version: "1.0.0",
tools: [
tool("greet", "Greet a user.", { name: z.string() }, async ({ name }) => ({
content: [{ type: "text", text: `Hello, ${name}!` }],
})),
],
});
const q = query({
prompt: "Greet Alice.",
options: {
auth: qodercliAuth(),
cwd: process.cwd(),
mcpServers: {
tools: server,
},
allowedTools: ["mcp__tools__greet"],
},
});For stdio, SSE, and Streamable HTTP MCP servers, set timeout to the hard
wall-clock limit for each tool call. The value is in milliseconds, progress
notifications do not extend it, and values below 1,000 ms are ignored.
An effective server timeout overrides MCP_TOOL_TIMEOUT. If neither is set,
the CLI uses 100,000,000 ms (about 27.8 hours). Connection and discovery
requests are independent: they use MCP_TIMEOUT, which defaults to 30,000 ms.
const q = query({
prompt: "Run the long report.",
options: {
auth: qodercliAuth(),
mcpServers: {
reports: {
type: "stdio",
command: "report-mcp-server",
timeout: 1_800_000,
},
},
allowedTools: ["mcp__reports__run_report"],
},
});The CLI also protects silent tool calls with an idle timeout: 30 minutes for
stdio and 5 minutes for remote transports. Progress resets the idle timer but
not the hard timeout. Set QODER_MCP_TOOL_IDLE_TIMEOUT to adjust the global
idle baseline, or to 0 to disable it; a valid server timeout can extend the
idle limit up to the hard timeout. In-process servers returned by
createSdkMcpServer() do not expose a server-level timeout field and do not
use the idle watchdog.
Hooks
Hooks are deterministic callbacks invoked at specific points in the agent loop. They are useful for validation, policy checks, logging, and application-specific feedback.
UserPromptSubmit callbacks receive optional image_urls: string[] after
image inputs resolve to HTTP(S) URLs. The field is omitted when no resolved
image URLs are available.
import { qodercliAuth, query } from "@qoder-ai/qoder-agent-sdk";
import type { HookCallback } from "@qoder-ai/qoder-agent-sdk";
const blockDeployScript: HookCallback = async (input) => {
if (input.hook_event_name !== "PreToolUse") {
return {};
}
if (input.tool_name !== "Bash") {
return {};
}
const toolInput = input.tool_input as { command?: unknown } | undefined;
const command = String(toolInput?.command ?? "");
if (command.includes("./deploy.sh")) {
return {
hookSpecificOutput: {
hookEventName: "PreToolUse",
permissionDecision: "deny",
permissionDecisionReason: "Deployment scripts require review.",
},
};
}
return {};
};
const q = query({
prompt: "Review this project without deploying it.",
options: {
auth: qodercliAuth(),
cwd: process.cwd(),
hooks: {
PreToolUse: [{ matcher: "Bash", hooks: [blockDeployScript] }],
},
},
});Error Handling
import {
AbortError,
ModelPolicyTimeoutError,
ProtocolVersionMismatchError,
qodercliAuth,
query,
} from "@qoder-ai/qoder-agent-sdk";
function errorCode(error: unknown): string | undefined {
if (typeof error === "object" && error !== null && "code" in error) {
const code = (error as { code?: unknown }).code;
return typeof code === "string" ? code : undefined;
}
return undefined;
}
try {
const q = query({
prompt: "Hello Qoder",
options: {
auth: qodercliAuth(),
cwd: process.cwd(),
},
});
for await (const message of q) {
console.log(message);
}
} catch (error) {
if (errorCode(error) === "auth_not_configured") {
console.error("Configure options.auth before calling query().");
} else if (error instanceof ProtocolVersionMismatchError) {
console.error("Upgrade qodercli or @qoder-ai/qoder-agent-sdk.");
} else if (error instanceof ModelPolicyTimeoutError) {
console.error("Model policy resolution timed out.");
} else if (error instanceof AbortError) {
console.error("The query was aborted.");
} else {
console.error(error);
}
}License and Terms
Copyright (c) 2026 Qoder
Use of this software is governed by the Qoder Product Service Terms:
https://qoder.com/product-service
By installing or using this package, you agree to those terms.
