Skip to main content
Getting Started

Quick Start

Qoder Agent SDK lets you call Qoder AI capabilities from TypeScript, Python, or Java—reading and writing files, searching code, running commands, and more—embedding an AI agent into your app or script with just a few lines of code.

Prerequisites

  • TypeScript: Node.js 18+
  • Python: Python 3.10+
  • Java: JRE 8+

Install

npm install @qoder-ai/qoder-agent-sdk
With Gradle, add implementation 'com.qoder.sdk:qoder-agent-sdk:VERSION'. In both Maven and Gradle, replace VERSION with a released SDK version from Maven Central. The Java SDK does not bundle qodercli. On first start it downloads the CLI version pinned to this SDK release and caches it for reuse, so the runtime environment needs access to the Qoder download site. For offline environments and self-specified CLIs, see Managed CLI (Java).

Authentication

The SDK authenticates via a Personal Access Token (PAT), ideal for scripts, CI pipelines, and third-party integration scenarios. Generate a PAT at qoder.com/account/integrations (copy it immediately — the value cannot be retrieved again after the page is closed). For full steps, custom environment variables, and reusing local qodercli credentials, see SDK Authentication. Once you have a PAT, set the environment variable first: 
export QODER_PERSONAL_ACCESS_TOKEN="<your-qoder-personal-access-token>"
node agent.mjs
Then configure authentication with accessTokenFromEnv() (TypeScript) / access_token_from_env() (Python) / Auth.accessTokenEnv() (Java): 
import { accessTokenFromEnv, query } from '@qoder-ai/qoder-agent-sdk';

const stream = query({
  prompt: 'Hello',
  options: {
    auth: accessTokenFromEnv(),
  },
});
The SDK reads this environment variable before starting qodercli and writes the parsed access token into a one-time auth payload. You typically don't need to pass the PAT via the env option; if options.env is explicitly provided, the SDK reads the same-named variable from it first. Java reads only the JVM process environment; a same-named variable passed through putEnvironment() is not used for authentication.
Security Note: Do not hard-code PATs in your code repository. Inject them via environment variables or a secrets management service.

Single-message and streaming input

The TypeScript and Python SDKs both use query() as the core entry point. When prompt is a string, one call submits one user message, and the SDK closes the session after the turn completes—ideal for one-off, stateless tasks. The Java equivalent is QoderClient.query() with a OneShotQueryRequest; the CLI exits after the turn completes. To send multiple messages in the same session and choose the next step from a response, pass an async message stream to TypeScript query(), maintain a long-lived connection with Python QoderSDKClient, or in Java open a QoderSession with QoderClient.openSession() and call send() repeatedly. See Input Modes.

Complete Example

Create agent.mjs (TypeScript), agent.py (Python), or Agent.java (Java, under src/main/java/ in a Maven project): 
import { accessTokenFromEnv, query } from '@qoder-ai/qoder-agent-sdk';

for await (const message of query({
  prompt: 'Analyze the codebase, find functions without test coverage, and write unit tests for them.',
  options: {
    auth: accessTokenFromEnv(),
    allowedTools: ['Read', 'Write', 'Edit', 'Glob', 'Grep', 'Bash'],
    permissionMode: 'acceptEdits',  // Auto-approve file edits
  },
})) {
  if (message.type === 'assistant') {
    for (const block of message.message.content) {
      if (block.type === 'text') {
        console.log(block.text);              // AI text response
      } else if (block.type === 'tool_use') {
        console.log(`Tool: ${block.name}`);   // Tool being called
      }
    }
  } else if (message.type === 'result') {
    console.log(`Done: ${message.subtype}`);  // Final result
  }
}
Run it: 
node agent.mjs
The Agent will autonomously browse the project, find functions lacking test coverage, generate test files, and run them for verification.

Next Steps