{"id":29806335,"url":"https://github.com/sugyan/claude-code-webui","last_synced_at":"2025-09-10T15:04:42.209Z","repository":{"id":298534259,"uuid":"999285986","full_name":"sugyan/claude-code-webui","owner":"sugyan","description":"Web-based interface for Claude CLI with streaming chat responses","archived":false,"fork":false,"pushed_at":"2025-09-06T14:56:13.000Z","size":2885,"stargazers_count":551,"open_issues_count":15,"forks_count":119,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-09-06T16:25:27.783Z","etag":null,"topics":["claude","claude-cli","web-ui"],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","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/sugyan.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"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":"2025-06-10T03:06:25.000Z","updated_at":"2025-09-06T14:56:05.000Z","dependencies_parsed_at":"2025-06-11T17:04:20.915Z","dependency_job_id":"d7739717-1301-4657-b9d4-43bb7cc0b3fe","html_url":"https://github.com/sugyan/claude-code-webui","commit_stats":null,"previous_names":["sugyan/claude-code-webui"],"tags_count":53,"template":false,"template_full_name":null,"purl":"pkg:github/sugyan/claude-code-webui","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sugyan%2Fclaude-code-webui","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sugyan%2Fclaude-code-webui/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sugyan%2Fclaude-code-webui/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sugyan%2Fclaude-code-webui/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/sugyan","download_url":"https://codeload.github.com/sugyan/claude-code-webui/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/sugyan%2Fclaude-code-webui/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274010097,"owners_count":25206763,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-07T02:00:09.463Z","response_time":67,"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","claude-cli","web-ui"],"created_at":"2025-07-28T14:05:57.637Z","updated_at":"2025-09-10T15:04:42.179Z","avatar_url":"https://github.com/sugyan.png","language":"TypeScript","readme":"# 🌐 Claude Code Web UI\n\n[![npm Version](https://img.shields.io/npm/v/claude-code-webui)](https://www.npmjs.com/package/claude-code-webui)\n[![npm Downloads](https://img.shields.io/npm/dt/claude-code-webui)](https://www.npmjs.com/package/claude-code-webui)\n[![License](https://img.shields.io/github/license/sugyan/claude-code-webui)](https://github.com/sugyan/claude-code-webui/blob/main/LICENSE)\n[![CI](https://github.com/sugyan/claude-code-webui/actions/workflows/ci.yml/badge.svg)](https://github.com/sugyan/claude-code-webui/actions/workflows/ci.yml)\n[![GitHub Release](https://img.shields.io/github/v/release/sugyan/claude-code-webui)](https://github.com/sugyan/claude-code-webui/releases)\n\n\u003e **A modern web interface for Claude Code CLI** - Transform your command-line coding experience into an intuitive web-based chat interface\n\n[🎬 **View Demo**](https://github.com/user-attachments/assets/33e769b0-b17e-470b-8163-c71ef186b5af)\n\n## 📱 Screenshots\n\n\u003cdiv align=\"center\"\u003e\n\n| Desktop Interface                                                                                                                                  | Mobile Experience                                                                                                                                |\n| -------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |\n| \u003cimg src=\"https://github.com/sugyan/claude-code-webui/raw/main/docs/images/screenshot-desktop-basic-dark.png\" alt=\"Desktop Interface\" width=\"600\"\u003e | \u003cimg src=\"https://github.com/sugyan/claude-code-webui/raw/main/docs/images/screenshot-mobile-basic-dark.png\" alt=\"Mobile Interface\" width=\"250\"\u003e |\n| _Chat-based coding interface with instant responses and ready input field_                                                                         | _Mobile-optimized chat experience with touch-friendly design_                                                                                    |\n\n\u003c/div\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e💡 Light Theme Screenshots\u003c/strong\u003e\u003c/summary\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n| Desktop (Light)                                                                                                                                 | Mobile (Light)                                                                                                                                |\n| ----------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |\n| \u003cimg src=\"https://github.com/sugyan/claude-code-webui/raw/main/docs/images/screenshot-desktop-basic.png\" alt=\"Desktop Light Theme\" width=\"600\"\u003e | \u003cimg src=\"https://github.com/sugyan/claude-code-webui/raw/main/docs/images/screenshot-mobile-basic.png\" alt=\"Mobile Light Theme\" width=\"250\"\u003e |\n| _Clean light interface for daytime coding sessions_                                                                                             | _iPhone SE optimized light theme interface_                                                                                                   |\n\n\u003c/div\u003e\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003e🔧 Advanced Features\u003c/strong\u003e\u003c/summary\u003e\n\n\u003cdiv align=\"center\"\u003e\n\n| Desktop Permission Dialog                                                                                                                                   | Mobile Permission Dialog                                                                                                                                   |\n| ----------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |\n| \u003cimg src=\"https://github.com/sugyan/claude-code-webui/raw/main/docs/images/screenshot-desktop-fileOperations-dark.png\" alt=\"Permission Dialog\" width=\"600\"\u003e | \u003cimg src=\"https://github.com/sugyan/claude-code-webui/raw/main/docs/images/screenshot-mobile-fileOperations-dark.png\" alt=\"Mobile Permission\" width=\"250\"\u003e |\n| _Secure tool access with granular permission controls and clear approval workflow_                                                                          | _Touch-optimized permission interface for mobile devices_                                                                                                  |\n\n\u003c/div\u003e\n\n\u003c/details\u003e\n\n---\n\n## 📑 Table of Contents\n\n- [✨ Why Claude Code Web UI?](#-why-claude-code-web-ui)\n- [🚀 Quick Start](#-quick-start)\n- [⚙️ CLI Options](#-cli-options)\n- [🚨 Troubleshooting](#-troubleshooting)\n- [🔧 Development](#-development)\n- [🔒 Security Considerations](#-security-considerations)\n- [📚 Documentation](#-documentation)\n- [❓ FAQ](#-faq)\n- [🤝 Contributing](#-contributing)\n- [📄 License](#-license)\n\n---\n\n## ✨ Why Claude Code Web UI?\n\n**Transform the way you interact with Claude Code**\n\nInstead of being limited to command-line interactions, Claude Code Web UI brings you:\n\n| CLI Experience                | Web UI Experience            |\n| ----------------------------- | ---------------------------- |\n| ⌨️ Terminal only              | 🌐 Any device with a browser |\n| 📱 Desktop bound              | 📱 Mobile-friendly interface |\n| 📝 Plain text output          | 🎨 Rich formatted responses  |\n| 🗂️ Manual directory switching | 📁 Visual project selection  |\n\n### 🎯 Key Features\n\n- **📋 Permission Mode Switching** - Toggle between normal and plan mode execution\n- **🔄 Real-time streaming responses** - Live Claude Code output in chat interface\n- **📁 Project directory selection** - Visual project picker for context-aware sessions\n- **💬 Conversation history** - Browse and restore previous chat sessions\n- **🛠️ Tool permission management** - Granular control over Claude's tool access\n- **🎨 Dark/light theme support** - Automatic system preference detection\n- **📱 Mobile-responsive design** - Touch-optimized interface for any device\n\n---\n\n## 🚀 Quick Start\n\nGet up and running in under 2 minutes:\n\n### Option 1: npm Package (Recommended)\n\n```bash\n# Install globally via npm\nnpm install -g claude-code-webui\n\n# Start the server\nclaude-code-webui\n\n# Open browser to http://localhost:8080\n```\n\n### Option 2: Binary Release\n\n```bash\n# Download and run (macOS ARM64 example)\ncurl -LO https://github.com/sugyan/claude-code-webui/releases/latest/download/claude-code-webui-macos-arm64\nchmod +x claude-code-webui-macos-arm64\n./claude-code-webui-macos-arm64\n\n# Open browser to http://localhost:8080\n```\n\n### Option 3: Development Mode\n\n```bash\n# Backend (choose one)\ncd backend \u0026\u0026 deno task dev    # Deno runtime\ncd backend \u0026\u0026 npm run dev      # Node.js runtime\n\n# Frontend (new terminal)\ncd frontend \u0026\u0026 npm run dev\n\n# Open browser to http://localhost:3000\n```\n\n### Prerequisites\n\n- ✅ **Claude CLI** installed and authenticated ([Get it here](https://github.com/anthropics/claude-code))\n- ✅ **Node.js \u003e=20.0.0** (for npm installation) or **Deno** (for development)\n- ✅ **Modern browser** (Chrome, Firefox, Safari, Edge)\n- ✅ **dotenvx** (for development): [Install guide](https://dotenvx.com/docs/install)\n\n---\n\n## ⚙️ CLI Options\n\nThe backend server supports the following command-line options:\n\n| Option                 | Description                                               | Default     |\n| ---------------------- | --------------------------------------------------------- | ----------- |\n| `-p, --port \u003cport\u003e`    | Port to listen on                                         | 8080        |\n| `--host \u003chost\u003e`        | Host address to bind to (use 0.0.0.0 for all interfaces)  | 127.0.0.1   |\n| `--claude-path \u003cpath\u003e` | Path to claude executable (overrides automatic detection) | Auto-detect |\n| `-d, --debug`          | Enable debug mode                                         | false       |\n| `-h, --help`           | Show help message                                         | -           |\n| `-v, --version`        | Show version                                              | -           |\n\n### Environment Variables\n\n- `PORT` - Same as `--port`\n- `DEBUG` - Same as `--debug`\n\n### Examples\n\n```bash\n# Default (localhost:8080)\nclaude-code-webui\n\n# Custom port\nclaude-code-webui --port 3000\n\n# Bind to all interfaces (accessible from network)\nclaude-code-webui --host 0.0.0.0 --port 9000\n\n# Enable debug mode\nclaude-code-webui --debug\n\n# Custom Claude CLI path (for non-standard installations or aliases)\nclaude-code-webui --claude-path /path/to/claude\n\n# Using environment variables\nPORT=9000 DEBUG=true claude-code-webui\n```\n\n---\n\n## 🚨 Troubleshooting\n\n### Claude CLI Path Detection Issues\n\nIf you encounter \"Claude Code process exited with code 1\" or similar errors, this typically indicates Claude CLI path detection failure.\n\n**Quick Solution:**\n\n```bash\nclaude-code-webui --claude-path \"$(which claude)\"\n```\n\n**Common scenarios requiring explicit path specification:**\n\n- **Node.js environment managers** (Volta, asdf, nvm, etc.)\n- **Custom installation locations**\n- **Shell aliases or wrapper scripts**\n\n**Environment-specific commands:**\n\n```bash\n# For Volta users\nclaude-code-webui --claude-path \"$(volta which claude)\"\n\n# For asdf users\nclaude-code-webui --claude-path \"$(asdf which claude)\"\n```\n\n**Native Binary Installation:**\nSupported. Script path detection may fail and show warnings, but the application will work correctly as long as the Claude executable path is valid.\n\n**Debug Mode:**\nUse `--debug` flag for detailed error information:\n\n```bash\nclaude-code-webui --debug\n```\n\n---\n\n## 🔧 Development\n\n### Setup\n\n```bash\n# Clone repository\ngit clone https://github.com/sugyan/claude-code-webui.git\ncd claude-code-webui\n\n# Install dotenvx (see prerequisites)\n\n# Start backend (choose one)\ncd backend\ndeno task dev    # Deno runtime\n# OR\nnpm run dev      # Node.js runtime\n\n# Start frontend (new terminal)\ncd frontend\nnpm run dev\n```\n\n### Port Configuration\n\nCreate `.env` file in project root:\n\n```bash\necho \"PORT=9000\" \u003e .env\n```\n\nRun with dotenvx to use the `.env` file:\n\n```bash\n# Backend\ncd backend\ndotenvx run --env-file=../.env -- deno task dev    # Deno\ndotenvx run --env-file=../.env -- npm run dev      # Node.js\n\n# Frontend (uses Vite's built-in .env support)\ncd frontend\nnpm run dev\n```\n\nAlternative: Set environment variables directly:\n\n```bash\nPORT=9000 deno task dev     # Deno\nPORT=9000 npm run dev       # Node.js\n```\n\n---\n\n## 🔒 Security Considerations\n\n**Important**: This tool executes Claude CLI locally and provides web access to it.\n\n### ✅ Safe Usage Patterns\n\n- **🏠 Local development**: Default localhost access\n- **📱 Personal network**: LAN access from your own devices\n\n### ⚠️ Security Notes\n\n- **No authentication**: Currently no built-in auth mechanism\n- **System access**: Claude can read/write files in selected projects\n- **Network exposure**: Configurable but requires careful consideration\n\n### 🛡️ Best Practices\n\n```bash\n# Local only (recommended)\nclaude-code-webui --port 8080\n\n# Network access (trusted networks only)\nclaude-code-webui --port 8080 --host 0.0.0.0\n```\n\n**Never expose to public internet without proper security measures.**\n\n---\n\n## 📚 Documentation\n\nFor comprehensive technical documentation, see [CLAUDE.md](./CLAUDE.md) which covers:\n\n- Architecture overview and design decisions\n- Detailed development setup instructions\n- API reference and message types\n\n---\n\n## ❓ FAQ\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eQ: Do I need Claude API access?\u003c/strong\u003e\u003c/summary\u003e\n\nYes, you need the Claude CLI tool installed and authenticated. The web UI is a frontend for the existing Claude CLI.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eQ: Can I use this on mobile?\u003c/strong\u003e\u003c/summary\u003e\n\nYes! The web interface is fully responsive and works great on mobile devices when connected to your local network.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eQ: Is my code safe?\u003c/strong\u003e\u003c/summary\u003e\n\nYes, everything runs locally. No data is sent to external servers except Claude's normal API calls through the CLI.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eQ: Can I deploy this to a server?\u003c/strong\u003e\u003c/summary\u003e\n\nWhile technically possible, it's designed for local use. If deploying remotely, ensure proper authentication and security measures.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eQ: How do I update?\u003c/strong\u003e\u003c/summary\u003e\n\nDownload the latest binary from releases or pull the latest code for development mode.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n\u003csummary\u003e\u003cstrong\u003eQ: What if Claude CLI isn't found or I get \"process exited with code 1\"?\u003c/strong\u003e\u003c/summary\u003e\n\nThese errors typically indicate Claude CLI path detection issues. See the [Troubleshooting](#-troubleshooting) section for detailed solutions including environment manager workarounds and debug steps.\n\n\u003c/details\u003e\n\n---\n\n## 🔗 Related Projects\n\n**Alternative Claude Code Web UIs:**\n\n- **[siteboon/claudecodeui](https://github.com/siteboon/claudecodeui)**\n  - A popular web-based Claude Code interface with mobile and remote management focus\n  - Offers additional features for project and session management\n  - Great alternative if you need more advanced remote access capabilities\n\nBoth projects aim to make Claude Code more accessible through web interfaces, each with their own strengths and approach.\n\n---\n\n## 🤝 Contributing\n\nWe welcome contributions! Please see our [development setup](#-development) and feel free to:\n\n- 🐛 Report bugs\n- ✨ Suggest features\n- 📝 Improve documentation\n- 🔧 Submit pull requests\n\n**Fun fact**: This project is almost entirely written and committed by Claude Code itself! 🤖  \nWe'd love to see pull requests from your Claude Code sessions too :)\n\n---\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) for details.\n\n---\n\n\u003cdiv align=\"center\"\u003e\n\n**Made with ❤️ for the Claude Code community**\n\n[⭐ Star this repo](https://github.com/sugyan/claude-code-webui) • [🐛 Report issues](https://github.com/sugyan/claude-code-webui/issues) • [💬 Discussions](https://github.com/sugyan/claude-code-webui/discussions)\n\n\u003c/div\u003e\n","funding_links":[],"categories":["Claude Code Ecosystem","GUIs \u0026 Web UIs","图形界面与网页界面","TypeScript"],"sub_categories":["User Interfaces \u0026 Web Apps"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsugyan%2Fclaude-code-webui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsugyan%2Fclaude-code-webui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsugyan%2Fclaude-code-webui/lists"}