diff --git a/doc/dev/2026-02-24-echokit-remote-control-claude-code.md b/doc/dev/2026-02-24-echokit-remote-control-claude-code.md new file mode 100644 index 0000000..4179843 --- /dev/null +++ b/doc/dev/2026-02-24-echokit-remote-control-claude-code.md @@ -0,0 +1,198 @@ +--- +slug: echokit-remote-control-claude-code +title: "My Coding Assistant Lives in a Box Now | EchoKit" +tags: [echokit, claude-code, remote-control, voice-ai] +--- + +It was 2 AM. I was deep in a coding session, fingers flying across the keyboard, completely in the zone. Then I hit a bug. I needed to run the tests. + +Which meant breaking my flow. Switching windows. Typing the command. Waiting. Switching back. + +I thought: *What if I could just say it?* + +**Not into my phone.** Not unlocking an app. Just speak—to a device sitting on my desk. + +## A Small Device, Big Idea + +That moment sparked an experiment. What if my AI coding assistant wasn't trapped in a terminal window, but lived in a small device on my desk? What if I could speak to it like a pair programmer sitting next to me? + +Not voice typing—I hate that. But voice *commands*. Like having a junior developer who actually does things, not just suggests them. + +So I built it. + +Today, I'm excited to share how EchoKit became a voice remote control for Claude Code. And why this changes everything about how I work. + +## It Started with a Problem + +Claude Code is amazing. It writes code, fixes bugs, runs tests, explains errors. + +**Yes, Claude Code now has an official Remote Control feature for mobile and web access.** But it's designed for phones and browsers—not for hands-free voice control or physical devices. You still need to look at a screen and tap buttons. + +I wanted something different. Something that felt like... magic. + +## The Missing Piece + +I had EchoKit—my open-source voice AI device sitting on my desk. It can hear me, think, and respond. But it couldn't control my code editor. + +I needed a bridge. + +That bridge is called [echokit_pty](https://github.com/second-state/echokit_pty). + +**What is echokit_pty?** It's the web version of Claude Code, but with a superpower: a WebSocket interface. + +See, Claude Code was designed as a CLI tool. You run it in your terminal, type commands, get responses. That's great for terminal workflows. But for voice control? For remote access? For building *anything* on top of Claude Code? + +You need something more. + +echokit_pty is that "more." + +## How echokit_pty Changed Everything + +Here's what echokit_pty does: it takes Claude Code and exposes it through a WebSocket server. Suddenly, Claude Code isn't just a terminal app—it's a service that *anything* can talk to. + +My EchoKit device can send commands. A web app could send commands. A mobile app. A game controller. Anything that speaks WebSocket. + +But here's the beautiful part: it's still Claude Code. All the capabilities, all the intelligence, everything that makes Claude Code amazing—just accessible through a clean, simple interface. + +## The Setup: Three Pieces, One Experience + +Now my coding setup looks like this: + +**1. echokit_pty runs on my machine** — Starts a WebSocket server (ws://localhost:3000/ws) + +**2. EchoKit Server connects to it** — Handles speech recognition and text-to-speech + +**3. EchoKit Device sits on my desk** — Listens for my voice, speaks back responses + +``` +My Voice: "Run the tests" + ↓ +EchoKit Device (hears me) + ↓ +EchoKit Server (transcribes speech) + ↓ +echokit_pty (WebSocket connection) + ↓ +Claude Code (executes the command) + ↓ +Tests run, results stream back + ↓ +EchoKit speaks: "142 tests passed, 3 failed" +``` + +All while I keep typing. No window switching. No flow breaking. + +## A Day in the Life + +Let me show you what this actually feels like. + +**Morning:** +I sit down with coffee. "EchoKit, run the full test suite." I start reading emails while tests run in the background. Five minutes later: "Tests complete. Two failures in the auth module." + +**Afternoon:** +I'm stuck on a bug. "EchoKit, why is the login failing?" It explains the issue while I'm looking at the code. "Can you fix it?" "Done. Want me to run the tests?" "Yes." + +**Evening:** +I'm tired, don't want to type. "EchoKit, create a new feature branch called dark-mode." "Deploy staging." "Check if the build passed." Each command happens while I'm leaning back in my chair. + +It feels like having a coding companion. Not a tool—a teammate. + +## Why This Matters + +I know what you're thinking: *Voice control for coding? Sounds weird.* And doesn't Claude Code have Remote Control now? + +You're right—it *is* weird at first. But here's the thing: **Claude Code's Remote Control is great for mobile access, but EchoKit isn't your phone.** It's a dedicated device that sits on your desk. Always on. Always listening. No unlocking, no apps, no picking it up. + +Here's what I discovered: + +**It's not about voice typing.** I'm not dictating code. That would be terrible. + +**It's about having a physical device.** Think of it like a smart speaker for coding. It just sits there, ready to help. No screens to tap, no apps to open, no phone to find. + +**The magic is the always-there presence.** The device lives on my desk. It's part of my workspace. I don't need to grab anything or unlock anything. I just speak. + +**It keeps me in the flow.** That's the biggest one. I can stay focused on coding while EchoKit handles tasks in the background. It's like having a second pair of hands. + +## The Tech Behind the Magic + +If you're curious how echokit_pty works technically, here's the short version: + +**PTY** stands for "pseudo-terminal"—a Unix concept that lets a program control a terminal as if a user were typing. echokit_pty uses this to create a bridge between: +- **WebSocket clients** → send JSON commands +- **Claude Code CLI** → executes the commands +- **Response streaming** → sends results back + +It's built with Rust, runs locally, and is completely open source. No cloud required. Your code never leaves your machine. + +But here's what I care about: it just works. + +## What You Can Do + +So what does this actually look like in practice? + +**"Create a web page for me"** +→ Claude Code generates the HTML, EchoKit confirms when done + +**"Run the tests"** +→ Tests execute, EchoKit tells me the results + +**"Explain this error"** +→ Claude Code analyzes, EchoKit reads the explanation + +**"Deploy to staging"** +→ Deployment triggers, EchoKit confirms when complete + +**"Create a new branch"** +→ Git command executes, no typing required + +I can speak from across the room. Keep my hands on the keyboard while EchoKit works in the background. Get voice feedback without breaking my flow. + +## Building Your Own + +This is the part I'm most excited about: everything here is open source. + +- **EchoKit** — Open hardware, Rust firmware, fully customizable +- **echokit_pty** — Open source WebSocket interface for Claude Code +- **EchoKit Server** — Rust-based voice AI server + +You can build this yourself. Or modify it. Or extend it. + +Want to add custom voice commands? Go ahead. +Want to integrate with other tools? echokit_pty makes it possible. +Want to build a completely different interface? The WebSocket is waiting. + +## The Future + +This experiment showed me something: AI coding assistants can take many forms beyond screens and apps. + +**Claude Code's Remote Control solved mobile access.** But what about specialized hardware? What about completely hands-free experiences? What about devices that do one thing perfectly? + +echokit_pty is the bridge that makes these experiments possible. And EchoKit is just one example. + +Imagine what else we could build: +- Voice-controlled development environments +- Specialized devices for specific workflows +- Educational tools that feel like magic +- Assistive technology for developers with disabilities + +All built on top of echokit_pty's open WebSocket interface. + +## Try It Yourself + +Ready to turn your AI assistant into a physical device? + +**Full Documentation:** [Remote Control Claude Code with Your Voice](https://echokit.dev/docs/use-cases/claude-code) + +**EchoKit Hardware:** +- [EchoKit Box](https://echokit.dev/echokit_box.html) — Pre-assembled device +- [EchoKit DIY Kit](https://echokit.dev/echokit_diy.html) — Build it yourself + +**echokit_pty Repository:** [github.com/second-state/echokit_pty](https://github.com/second-state/echokit_pty) + +**Join the Community:** [EchoKit Discord](https://discord.gg/Fwe3zsT5g3) + +Build something cool. Then tell me about it. + +--- + +*PS: The first time I heard EchoKit say "Tests passed" while I was making coffee? That's when I knew this wasn't just a cool experiment. This was how I wanted to work from now on.* diff --git a/doc/dev/2026-02-25-echokit-pty-intro.md b/doc/dev/2026-02-25-echokit-pty-intro.md new file mode 100644 index 0000000..064c80e --- /dev/null +++ b/doc/dev/2026-02-25-echokit-pty-intro.md @@ -0,0 +1,185 @@ +--- +slug: echokit-pty-websocket-claude-code +title: "echokit_pty: Giving Claude Code a Remote Control" +tags: [echokit-pty, claude-code, websocket, developer-tools] +--- + +Claude Code is amazing. It writes code, fixes bugs, runs tests, explains errors. But it lives in your terminal. To use it, you type commands, get responses. It's a CLI tool, designed for terminal workflows. + +But what if you want to build something on top of Claude Code? What if you want a web app? A mobile interface? A physical device? Voice control? + +That's why we built **echokit_pty**. + +## What Is echokit_pty? + +**echokit_pty** is the web version of Claude Code with a superpower: a WebSocket interface. + +It handles Claude Code's input and output, turning its CLI into a WebSocket service. Suddenly, Claude Code isn't just a terminal app—it's a service that *any application* can talk to. + +**What makes it special?** +- Full Claude Code capabilities (file editing, command execution, tool use) +- **Clean JSON API for integrations**. Check out the full API documentation [here](https://github.com/second-state/echokit_pty?tab=readme-ov-file#api). +- **Open and extensible** - unlike Claude Code's official Remote Control, you have full control over the protocol and can customize every aspect +- **No subscription required** - free and open source vs. Max-only Remote Control +- Bidirectional streaming (real-time responses) +- Runs locally +- Built for developers building custom solutions + +## The Problem: Claude Code Is Trapped in the Terminal + +Claude Code was designed as a CLI tool. You run it in your terminal, type commands, get responses. This works great for terminal workflows. + +But what if you want to: +- Build a web app that uses Claude Code? +- Create a physical device that talks to Claude Code? +- Integrate Claude Code into another tool? +- Build a custom application that needs programmatic access? + +**Yes, Claude Code now has an official Remote Control feature** for mobile and web access. But it's designed as a user-facing feature, not a developer platform. It requires a Max subscription, uses a closed protocol, and can't be integrated into custom applications. + +That's where echokit_pty comes in. + +## The Solution: PTY + WebSocket + +The bridge is **echokit_pty**. + +**What does "pty" mean?** + +PTY stands for "pseudo-terminal"—a Unix concept that allows a program to control a terminal as if a user were typing. + +echokit_pty uses this technology to create a bridge between: +- **WebSocket clients** → send JSON commands +- **Claude Code CLI** → executes the commands +- **Response streaming** → sends results back + +## How It Works + +echokit_pty is built with Rust. Here's the architecture: + +``` +┌─────────────────┐ WebSocket ┌──────────────┐ +│ Any Client │ ◄─────────────────► │ echokit_pty │ +│ (Web, Mobile, │ (ws://localhost)│ (Rust) │ +│ Device, etc.) │ └──────┬───────┘ +└─────────────────┘ │ + │ PTY + ↓ + ┌──────────────┐ + │ Claude Code │ + │ CLI │ + └──────────────┘ +``` + +**The flow:** +1. echokit_pty starts a WebSocket server (default: `ws://localhost:3000/ws`) +2. Clients connect via WebSocket and send JSON commands +3. echokit_pty forwards commands to Claude Code CLI through a pseudo-terminal +4. Claude Code executes the command +5. Results stream back through the WebSocket in real-time + +**Example:** +```json +// Client sends +{"type": "command", "content": "run the tests"} + +// echokit_pty forwards to Claude Code + +// Results stream back +{"type": "response", "content": "Running tests...\n142 passed, 3 failed"} +``` + +## Use Cases: What Can You Build? + +The beauty of echokit_pty is that it turns Claude Code into a *platform*. Here's what you can build: + +### Voice-Controlled Coding +Speak commands, Claude Code executes, hear results. Perfect for hands-free workflows. This is what EchoKit + echokit_pty enables. + +**Why echokit_pty for voice control?** While Claude Code's Remote Control works great for mobile/web access, it doesn't support voice interfaces or custom hardware. echokit_pty's open API lets you build exactly the voice experience you need—whether that's a custom device, specialized voice commands, or integration with other speech services. + +But it's just one implementation. For more details, check out EchoKit's full integration [documentation](https://echokit.dev/docs/use-cases/claude-code). + +### Web Apps +Build a web interface for Claude Code. No terminal required. Just open a browser, connect to the WebSocket, and start coding. Great for presentations, teaching, or developers who prefer GUIs. + +### Mobile Apps +Control Claude Code from your phone. Run tests while walking. Check build status from the couch. Deploy from anywhere. Your coding environment fits in your pocket. + +### Pair Programming Platforms +Create a web app where multiple people can interact with Claude Code simultaneously. Real-time collaboration, shared context, better than screen sharing. + +### Teaching & Demos +Show Claude Code in presentations without terminal windows cluttering the screen. A clean web interface for live coding demos, tutorials, and workshops. + +### Custom Developer Tools +Build your own tools on top of Claude Code. Automations, dashboards, integrations—anything you can imagine. The WebSocket interface makes Claude Code a building block. + +### IDE Integrations +Embed Claude Code directly into your IDE. VS Code extension, JetBrains plugin, custom editor—give Claude Code a proper home in your development environment. + +## Getting Started + +**Installation:** + +First, clone and build echokit_pty: + +```bash +git clone https://github.com/second-state/echokit_pty.git +cd echokit_pty +cargo build --release --bin echokit_cc +``` + +**Running echokit_pty:** + +Set your workspace directory and start the server: + +```bash +ECHOKIT_WORKING_PATH="/path/to/your/workspace" \ +./target/release/echokit_cc -c ./run_cc.sh -b "localhost:3000" +``` + +The WebSocket server will start on `ws://localhost:3000/ws`. + +![](./2026-02-25-echokit-pty.jpg) + +## echokit_pty vs. Claude Code Remote Control + +You might be wondering: *Should I use echokit_pty or Claude Code's official Remote Control?* + +**Use Claude Code Remote Control if:** +- You want to control Claude Code from your phone or browser +- You have a Max subscription and don't need customization +- You just need remote access, not programmatic control + +**Use echokit_pty if:** +- You're building a custom application or service +- You need full control over the protocol and behavior +- You want to integrate Claude Code into hardware (voice devices, custom interfaces) +- You need a free, open-source solution +- You're building something beyond simple remote control + +**They're complementary, not competing.** Remote Control is perfect for individual developers who want mobile access. echokit_pty is for builders who want to create entirely new experiences on top of Claude Code. + +## The Vision + +Claude Code is the most capable AI coding assistant today. With Remote Control, it can now follow you beyond the terminal. But that's just the beginning. + +echokit_pty is about turning Claude Code into a true **platform for innovation**. + +Imagine what we can build: + +- Voice-controlled coding assistants with custom hardware +- Specialized interfaces for specific workflows +- Custom developer tools and dashboards +- AI-powered IDE integrations +- Educational platforms with tailored experiences + +All built on top of echokit_pty's open API. + +**Claude Code as a platform for builders, not just a tool for users.** + +--- + +**Ready to build something?** + +Start with the [echokit_pty repository](https://github.com/second-state/echokit_pty). See EchoKit's full integration [documentation](https://echokit.dev/docs/use-cases/claude-code) for a complete example. Join our [Discord community](https://discord.gg/Fwe3zsT5g3) to share your ideas. diff --git a/doc/dev/2026-02-25-echokit-pty.jpg b/doc/dev/2026-02-25-echokit-pty.jpg new file mode 100644 index 0000000..548273d Binary files /dev/null and b/doc/dev/2026-02-25-echokit-pty.jpg differ diff --git a/doc/docs/use-cases/claude-code.md b/doc/docs/use-cases/claude-code.md new file mode 100644 index 0000000..f55c47d --- /dev/null +++ b/doc/docs/use-cases/claude-code.md @@ -0,0 +1,126 @@ +--- +sidebar_position: 2 +--- + +# Remote Control Claude Code with Your Voice + +Use EchoKit as a voice remote control for Claude Code. Speak commands from across the room while your hands stay on the keyboard. Run tests, deploy code, explain errors, and manage your development workflow - all through voice commands. + +## What You Can Do + +EchoKit becomes a voice-powered remote control for Claude Code: + +- **Speak from anywhere** - Control Claude Code from across the room, no need to be at your desk +- **Hands-free operation** - Keep typing while EchoKit handles commands in the background +- **Voice commands** - Speak to EchoKit, Claude Code executes your commands, and EchoKit speaks back the results + +## How It Works + +EchoKit acts as a voice remote control for Claude Code through three components: + +``` +Your Voice Command → [EchoKit Device] → [EchoKit Server] → Claude Code (echokit_pty) → Action Executed + ↓ ↓ + ws://localhost:3000/ws Response Spoken Back + ↑ ↓ + [EchoKit Device] ← Audio Response ←──────────────┘ +``` + +1. **EchoKit Device** - Captures your voice commands and speaks back Claude Code's responses +2. **EchoKit Server** - Processes speech, connects to Claude Code via WebSocket, and returns audio +3. **Claude Code (echokit_pty)** - Web version of Claude Code that executes commands and returns responses + +## Quick Start + +Get started in 5 steps: + +### Step 1: Start echokit_pty + +First, launch the web version of Claude Code which provides the WebSocket server: + +```bash +# Clone the repository +git clone https://github.com/second-state/echokit_pty.git +cd echokit_pty + +# Start echokit_pty +cargo build --release --bin echokit_cc +ECHOKIT_WORKING_PATH="/path/to/your/workspace" target/release/echokit_cc -c ./run_cc.sh -b "localhost:3000" +``` + +The echokit_pty server starts automatically and listens on `ws://localhost:3000/ws`. + +### Step 2: Configure EchoKit Server + +Add Claude Code configuration to your EchoKit server's `config.toml`: + +```toml +addr = "0.0.0.0:8080" +hello_wav = "hello.wav" + +[asr] +platform = "openai" +url = "https://api.openai.com/v1/audio/transcriptions" +api_key = "sk_ABCD" +model = "gpt-4o-mini-transcribe" +lang = "en" + +[tts] +platform = "openai" +url = "https://api.openai.com/v1/audio/speech" +model = "gpt-4o-mini-tts" +api_key = "sk_ABCD" +voice = "ash" + +[claude] +url = "ws://localhost:3000/ws" +``` + +For this use case, you still need ASR and TTS services, but you don't need an LLM configuration since Claude Code handles that. + +### Step 3: Start EchoKit Server + +Launch the EchoKit server with the new configuration: + +```bash +cd echokit_server +cargo run -- --config config.toml +``` + +The server will connect to echokit_pty on startup. + +### Step 4: Flash EchoKit Firmware + +Flash your EchoKit device with the latest firmware: + +```bash +# Download and install espflash +cargo install espflash + +# Flash the firmware +espflash /path/to/firmware.bin +``` + +> The firmware is compatible with the standard EchoKit server. You can use your existing EchoKit device! + +### Step 5: Connect and Test + +Your EchoKit device will automatically connect to the EchoKit server. Try a voice command: + +> **"Create a web page for me"** + +EchoKit will send your command to Claude Code, which executes it and speaks back the results. + + +## Next Steps + +- [Explore EchoKit hardware options](../get-started/echokit-diy.md) +- [Learn about EchoKit server configuration](../server/echokit-server.md) +- [Check out echokit_pty repository](https://github.com/second-state/echokit_pty) +- [Join the EchoKit community](https://github.com/second-state/echokit) + +## See Also + +- [EchoKit Server Documentation](../server/echokit-server.md) +- [Flashing Firmware](../hardware/flash-firmware.md) +- [MCP Integration Guide](../config/mcp.md)