TypeScript SDK Introduction

Build applications with Qwen Code’s powerful TypeScript SDK

The Qwen Code TypeScript SDK provides programmatic access to Qwen Code’s AI coding capabilities. Use it to integrate AI-powered code assistance into your applications, tools, and workflows.

What is the SDK?

The SDK is a TypeScript/JavaScript library that lets you:

• Execute queries and get AI-powered code suggestions
• Stream responses in real-time
• Implement multi-turn conversations
• Create custom tools with MCP (Model Context Protocol)
• Control permissions and tool execution
• Manage session state and history

Key Features

Simple Query Interface

Execute single-turn queries with minimal setup:

import { query } from '@qwen-code/sdk';

const result = query({
  prompt: 'What files are in the current directory?',
  options: { cwd: '/path/to/project' },
});

for await (const message of result) {
  if (message.type === 'assistant') {
    console.log(message.message.content);
  }
}

Multi-Turn Conversations

Build interactive AI assistants with conversation history:

async function* generateMessages() {
  yield { type: 'user', message: { role: 'user', content: 'Create a file' } };
  yield { type: 'user', message: { role: 'user', content: 'Now read it back' } };
}

const result = query({
  prompt: generateMessages(),
  options: { permissionMode: 'auto-edit' },
});

Custom Tools via MCP

Extend Qwen Code with custom functionality:

import { z } from 'zod';
import { tool, createSdkMcpServer } from '@qwen-code/sdk';

const calculatorTool = tool(
  'calculate_sum',
  'Add two numbers',
  { a: z.number(), b: z.number() },
  async (args) => ({
    content: [{ type: 'text', text: String(args.a + args.b) }],
  })
);

const server = createSdkMcpServer({
  name: 'calculator',
  tools: [calculatorTool],
});

Fine-Grained Permission Control

Control which operations the AI can perform:

const result = query({
  prompt: 'Modify the project',
  options: {
    permissionMode: 'default',
    canUseTool: async (toolName, input) => {
      if (toolName.startsWith('read_')) {
        return { behavior: 'allow', updatedInput: input };
      }
      // Prompt user for approval
      const approved = await askUser(`Allow ${toolName}?`);
      return approved
        ? { behavior: 'allow', updatedInput: input }
        : { behavior: 'deny', message: 'User denied' };
    },
  },
});

Requirements

• Node.js: >= 18.0.0
• TypeScript: >= 5.0.0 (for TypeScript projects)

Bundle Information

From SDK version 0.1.1 onwards, the Qwen Code CLI is bundled with the SDK. No separate CLI installation is required.

If you’re using SDK version 0.1.0, you need to install Qwen Code CLI separately (>= 0.4.0) and ensure it’s in your PATH.

Use Cases

Application Integration

Embed AI coding assistance directly into your development tools:

• Code editors and IDEs
• CI/CD pipelines
• Code review systems
• Documentation generators

Automation Scripts

Automate repetitive coding tasks:

• Bulk code refactoring
• Test generation
• Code migration
• Documentation updates

Custom Workflows

Build specialized AI-powered workflows:

• Interactive code tutoring systems
• Automated bug fixing bots
• Code quality analyzers
• Project scaffolding tools

Architecture

The SDK communicates with the Qwen Code CLI via a JSON-based protocol:

┌─────────────┐         JSON Protocol        ┌──────────────┐
│  Your App   │ ◄──────────────────────────► │  Qwen CLI    │
│  (SDK)      │    (stdin/stdout/stderr)     │  Process     │
└─────────────┘                               └──────────────┘
       │                                              │
       │                                              │
       ▼                                              ▼
  SDK MCP Servers                              External MCP
  (In-process)                                 Servers

• SDK Process: Your application using the TypeScript SDK
• CLI Process: Spawned Qwen Code CLI instance
• MCP Servers: Tools that extend functionality (can run in-process or external)

Next Steps

Installation

Install the SDK and set up your project

Quick Start

Run your first query in under 5 minutes

API Reference

Explore the complete API documentation

Examples

Learn from practical examples