VerifiedPlugin
prompt-improver
Intelligent prompt optimization for Claude Code. It injects the right context at the right moment - at prompt submit, tool use, and subagent start - so Claude has what it needs before it acts.
1 skill
@severity1Development
Plugin
claude-agent-sdk-go
Unofficial Go SDK for Claude Code CLI integration. Build production-ready applications that leverage Claude's advanced code understanding, secure file operations, and external tool integrations through a clean, idiomatic Go API with comprehensive error
Plugin Signal62/100Solid
maintained67
capable37
documented100
adopted47
Stats
168
Stars
35
Forks
Maintained
Maintenance
Go
Language
MIT
License
2mo ago
Last commit
0y ago
Created
Repo: severity1/claude-agent-sdk-go
What's inside
Badges
README
Claude Agent SDK for Go
Unofficial Go SDK for Claude Code CLI integration. Build production-ready applications that leverage Claude's advanced code understanding, secure file operations, and external tool integrations through a clean, idiomatic Go API with comprehensive error handling and automatic resource management.
Two powerful APIs for different use cases:
- Query API: One-shot operations, automation, CI/CD integration
- Client API: Interactive conversations, multi-turn workflows, streaming responses
- WithClient: Go-idiomatic context manager for automatic resource management
Installation
go get github.com/severity1/claude-agent-sdk-go
Prerequisites: Go 1.18+, Node.js, Claude Code (npm install -g @anthropic-ai/claude-code)
Key Features
Two APIs for different needs - Query for automation, Client for interaction
100% Python SDK compatibility - Same functionality, Go-native design
Automatic resource management - WithClient provides Go-idiomatic context manager pattern
Session management - Isolated conversation contexts with Query() and QueryWithSession()
Built-in tool integration - File operations, AWS, GitHub, databases, and more
Production ready - Comprehensive error handling, timeouts, resource cleanup
Security focused - Granular tool permissions and access controls
Context-aware - Maintain conversation state across multiple interactions
Advanced capabilities - Permission callbacks, lifecycle hooks, file checkpointing
Usage
Query API - One-Shot Operations
Best for automation, scripting, and tasks with clear completion criteria:
package main
import (
"context"
"errors"
"fmt"
"log"
"github.com/severity1/claude-agent-sdk-go"
)
func main() {
fmt.Println("Claude Agent SDK - Query API Example")
fmt.Println("Asking: What is 2+2?")
ctx := context.Background()
// Create and execute query
iterator, err := claudecode.Query(ctx, "What is 2+2?")
if err != nil {
// Use error type helpers for specific error handling
if cliErr := claudecode.AsCLINotFoundError(err); cliErr != nil {
fmt.Printf("Claude CLI not found: %v\n", cliErr)
fmt.Println("Install with: npm install -g @anthropic-ai/claude-code")
return
}
if connErr := claudecode.AsConnectionError(err); connErr != nil {
fmt.Printf("Connection failed: %v\n", connErr)
return
}
log.Fatalf("Query failed: %v", err)
}
defer iterator.Close()
fmt.Println("\nResponse:")
// Iterate through messages
for {
message, err := iterator.Next(ctx)
if err != nil {
if errors.Is(err, claudecode.ErrNoMoreMessages) {
break
}
log.Fatalf("Failed to get message: %v", err)
}
if message == nil {
break
}
// Handle different message types
switch msg := message.(type) {
case *claudecode.AssistantMessage:
for _, block := range msg.Content {
if textBlock, ok := block.(*claudecode.TextBlock); ok {
fmt.Print(textBlock.Text)
}
}
case *claudecode.ResultMessage:
if msg.IsError {
if msg.Result != nil {
log.Printf("Error: %s", *msg.Result)
} else {
log.Printf("Error: unknown error")
}
}
}
}
fmt.Println("\nQuery completed!")
}
Client API - Interactive & Multi-Turn
WithClient provides automatic resource management (equivalent to Python's async with):
package main
import (
"context"
"fmt"
"log"
"github.com/severity1/claude-agent-sdk-go"
)
func main() {
fmt.Println("Claude Agent SDK - Client Streaming Example")
fmt.Println("Asking: Explain Go goroutines with a simple example")
ctx := context.Background()
question := "Explain what Go goroutines are and show a simple example"
// WithClient handles connection lifecycle automatically
err := claudecode.WithClient(ctx, func(client claudecode.Client) error {
fmt.Println("\nConnected! Streaming response:")
// Simple query uses default session
if err := client.Query(ctx, question); err != nil {
return fmt.Errorf("query failed: %w", err)
}
// Stream messages in real-time
msgChan := client.ReceiveMessages(ctx)
for {
select {
case message := <-msgChan:
if message == nil {
return nil // Stream ended
}
switch msg := message.(type) {
case *claudecode.AssistantMessage:
// Print streaming text as it arrives
for _, block := range msg.Content {
if textBlock, ok := block.(*claudecode.TextBlock); ok {
fmt.Print(textBlock.Text)
}
}
case *claudecode.ResultMessage:
if msg.IsError {
if msg.Result != nil {
return fmt.Errorf("error: %s", *msg.Result)
}
return fmt.Errorf("error: unknown error")
}
return nil // Success, stream complete
}
case <-ctx.Done():
return ctx.Err()
}
}
})
if err != nil {
log.Fatalf("Streaming failed: %v", err)
}
fmt.Println("\n\nStreaming completed!")
}
Session Management
Maintain conversation context across multiple queries with session management:
package main
import (
"context"
"fmt"
"log"
"github.com/severity1/claude-agent-sdk-go"
)
func main() {
fmt.Println("Claude Agent SDK - Session Management Example")
ctx := context.Background()
err := claudecode.WithClient(ctx, func(client claudecode.Client) error {
fmt.Println("\nDemonstrating isolated sessions:")
// Session A: Math conversation
sessionA := "math-session"
if err := client.QueryWithSession(ctx, "Remember this: x = 5", sessionA); err != nil {
return err
}
// Session B: Programming conversation
sessionB := "programming-session"
if err := client.QueryWithSession(ctx, "Remember this: language = Go", sessionB); err != nil {
return err
}
// Query each session - they maintain separate contexts
fmt.Println("\nQuerying math session:")
if err := client.QueryWithSession(ctx, "What is x * 2?", sessionA); err != nil {
return err
}
fmt.Println("\nQuerying programming session:")
if err := client.QueryWithSession(ctx, "What language did I mention?", sessionB); err != nil {
return err
}
// Default session query (separate from above)
fmt.Println("\nDefault session (no context from above):")
return client.Query(ctx, "What did I just ask about?") // Won't know about x or Go
})
if err != nil {
log.Fatalf("Session demo failed: %v", err)
}
fmt.Println("Session management demo completed!")
}
Traditional Client API (still supported):
func traditionalClientExample() {
ctx := context.Background()
client := claudecode.NewClient()
if err := client.Connect(ctx); err != nil {
log.Fatalf("Failed to connect: %v", err)
}
defer client.Disconnect() // Manual cleanup required
// Use client...
}
Tool Integration & External Services
Integrate with file systems, cloud services, databases, and development tools:
Core Tools (built-in file operations):
// File analysis and documentation generation
claudecode.Query(ctx, "Read all Go files and create API documentation",
claudecode.WithAllowedTools("Read", "Write"))
MCP Tools (external service integrations):
// AWS infrastructure automation
claudecode.Query(ctx, "List my S3 buckets and analyze their security settings",
claudecode.WithAllowedTools("mcp__aws-api-mcp__call_aws", "mcp__aws-api-mcp__suggest_aws_commands", "Write"))
Configuration Options
Customize Claude's behavior with functional options:
Tool & Permission Control:
claudecode.Query(ctx, prompt,
claudecode.WithAllowedTools("Read", "Write"),
claudecode.WithPermissionMode(claudecode.PermissionModeAcceptEdits))
System Behavior:
claudecode.Query(ctx, prompt,
claudecode.WithSystemPrompt("You are a senior Go developer"),
claudecode.WithModel("claude-sonnet-4-5"),
claudecode.WithMaxTurns(10))
Environment Variables (new in v0.2.5):
// Proxy configuration
claudecode.NewClient(
claudecode.WithEnv(map[string]string{
"HTTP_PROXY": "http://proxy.example.com:8080",
"HTTPS_PROXY": "http://proxy.example.com:8080",
}))
// Individual variables
claudecode.NewClient(
claudecode.WithEnvVar("DEBUG", "1"),
claudecode.WithEnvVar("CUSTOM_PATH", "/usr/local/bin"))
Context & Working Directory:
claudecode.Query(ctx, prompt,
claudecode.WithCwd("/path/to/project"),
claudecode.WithAddDirs("src", "docs"))
Session Management (Client API):
// WithClient provides isolated session contexts
err := claudecode.WithClient(ctx, func(client claudecode.Client) error {
// Default session
client.Query(ctx, "Remember: x = 5")
// Named session (isolated context)
return client.QueryWithSession(ctx, "What is x?", "math-session")
})
Programmatic Agents:
// Define custom agents for specialized tasks
claudecode.Query(ctx, "Review this codebase for security issues",
claudecode.WithAgent("security-reviewer", claudecode.AgentDefinition{
Description: "Reviews code for security vulnerabilities",
Prompt: "You are a security expert focused on OWASP top 10...",
Tools: []string{"Read", "Grep", "Glob"},
Model: claudecode.AgentModelSonnet,
}))
// Multiple agents for complex workflows
claudecode.Query(ctx, "Analyze and improve this code",
claudecode.WithAgents(map[string]claudecode.AgentDefinition{
"code-reviewer": {
Description: "Reviews code quality and best practices",
Prompt: "You are a senior engineer focused on code quality...",
Tools: []string{"Read", "Grep"},
Model: claudecode.AgentModelSonnet,
},
"test-writer": {
Description: "Writes comprehensive unit tests",
Prompt: "You are a testing expert...",
Tools: []string{"Read", "Write", "Bash"},
Model: claudecode.AgentModelHaiku,
},
}))
Available agent models: AgentModelSonnet, AgentModelOpus, AgentModelHaiku, AgentModelInherit
Documentation
- Architecture - System design and component overview
- Contributing - Development setup and guidelines
- API Reference - Complete SDK reference with all types, functions, and examples
- Python SDK Parity - Feature comparison with the Python SDK
- pkg.go.dev - GoDoc reference
Advanced Features
The SDK includes advanced capabilities for production use:
- Permission Callbacks - Programmatic tool access control (Example 11)
- Lifecycle Hooks - Intercept tool execution events (Example 12)
- File Checkpointing - Track and rewind file changes (Example 13)
- SDK MCP Servers - Create in-process custom tools (Example 14)
- Stream Diagnostics - Monitor stream health with
GetStreamIssues()andGetStreamStats()
See the examples directory for complete documentation.
When to Use Which API
Use Query API when you:
- Need one-shot automation or scripting
- Have clear task completion criteria
- Want automatic resource cleanup
- Are building CI/CD integrations
- Prefer simple, stateless operations
Use Client API (WithClient) when you:
- Need interactive conversations
- Want to build context across multiple requests
- Are creating complex, multi-step workflows
- Need real-time streaming responses
- Want to iterate and refine based on previous results
- Need automatic resource management (recommended)
Examples
See examples/README.md for detailed documentation.
Getting Started
| Example | Description |
|---|---|
01_quickstart | Query API fundamentals |
02_client_streaming | WithClient streaming basics |
03_client_multi_turn | Multi-turn conversations |
Tool Integration
| Example | Description |
|---|---|
04_query_with_tools | File operations with Query API |
05_client_with_tools | Interactive file workflows |
06_query_with_mcp | External MCP server integration |
07_client_with_mcp | Multi-turn MCP workflows |
Production Patterns
| Example | Description |
|---|---|
08_client_advanced | Error handling, model switching |
09_context_manager | WithClient vs manual patterns |
10_session_management | Session isolation |
Security & Lifecycle
| Example | Description |
|---|---|
11_permission_callback | Permission callbacks |
12_hooks | Lifecycle hooks |
13_file_checkpointing | File rewind capabilities |
14_sdk_mcp_server | In-process custom tools |
License
MIT
File tree
severity1/claude-agent-sdk-goView on GitHub
.claude/
agents/
grumpy-gopher.md
auto-memory/
config.json
commands/
qualify.md
tdd-parity-review.md
tdd-review.md
tdd.md
settings.json
.github/
workflows/
ci.yml
claude-code-review.yml.disabled
claude.yml
pkg-go-dev-sync.yml
release.yml
security.yml
.gitignore
.golangci.yml
.goreleaser.yml
ARCHITECTURE.md
cc-sdk-go-in-action-v2.gif
CLAUDE.md
cli_path_test.go
client_test.go
client.go
codecov.yml
CONTRIBUTING.md
doc.go
docs/
architecture/
advanced.md
components.md
data-flow.md
interfaces.md
patterns.md
parity.md
reference.md
tracking/
post-snapshot.md
README.md
errors.go
examples/
01_quickstart/
go.mod
go.sum
main.go
02_client_streaming/
go.mod
go.sum
main.go
03_client_multi_turn/
go.mod
go.sum
main.go
04_query_with_tools/
go.mod
go.sum
main.go
05_client_with_tools/
go.mod
go.sum
main.go
06_query_with_mcp/
go.mod
go.sum
main.go
07_client_with_mcp/
go.mod
go.sum
main.go
08_client_advanced/
go.mod
go.sum
main.go
09_context_manager/
go.mod
main.go
10_session_management/
go.mod
main.go
11_permission_callback/
main.go
12_hooks/
demo/
sample.txt
main.go
13_file_checkpointing/
demo/
notes.txt
main.go
14_sdk_mcp_server/
main.go
15_programmatic_subagents/
go.mod
main.go
16_structured_output/
go.mod
main.go
17_plugins/
go.mod
main.go
18_sandbox_security/
go.mod
main.go
19_partial_streaming/
go.mod
main.go
20_debugging_and_diagnostics/
go.mod
main.go
21_list_sessions/
go.mod
go.sum
main.go
22_session_messages/
go.mod
go.sum
main.go
CLAUDE.md
README.md
go.mod
gopher.png
integration_helpers_test.go
integration_test.go
integration_validation_test.go
internal/
cli/
CLAUDE.md
discovery_bench_test.go
discovery_test.go
discovery.go
control/
CLAUDE.md
hooks_test.go
hooks.go
mcp_test.go
mcp.go
permissions.go
protocol_bench_test.go
protocol_test.go
protocol.go
types_hook_test.go
types_hook.go
types.go
parser/
CLAUDE.md
json_bench_test.go
json_fuzz_test.go
json_test.go
json.go
session/
session_test.go
session.go
shared/
CLAUDE.md
errors_helpers_test.go
errors_test.go
errors.go
message_bench_test.go
message_fuzz_test.go
message_test.go
message.go
options_test.go
options.go
stream_test.go
stream.go
validator_test.go
validator.go
subprocess/
CLAUDE.md
config_test.go
config.go
io_test.go
io.go
process_test.go
process.go
protocol_adapter_test.go
protocol_adapter.go
transport_test.go
transport.go
LICENSE
Makefile
mcp_test.go
mcp.go
options_bench_test.go
options_test.go
options.go
query_test.go
query.go
README.md
session_integration_test.go
session_test.go
session.go
testdata/
cli_responses/
error_responses.json
large_response.json
simple_query.json
streaming_response.json
tool_usage.json
scenarios/
session_continuation.yaml
types.goMore Flows by @severity1.
@severity1FAQ
claude-agent-sdk-go is a Claude Code plugin with hand-picked skills for development work, indexed on Flowy. Install it with the command on its page. Its skills do not fire on their own yet. Request auto-invocation to have Flowy route them as you prompt. Free and open source.
- What is claude-agent-sdk-go?
- Unofficial Go SDK for Claude Code CLI integration. Build production-ready applications that leverage Claude's advanced code understanding, secure file operations, and external tool integrations through a clean, idiomatic Go API with comprehensive error
- How do I install claude-agent-sdk-go?
- Run these in Claude Code: . Then prompt normally.
- Does claude-agent-sdk-go auto-invoke its skills?
- Not yet. It is indexed on Flowy as a plain plugin. Request auto-invocation on its page and Flowy will route its skills for you as you prompt.
- Is claude-agent-sdk-go free?
- Yes. Flowy is free and open source, with nothing gated. You can read every skill in full before you install.