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

CLI Behavior

The npm package does not publish a qodercli binary inside the tarball. During npm install, the postinstall script downloads the platform-specific CLI into dist/_bundled.

If your environment blocks install scripts or network downloads, skip the bundled CLI download:

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

Then point the SDK at an existing qodercli:

export QODERCLI_PATH=/absolute/path/to/qodercli

You can also set the CLI path for a single query with options.pathToQoderCLIExecutable.

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 tests.');
}

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.