Code Controller

AI Dev Agents

Comment

Inspiration

The inspiration for Claude Code Companion came from the frustration of using command-line interfaces for AI coding assistants. While Claude Code CLI from Anthropic is powerful, we found that many developers prefer a graphical interface and want to maintain context across multiple conversations. We wanted to create a solution that combines the power of Claude Code with the convenience and organization of a modern web UI.

We were also inspired by the way VS Code extensions like GitHub Copilot and ChatGPT have transformed coding workflows, but wanted to create a standalone solution that works across any development environment and keeps conversations organized by project directory.

What it does

Claude Code Companion is a modern web interface for Anthropic's Claude Code CLI that enhances the developer experience through:

  1. Persistent chat sessions - Maintain multiple conversations with Claude, each with its own history
  2. Directory-based conversations - Organize chats by project directories to keep context relevant
  3. Command shortcuts - Quick access to common commands like /clear and /compact
  4. Modern UI - A clean, responsive interface built with React and Tailwind CSS
  5. Message formatting - Proper handling of bullet points and command outputs for improved readability
  6. Terminal integration - Seamless connection to the underlying Claude Code CLI

The application consists of a Node.js backend that spawns and manages a persistent Claude Code process, and a React frontend that provides an intuitive chat interface with features like directory navigation and command management.

How we built it

We built Claude Code Companion as a full-stack JavaScript application:

Backend:

  • Node.js server with Express.js for the API
  • node-pty for terminal interaction with Claude Code CLI
  • Custom wrapper to manage the Claude process lifecycle
  • RESTful API endpoints for prompts and directory listing
  • Error handling and automatic process recovery

Frontend:

  • React with TypeScript for type safety
  • Tailwind CSS and Radix UI components for the interface
  • Custom event system for cross-component communication
  • React Query for data fetching and state management
  • Responsive design for mobile and desktop use

Architecture:

  1. The backend spawns a pseudoterminal running the Claude Code CLI
  2. A wrapper manages input/output and parses responses
  3. The Express server exposes a REST API for the frontend
  4. The React app communicates with the API to send prompts and receive responses
  5. A custom event system enables directory-based chat organization

Challenges we ran into

  1. Terminal Interaction: Parsing Claude's TUI (Terminal User Interface) responses proved challenging since we needed to strip ANSI codes, handle command approvals, and identify when responses were complete.

  2. Response Formatting: Claude often returns bullet-point formatted responses, which needed special handling to display correctly in the UI. We implemented a system that splits these into separate messages for a more natural chat flow.

  3. Command Handling: Implementing commands like /clear required both client-side and server-side handling to ensure a responsive experience while maintaining consistency.

  4. Directory Navigation: Creating a system for directory-based conversations required careful state management and a custom event system to bridge component boundaries.

  5. Persistent Connection: Ensuring the Claude process stays alive and recovers from crashes was critical for a good user experience, requiring careful error handling and reconnection logic.

Accomplishments that we're proud of

  1. Seamless Terminal Integration: We successfully created a bridge between the terminal-based Claude Code and a modern web UI without sacrificing functionality.

  2. Directory-Aware Conversations: We implemented a system that understands project structure and allows conversations to be organized by directory, making it easier to work on multiple projects.

  3. Response Parsing Intelligence: Our solution intelligently handles Claude's bullet-point responses, command outputs, and various formatting quirks to provide a cleaner experience.

  4. Command Auto-Approval: The system can automatically approve safe command executions, reducing the friction in the development workflow.

  5. Resilience: The application gracefully handles disconnections, timeouts, and process crashes with automatic recovery.

What we learned

  1. Terminal Interaction Complexity: Working with terminal-based applications programmatically requires careful handling of ANSI escape codes, control sequences, and timing issues.

  2. Event-Based Architecture: We learned that a custom event system can effectively bridge component boundaries in React when direct prop passing isn't feasible.

  3. Response Parsing Strategies: Developing heuristics for determining when an AI has completed its response requires balancing reliability with responsiveness.

  4. Error Recovery Patterns: Implementing graceful recovery from process failures is essential for applications that maintain long-running processes.

  5. UI/UX Considerations: The importance of visual feedback (like loading indicators) and consistent interface elements when working with potentially slow or unreliable backend services.

What's next for Code Controller

  1. Enhanced Directory Navigation: Implement deeper directory browsing capabilities, allowing users to navigate subdirectories and maintain context.

  2. Workspace Management: Add support for saving and loading entire workspaces with multiple conversations.

  3. Command History: Implement a command history feature to easily reuse previous prompts.

  4. Integrated File Browser: Add a file browser to view and edit files directly within the interface.

  5. Custom Command Shortcuts: Allow users to define their own command shortcuts for frequently used prompts.

  6. Multi-Model Support: Expand beyond Claude to support other AI assistants through a plugin system.

  7. Collaborative Features: Add support for sharing conversations and collaborating with team members.

  8. Export/Import: Enable exporting conversations as markdown or PDF for documentation purposes.

Built With

Share this project:

Updates