> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/QwenLM/qwen-code/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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:

```typescript theme={null}
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.

<Note>
  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.
</Note>

## 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

<CardGroup cols={2}>
  <Card title="Installation" icon="download" href="/sdk/installation">
    Install the SDK and set up your project
  </Card>

  <Card title="Quick Start" icon="rocket" href="/sdk/quick-start">
    Run your first query in under 5 minutes
  </Card>

  <Card title="API Reference" icon="book" href="/sdk/api/query">
    Explore the complete API documentation
  </Card>

  <Card title="Examples" icon="code" href="/sdk/examples/single-turn">
    Learn from practical examples
  </Card>
</CardGroup>