@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.

Installation

npm install @qoder-ai/qoder-agent-sdk zod

Prerequisites:

• 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

The standard npm package keeps the existing process runtime behavior: query() launches qodercli as a child process by default. During npm install, the postinstall script downloads the platform-specific CLI into dist/_bundled.

Packages built with the Worker runtime bundle bake that choice into the SDK: their default query() transport is WorkerTransport.default, and install does not download the process CLI unless QODER_INSTALL_BUNDLED_CLI=1 is set. Worker runtime assets can either be packaged into the tarball or downloaded by postinstall, depending on the release pipeline.

You can still select a transport explicitly on the same query() entry:

import {
  qodercliAuth,
  query,
  WorkerTransport,
} from "@qoder-ai/qoder-agent-sdk";

const q = query({
  prompt: "Summarize this repository.",
  options: {
    auth: qodercliAuth(),
    transport: WorkerTransport.default,
  },
});

When the package includes dist/_worker/qoder-worker-runtime.obf.mjs, the worker transport uses that embedded runtime; otherwise set QODER_WORKER_RUNTIME_PATH or pass new WorkerTransport({ pathToQoderWorkerRuntime }).

Worker-bundled packages include a dist/runtime-manifest.json that records the default runtime and whether the Worker runtime is packaged or installed by postinstall. Install-delivered packages can also pin the qodercli Worker runtime archive URL in that manifest; the SDK package itself does not need to host a copy of the archive. The presence of dist/_worker is used as an integrity check after installation, not as the mode selector.

The packaged Worker runtime is built as a self-contained universal profile by default. Runtime assets such as native keychain bindings, PTY bindings, image processing bindings, devtools support, and ripgrep binaries are carried by the SDK package instead of by the host product.

If your environment blocks install scripts or network downloads, skip postinstall runtime downloads:

QODER_SKIP_DOWNLOAD=1 npm install @qoder-ai/qoder-agent-sdk zod

QODER_SKIP_DOWNLOAD only affects install-time downloads. It does not change the package's default runtime. Then point the process transport at an existing qodercli, or point the worker transport at an existing runtime:

export QODERCLI_PATH=/absolute/path/to/qodercli
# or
export QODER_WORKER_RUNTIME_PATH=/absolute/path/to/qoder-worker-runtime.obf.mjs

query() is the only query entry point. Standard packages default to process; Worker-bundled packages default to Worker. Pass transport: ProcessTransport.default, transport: WorkerTransport.default, or a custom transport provider when a single call needs to override the package default.

Authentication

Every SDK query needs an explicit authentication option.

To reuse the local qodercli login state:

import { qodercliAuth, query } from "@qoder-ai/qoder-agent-sdk";

const q = query({
  prompt: "Summarize this repository.",
  options: {
    auth: qodercliAuth(),
    cwd: process.cwd(),
  },
});

To authenticate with a personal access token:

Generate a Personal Access Token at qoder.com/account/integrations:

1. Sign in to your Qoder account.
2. Open the integrations page.
3. Create a new PAT, choosing the expiry and scopes you need.
4. Copy the token immediately. The value cannot be retrieved again after the page is closed.

Use separate tokens for local scripts, CI, and production services when possible, so each environment can be revoked independently. Do not hard-code tokens in source code.

export QODER_PERSONAL_ACCESS_TOKEN=your-token

import { accessTokenFromEnv, query } from "@qoder-ai/qoder-agent-sdk";

const q = query({
  prompt: "Summarize this repository.",
  options: {
    auth: accessTokenFromEnv(),
    cwd: process.cwd(),
  },
});

accessTokenFromEnv() reads QODER_PERSONAL_ACCESS_TOKEN by default.

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);
    }
  }
}

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" };
    },
  },
});

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(...).

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"],
  },
});

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.

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.