@qodo/sdk

Official TypeScript SDK for building AI-powered agents with Qodo.

Installation

npm install @qodo/sdk zod

Requirements: Node.js >= 18, ESM only

Quick Start

import { QodoSDK } from '@qodo/sdk';

const sdk = new QodoSDK();

// Simple prompt
const result = await sdk.prompt('Analyze this codebase and summarize the main components.');
console.log(result.result.final_output);

await sdk.dispose();

Streaming

import { QodoSDK, SdkEventType, matchSdkEvent } from '@qodo/sdk';

const sdk = new QodoSDK();

for await (const ev of sdk.streamPrompt('Explain this repository structure.')) {
  matchSdkEvent(ev, {
    [SdkEventType.MessageDelta]: (e) => process.stdout.write(e.data.delta),
    [SdkEventType.Final]: (e) => console.log('\n--- Done ---'),
    default: () => {},
  });
}

await sdk.dispose();

Interactive Mode

Enable interactiveMode for chat applications where the agent should ask clarifying questions:

const sdk = new QodoSDK({
  interactiveMode: true,  // Agent can ask clarifying questions
});

By default, the SDK operates non-interactively (ideal for CI/CD and automation).

Structured Output with Zod

import { QodoSDK, sdkAgent, sdkCommand } from '@qodo/sdk';
import { z } from 'zod';

const agent = sdkAgent({
  commands: {
    analyze: sdkCommand({
      name: 'analyze',
      description: 'Analyze code quality',
      instructions: 'Analyze the provided code and return structured feedback.',
      args: z.object({
        file: z.string().describe('Path to the file to analyze'),
      }),
      output: z.object({
        issues: z.array(z.object({
          line: z.number().describe('Line number'),
          severity: z.enum(['info', 'warning', 'error']).describe('Issue severity'),
          message: z.string().describe('Issue description'),
        })).describe('List of issues found'),
        summary: z.string().describe('Brief summary of code quality'),
      }),
    }),
  },
});

const sdk = QodoSDK.fromAgent(agent);
const result = await sdk.run('analyze', { args: { file: 'src/main.ts' } });
console.log(result.result.structured_output);

await sdk.dispose();

Authentication

# Option 1: Environment variable (recommended)
export QODO_API_KEY=your_api_key_here

# Option 2: Auth file
mkdir -p ~/.qodo && echo "your_api_key_here" > ~/.qodo/auth.key

Optional Dependencies

The SDK includes built-in tool servers that work out of the box. Some tools have optional system dependencies for enhanced functionality:

| Tool | Dependency | Purpose | Install | |------|------------|---------|---------| | ripgrep_search | ripgrep | Fast code/text search | See below | | git_* | git | Git operations | Usually pre-installed | | shell_execute | shell | Command execution | Built-in |

Ripgrep

For the ripgrep_search tool, you have two options:

Option 1: Install @vscode/ripgrep (Recommended)

npm install @vscode/ripgrep

This bundles ripgrep binaries for all platforms - no system installation needed. The SDK auto-detects it.

Option 2: System ripgrep

# macOS
brew install ripgrep

# Ubuntu/Debian
apt install ripgrep

# Windows
choco install ripgrep

If ripgrep is not available, the ripgrep_search tool will be unavailable and the SDK will log a warning. All other functionality works normally.

Claude Code Skill

The SDK ships with a Claude Code skill that provides context-aware assistance when building Qodo agents. Install it with:

# Install to your project
npx @qodo/sdk install-skill

# Or install globally (available in all projects)
npx @qodo/sdk install-skill --global

Once installed, use /qodo-agent in Claude Code to get help with agent configuration, SDK APIs, and common patterns.

Documentation

| Guide | Description | |-------|-------------| | Getting Started | Installation, setup, core concepts | | API Reference | QodoSDK class, methods, options | | Agent Configuration | Commands, modes, triggers, TOML/YAML | | Event Streaming | All events, handlers, patterns | | Tool Servers | Filesystem, git, shell, ripgrep tools | | Schema Builders | sdkAgent, sdkCommand, Zod integration | | Utilities | InfoClient, SessionsClient, Tracker |

Examples

See the examples/ directory:

• run-chat.mjs - Simple blocking execution
• stream-chat.mjs - Streaming with event handling
• agent-object.mjs - Code-defined agent with Zod schemas
• approval-policy.mjs - Custom tool approval policies

export QODO_API_KEY=your_key
node examples/run-chat.mjs

TypeScript

Full type definitions included. See API Reference for all exports.

License

See LICENSE file.