[FEATURE] Add example web application using Agent SDK with browser-based tool approval
Preflight Checklist
- [x] I have searched existing requests and this feature hasn't been requested yet
- [x] This is a single feature request (not multiple features)
Problem Statement
The Agent SDK documentation and examples focus on CLI/terminal usage. All canUseTool examples use terminal input() prompts. All streaming examples print to stdout. There is no guidance or example for the common use case of building a web-based interface for Claude Code agents.
Third-party projects like The Vibe Companion demonstrate significant demand for browser-based Claude Code interaction. However, without official guidance, these projects resort to reverse-engineering internal protocols rather than building on the Agent SDK.
Proposed Solution
Add an example web application to the claude-agent-sdk-demos repository that demonstrates:
- Backend: A Node.js/Python server using the Agent SDK with WebSocket connections to browser clients
- Streaming to browser: Forwarding
StreamEventmessages to the browser via WebSocket or SSE - Tool approval via browser: Implementing
canUseToolthat sends approval requests to the browser and waits for user response - Session management: Creating, resuming, and listing agent sessions via HTTP API
- Basic frontend: A minimal React/vanilla JS chat interface showing streaming responses and tool approval UI
The example should be minimal (not a full product) but demonstrate the pattern clearly enough for developers to adapt.
Alternative Solutions
- Document the
--input-format stream-jsonstdin protocol: This would let developers build web UIs by wrapping the CLI with bidirectional stdin/stdout. Less elegant than the SDK but works today. - Document the internal WebSocket protocol: Not recommended -- this would commit to an internal API. The SDK is the right abstraction layer.
- Link to community examples: Point to well-built third-party implementations. Risk: they may use unsupported internals or become unmaintained.
Priority
- [ ] Critical - Blocking my work
- [ ] High - Significant impact on productivity
- [x] Medium - Would be very helpful
- [ ] Low - Nice to have
Feature Category
- [ ] CLI commands and flags
- [ ] Interactive mode (TUI)
- [ ] File operations
- [ ] API and model interactions
- [ ] MCP server integration
- [ ] Performance and speed
- [ ] Configuration and settings
- [x] Developer tools/SDK
- [x] Documentation
- [ ] Other
Use Case Example
A developer wants to build a team dashboard where multiple developers can launch Claude Code agents from their browsers, see streaming responses, approve tool calls, and manage sessions. Currently they would need to:
- Read the Agent SDK docs (terminal-focused examples)
- Figure out how to bridge
canUseToolcallbacks to WebSocket connections - Figure out how to stream
StreamEventmessages to the browser - Handle session lifecycle via HTTP API
- Build a tool approval UI without any reference implementation
An official example would reduce this from days of experimentation to hours of adaptation.
Additional Context
The Agent SDK streaming-output.md page already has a "Build a streaming UI" section, but it's terminal-only (uses process.stdout.write). The user-input.md page has thorough canUseTool documentation, but all examples use readline for terminal input. The pieces are there; they just need a web-oriented example tying them together.
The existing claude-agent-sdk-demos repo would be the natural home for this.
This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗