{"id":50622063,"url":"https://github.com/next-bin/claude-agent-sdk-golang","last_synced_at":"2026-06-06T13:01:34.145Z","repository":{"id":351530318,"uuid":"1208719021","full_name":"next-bin/claude-agent-sdk-golang","owner":"next-bin","description":"A Go SDK for building AI agents with Claude Code. Provides a high-level API for querying Claude, managing interactive sessions, defining custom tools, intercepting agent behavior with hooks, and managing conversation sessions.","archived":false,"fork":false,"pushed_at":"2026-04-15T12:28:21.000Z","size":490,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-04-15T12:31:16.618Z","etag":null,"topics":["claude-code","golang","sdk-go"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/next-bin.png","metadata":{"files":{"readme":"README-zh.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-12T16:54:47.000Z","updated_at":"2026-04-15T12:28:26.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/next-bin/claude-agent-sdk-golang","commit_stats":null,"previous_names":["next-bin/claude-agent-sdk-golang"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/next-bin/claude-agent-sdk-golang","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/next-bin%2Fclaude-agent-sdk-golang","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/next-bin%2Fclaude-agent-sdk-golang/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/next-bin%2Fclaude-agent-sdk-golang/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/next-bin%2Fclaude-agent-sdk-golang/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/next-bin","download_url":"https://codeload.github.com/next-bin/claude-agent-sdk-golang/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/next-bin%2Fclaude-agent-sdk-golang/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33983046,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-06T02:00:07.033Z","response_time":107,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["claude-code","golang","sdk-go"],"created_at":"2026-06-06T13:01:32.591Z","updated_at":"2026-06-06T13:01:34.136Z","avatar_url":"https://github.com/next-bin.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Claude Agent SDK for Golang\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/license-MIT-blue\" alt=\"License: MIT\"\u003e\n  \u003cimg src=\"https://img.shields.io/badge/Go-1.26+-00ADD8?logo=go\u0026logoColor=white\" alt=\"Go 1.26+\"\u003e\n  \u003ca href=\"https://pkg.go.dev/github.com/next-bin/claude-agent-sdk-golang\"\u003e\u003cimg src=\"https://pkg.go.dev/badge/github.com/next-bin/claude-agent-sdk-golang.svg\" alt=\"Go Reference\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://goreportcard.com/report/github.com/next-bin/claude-agent-sdk-golang\"\u003e\u003cimg src=\"https://goreportcard.com/badge/github.com/next-bin/claude-agent-sdk-golang\" alt=\"Go Report Card\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"README.md\"\u003eEnglish\u003c/a\u003e\n\u003c/p\u003e\n\n用于构建 Claude 智能体的 Go SDK。提供查询、交互式会话、自定义工具、钩子和会话管理等高级 API。\n\n## 目录\n\n- **入门**\n  - [安装](#安装)\n  - [快速开始](#快速开始)\n- **核心概念**\n  - [基本用法](#基本用法)\n    - [工具权限](#工具权限)\n    - [工作目录](#工作目录)\n  - [交互式会话](#交互式会话)\n  - [错误处理](#错误处理)\n- **高级功能**\n  - [自定义工具](#自定义工具)\n    - [混合服务器](#混合服务器)\n  - [钩子](#钩子)\n    - [可用钩子事件](#可用钩子事件)\n  - [会话 API](#会话-api)\n  - [动态控制](#动态控制)\n  - [传输中间件](#传输中间件)\n  - [函数式选项](#函数式选项)\n- **资源**\n  - [示例](#示例)\n  - [贡献](#贡献)\n  - [相关项目](#相关项目)\n\n## 安装\n\n```bash\ngo get github.com/next-bin/claude-agent-sdk-golang\n```\n\n**依赖：**\n\n| 依赖                | 说明                                                                   |\n| ------------------- | ---------------------------------------------------------------------- |\n| **Go**              | 1.26 或更高版本                                                        |\n| **Claude Code CLI** | 已安装并认证（[安装指南](https://code.claude.com/docs/en/quickstart)） |\n\n## 快速开始\n\n```go\npackage main\n\nimport (\n    \"context\"\n    \"fmt\"\n    \"log\"\n\n    claude \"github.com/next-bin/claude-agent-sdk-golang\"\n)\n\nfunc main() {\n    ctx := context.Background()\n\n    msgChan, err := claude.Query(ctx, \"2 + 2 等于几？\", nil)\n    if err != nil {\n        log.Fatal(err)\n    }\n\n    for msg := range msgChan {\n        fmt.Printf(\"%v\\n\", msg)\n    }\n}\n```\n\n## 基本用法\n\n### 简单查询\n\n```go\nctx := context.Background()\nmsgChan, err := claude.Query(ctx, \"你好 Claude\", nil)\n```\n\n### 配置选项\n\n```go\nimport \"github.com/next-bin/claude-agent-sdk-golang/types\"\n\nopts := \u0026types.ClaudeAgentOptions{\n    SystemPrompt: types.String(\"你是一个有用的助手\"),\n    MaxTurns:     types.Int(1),\n}\n\nmsgChan, err := claude.Query(ctx, \"讲个笑话\", opts)\n```\n\n### 工作目录\n\n```go\nopts := \u0026types.ClaudeAgentOptions{\n    CWD: \"/path/to/project\",\n}\n```\n\n### 工具权限\n\n默认情况下，Claude 拥有完整的 [Claude Code 工具集](https://code.claude.com/docs/en/settings#tools-available-to-claude)。`AllowedTools` 是自动批准列表，未列出的工具会走 `PermissionMode` 和 `CanUseTool` 决策流程。\n\n```go\nopts := \u0026types.ClaudeAgentOptions{\n    AllowedTools:   []string{\"Read\", \"Write\", \"Bash\"},\n    PermissionMode: types.PermissionModePtr(types.PermissionModeAcceptEdits),\n}\n```\n\n## 交互式会话\n\n对于需要后续消息的对话，使用 `client.Client`：\n\n```go\nimport \"github.com/next-bin/claude-agent-sdk-golang/client\"\n\nc := client.NewWithOptions(\u0026types.ClaudeAgentOptions{\n    PermissionMode: types.PermissionModePtr(types.PermissionModeAcceptEdits),\n})\ndefer c.Close()\n\n// 连接并发送初始消息\nerr := c.Connect(ctx, \"你好 Claude\")\n\n// 读取响应\nfor msg := range c.ReceiveResponse(ctx) {\n    fmt.Printf(\"%T: %v\\n\", msg, msg)\n}\n\n// 发送后续消息\nerr = c.Query(ctx, \"能再详细解释一下吗？\")\n```\n\n## 自定义工具\n\n将自定义工具定义为进程内 MCP 服务器，无需管理子进程。\n\n```go\nimport \"github.com/next-bin/claude-agent-sdk-golang/sdkmcp\"\n\ngreetTool := sdkmcp.Tool(\n    \"greet\",\n    \"打招呼\",\n    sdkmcp.SimpleSchema(map[string]string{\"name\": \"string\"}),\n    func(ctx context.Context, args map[string]interface{}) (*sdkmcp.ToolResult, error) {\n        name := args[\"name\"].(string)\n        return sdkmcp.TextResult(fmt.Sprintf(\"你好，%s！\", name)), nil\n    },\n)\n\nserver := sdkmcp.CreateSdkMcpServer(\"my-tools\", []*sdkmcp.SdkMcpTool{greetTool})\n\nopts := \u0026types.ClaudeAgentOptions{\n    MCPServers:   map[string]types.McpServerConfig{\"tools\": server},\n    AllowedTools: []string{\"mcp__tools__greet\"},\n}\n```\n\n## 钩子\n\n钩子是在智能体循环特定节点由 Claude Code 应用程序调用的函数。\n\n```go\ntype bashHook struct{}\n\nfunc (h *bashHook) Execute(input types.HookInput, toolUseID *string, ctx types.HookContext) (types.HookJSONOutput, error) {\n    hookInput, ok := input.(types.PreToolUseHookInput)\n    if !ok {\n        return types.SyncHookJSONOutput{Continue_: types.Bool(true)}, nil\n    }\n\n    command, _ := hookInput.ToolInput[\"command\"].(string)\n    if strings.Contains(command, \"rm -rf\") {\n        reason := \"危险命令已被钩子拦截\"\n        return types.SyncHookJSONOutput{\n            Continue_: types.Bool(true),\n            HookSpecificOutput: types.PreToolUseHookSpecificOutput{\n                HookEventName:            \"PreToolUse\",\n                PermissionDecision:       types.String(\"deny\"),\n                PermissionDecisionReason: \u0026reason,\n            },\n        }, nil\n    }\n\n    return types.SyncHookJSONOutput{Continue_: types.Bool(true)}, nil\n}\n```\n\n### 可用钩子事件\n\n| 钩子                 | 说明           |\n| -------------------- | -------------- |\n| `PreToolUse`         | 工具执行前     |\n| `PostToolUse`        | 工具执行后     |\n| `PostToolUseFailure` | 工具失败时     |\n| `UserPromptSubmit`   | 用户提交消息时 |\n| `Stop`               | 智能体停止时   |\n| `SubagentStart`      | 子智能体启动时 |\n| `SubagentStop`       | 子智能体停止时 |\n| `PreCompact`         | 上下文压缩前   |\n| `Notification`       | 通知           |\n| `PermissionRequest`  | 请求权限时     |\n\n## 会话 API\n\n以编程方式管理对话会话。\n\n```go\nimport claude \"github.com/next-bin/claude-agent-sdk-golang\"\n\n// 列出会话\nsessions, err := claude.ListSessions(\"/path/to/project\", 10, true)\n\n// 获取会话消息\nmessages, err := claude.GetSessionMessages(sessionID, \"/path/to/project\", 0, 0)\n\n// 获取单个会话信息\ninfo := claude.GetSessionInfo(sessionID, \"/path/to/project\")\n\n// 会话操作\nerr = claude.RenameSession(sessionID, \"新标题\", \"/path/to/project\")\nerr = claude.TagSession(sessionID, \"实验\", \"/path/to/project\")\nerr = claude.DeleteSession(sessionID, \"/path/to/project\")\nresult, err := claude.ForkSession(sessionID, \"/path/to/project\", nil, nil)\n```\n\n## 动态控制\n\n在运行时控制活跃会话。\n\n```go\nerr := c.Connect(ctx)\n\n// 切换权限模式\nerr = c.SetPermissionMode(ctx, \"acceptEdits\")\n\n// 切换模型\nerr = c.SetModel(ctx, \"claude-sonnet-4-6\")\n\n// 获取上下文使用率\nusage, err := c.GetContextUsage(ctx)\nfmt.Printf(\"已使用 %.1f%% 上下文\\n\", usage.Percentage)\n\n// 获取 MCP 服务器状态\nstatus, err := c.GetMCPStatus(ctx)\n\n// 中断对话\nerr = c.Interrupt(ctx)\n```\n\n## 传输中间件\n\n中间件允许拦截传输操作，用于日志、调试、指标收集或消息转换。\n\n```go\nimport \"github.com/next-bin/claude-agent-sdk-golang/transport\"\n\n// 创建日志中间件\nloggingMiddleware := transport.NewLoggingMiddleware(\n    func(ctx context.Context, data string) {\n        log.Printf(\"[写入] %s\", data)\n    },\n    func(ctx context.Context, msg map[string]interface{}) {\n        log.Printf(\"[读取] type=%s\", msg[\"type\"])\n    },\n)\n\n// 创建指标中间件\nmetricsMiddleware := transport.NewMetricsMiddleware()\n\n// 用中间件包装传输\nwrappedTransport := transport.NewMiddlewareTransport(\n    baseTransport,\n    loggingMiddleware,\n    metricsMiddleware,\n)\n\n// 使用包装的传输与客户端\nc := client.NewWithOptions(\u0026types.ClaudeAgentOptions{})\nc.Connect(ctx)\n```\n\n### 自定义中间件\n\n```go\ntype myMiddleware struct{}\n\nfunc (m *myMiddleware) InterceptWrite(ctx context.Context, data string) (string, error) {\n    // 修改或记录写入数据\n    return data, nil\n}\n\nfunc (m *myMiddleware) InterceptRead(ctx context.Context, msg map[string]interface{}) (map[string]interface{}, error) {\n    // 过滤或转换读取消息\n    if msg[\"type\"] == \"filtered_type\" {\n        return nil, nil // 过滤掉此消息\n    }\n    return msg, nil\n}\n```\n\n## 函数式选项\n\n函数式选项提供了一种灵活的方式来配置 SDK 操作，无需大型参数结构体。\n\n```go\nimport \"github.com/next-bin/claude-agent-sdk-golang/option\"\n\n// 使用函数式选项创建配置\nconfig, err := option.NewRequestConfig(\n    option.WithSystemPrompt(\"你是一个有用的助手\"),\n    option.WithModel(types.ModelSonnet),\n    option.WithMaxTurns(5),\n    option.WithPermissionMode(types.PermissionModeAcceptEdits),\n)\n\n// 组合选项\nbaseOptions := []option.RequestOption{\n    option.WithSystemPrompt(\"基础提示\"),\n    option.WithMaxTurns(10),\n}\n\nextraOptions := []option.RequestOption{\n    option.WithModel(types.ModelOpus),\n}\n\nallOptions := append(baseOptions, extraOptions...)\nconfig, err := option.NewRequestConfig(allOptions...)\n```\n\n### 可用选项\n\n| 选项 | 说明 |\n|------|------|\n| `WithSystemPrompt(prompt)` | 设置系统提示 |\n| `WithModel(model)` | 设置 AI 模型 |\n| `WithMaxTurns(turns)` | 设置最大对话轮次 |\n| `WithPermissionMode(mode)` | 设置权限模式 |\n| `WithTools(tools)` | 设置允许的工具 |\n| `WithHooks(hooks)` | 设置钩子配置 |\n| `WithMCPServers(servers)` | 设置 MCP 服务器配置 |\n| `WithCWD(dir)` | 设置工作目录 |\n| `WithEffort(level)` | 设置努力级别 (low/medium/high/max) |\n\n## 错误处理\n\n```go\nimport claude \"github.com/next-bin/claude-agent-sdk-golang\"\n\nmsgChan, err := claude.Query(ctx, \"Hello\", nil)\nif err != nil {\n    switch {\n    case claude.ErrNotInstalled:\n        fmt.Println(\"请安装 Claude Code\")\n    case claude.ErrConnectionFailed:\n        fmt.Println(\"连接失败\")\n    case claude.ErrTimeout:\n        fmt.Println(\"查询超时\")\n    default:\n        fmt.Printf(\"错误: %v\\n\", err)\n    }\n}\n```\n\n## 示例\n\n| 示例                                         | 说明           |\n| -------------------------------------------- | -------------- |\n| [quick_start](examples/quick_start/)         | 基本查询       |\n| [streaming_mode](examples/streaming_mode/)   | 交互式客户端   |\n| [mcp_sdk_server](examples/mcp_sdk_server/)   | 自定义工具     |\n| [hooks](examples/hooks/)                     | 钩子系统       |\n| [tool_permission](examples/tool_permission/) | 权限回调       |\n| [agents](examples/agents/)                   | 自定义智能体   |\n| [middleware](examples/middleware/)           | 传输中间件     |\n| [options](examples/options/)                 | 函数式选项     |\n\n## 贡献\n\n1. Fork 本仓库\n2. 创建功能分支 (`git checkout -b feature/amazing-feature`)\n3. 为新功能添加测试\n4. 提交 Pull Request\n\n### 开发\n\n```bash\ngit clone https://github.com/next-bin/claude-agent-sdk-golang.git\ncd claude-agent-sdk-golang\ngo mod download\ngo test ./...\ngo vet ./...\n```\n\n## 相关项目\n\n- [Claude Code 文档](https://code.claude.com/docs/en) — Claude Code 文档\n- [MCP 规范](https://modelcontextprotocol.io/) — Model Context Protocol\n- [Anthropic API](https://docs.anthropic.com/) — Anthropic API 文档\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnext-bin%2Fclaude-agent-sdk-golang","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnext-bin%2Fclaude-agent-sdk-golang","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnext-bin%2Fclaude-agent-sdk-golang/lists"}