dc5d73936a
GET /api/projects used to scan ~/.claude/projects/ on every request, derive each project's identity from the encoded folder name, and re-parse JSONL files to build session lists. Using the folder-derived name as the project identifier leaked the Claude CLI's on-disk encoding into every API route, forced every downstream endpoint to re-resolve a real path via JSONL 'cwd' inspection, and made the project list endpoint O(projects x sessions) on disk I/O. This change switches the entire API surface to identify projects by the stable primary key from the 'projects' table and drives the listing straight from the DB: - Add projectsDb.getProjectPathById as the canonical projectId -> path resolver so routes no longer need to touch the filesystem to figure out where a project lives. - Rewrite getProjects so it reads the project list from the 'projects' table and the per-project session list from the 'sessions' table (one SELECT per project). No filesystem scanning happens for this endpoint anymore, which removes the dependency on ~/.claude/projects existing, on Cursor's MD5-hashed chat folders being discoverable, and on Codex's JSONL history being on disk. Per the migration spec each session now exposes 'summary' sourced from sessions.custom_name, 'messageCount' = 0 (message counting is not implemented), and sessionMeta.hasMore is pinned to false since this endpoint doesn't drive session pagination. - Introduce id-based wrappers (getSessionsById, renameProjectById, deleteSessionById, deleteProjectById, getProjectTaskMasterById) so every caller can pass projectId and resolve the real path through the DB. renameProjectById also writes to projects.custom_project_name so the DB-driven getProjects response reflects renames immediately; it keeps project-config.json in sync for any legacy reader that still consults the JSON file. - Migrate every /api/projects/:projectName route in server/index.js, server/routes/taskmaster.js, and server/routes/messages.js to :projectId, and change server/routes/git.js so the 'project' query/body parameter carries a projectId that is resolved through the DB before any git command runs. TaskMaster WebSocket broadcasts emit 'projectId' for the same reason so the frontend can match notifications against its current selection without another lookup. - Delete helpers that existed only to feed the old getProjects path (getCursorSessions, getGeminiCliSessions, getProjectTaskMaster) along with their unused imports (better-sqlite3's Database, applyCustomSessionNames). The legacy folder-name helpers (getSessions, renameProject, deleteSession, deleteProject, extractProjectDirectory) are kept as internal implementation details of the id-based wrappers and of destructive cleanup / conversation search, but they are no longer re-exported. - searchConversations still walks JSONL to produce match snippets (that data doesn't live in the DB), but it now includes the resolved projectId in each result so the sidebar can cross-reference hits with its already loaded project list without a second round-trip. Frontend migration: - Project.name is replaced by Project.projectId in src/types/app.ts, and ProjectSession.__projectName becomes __projectId so session tagging and sidebar state keys stay aligned with the backend identifier. Settings continues to use SettingsProject.name for legacy consumers, but it is populated from projectId by normalizeProjectForSettings. - All places that previously indexed per-project state by project.name (sidebar expanded/starred/loading/deletingProjects sets, additionalSessions map, projectHasMoreOverrides, starredProjects localStorage, command history and draft-input localStorage, TaskMaster caches) now key on projectId so state survives display-name edits and is consistent across the app. - src/utils/api.js renames every endpoint parameter to projectId, the unified messages endpoint takes projectId in its query string, and useSessionStore forwards projectId on fetchFromServer / fetchMore / refreshFromServer. Git panel, file tree, code editor, PRD editor, plugins context, MCP server flows and TaskMaster hooks are all updated to pass projectId. - DEFAULT_PROJECT_FOR_EMPTY_SHELL is updated to carry a 'default' projectId sentinel so the empty-shell placeholder still satisfies the Project contract. Bug fix bundled in: - sessionsDb.setName no longer bumps updated_at when a row already exists. Renaming is a label change, not activity, so there is no reason for it to reset 'last activity' in the sidebar. It also no longer relies on SQLite's CURRENT_TIMESTAMP, which stores a naive 'YYYY-MM-DD HH:MM:SS' value that JavaScript parses as local time and caused renamed sessions to appear shifted backwards by the client's UTC offset. When an INSERT actually happens it now writes ISO-8601 UTC with a 'Z' suffix. - buildSessionsByProviderFromDb normalizes any legacy naive timestamps in the sessions table to ISO-8601 UTC on the way out so rows written before this change also render correctly on the client. Other cleanup: - Removed the filesystem-first project-discovery comment block at the top of server/projects.js and replaced it with a short note that describes the new DB-driven flow and lists the few remaining filesystem-dependent helpers (message reads, search, destructive delete, manual project registration). - server/modules/providers/index.ts is added as a small barrel so the providers module exposes a stable public surface. Made-with: Cursor
Cloud CLI (aka Claude Code UI)
A desktop and mobile UI for Claude Code, Cursor CLI, Codex, and Gemini-CLI.
Use it locally or remotely to view your active projects and sessions from everywhere.
CloudCLI Cloud · Documentation · Discord · Bug Reports · Contributing
Screenshots
Desktop View
Main interface showing project overview and chat |
Mobile Experience
Responsive mobile design with touch navigation |
CLI Selection
Select between Claude Code, Gemini, Cursor CLI and Codex |
|
Features
- Responsive Design - Works seamlessly across desktop, tablet, and mobile so you can also use Agents from mobile
- Interactive Chat Interface - Built-in chat interface for seamless communication with the Agents
- Integrated Shell Terminal - Direct access to the Agents CLI through built-in shell functionality
- File Explorer - Interactive file tree with syntax highlighting and live editing
- Git Explorer - View, stage and commit your changes. You can also switch branches
- Session Management - Resume conversations, manage multiple sessions, and track history
- Plugin System - Extend CloudCLI with custom plugins — add new tabs, backend services, and integrations. Build your own →
- TaskMaster AI Integration (Optional) - Advanced project management with AI-powered task planning, PRD parsing, and workflow automation
- Model Compatibility - Works with Claude, GPT, and Gemini model families (see
shared/modelConstants.jsfor the full list of supported models)
Quick Start
CloudCLI Cloud (Recommended)
The fastest way to get started — no local setup required. Get a fully managed, containerized development environment accessible from the web, mobile app, API, or your favorite IDE.
Get started with CloudCLI Cloud
Self-Hosted (Open source)
npm
Try CloudCLI UI instantly with npx (requires Node.js v22+):
npx @cloudcli-ai/cloudcli
Or install globally for regular use:
npm install -g @cloudcli-ai/cloudcli
cloudcli
Open http://localhost:3001 — all your existing sessions are discovered automatically.
Visit the documentation → for full configuration options, PM2, remote server setup and more.
Docker Sandboxes (Experimental)
Run agents in isolated sandboxes with hypervisor-level isolation. Starts Claude Code by default. Requires the sbx CLI.
npx @cloudcli-ai/cloudcli@latest sandbox ~/my-project
Supports Claude Code, Codex, and Gemini CLI. See the sandbox docs for setup and advanced options.
Which option is right for you?
CloudCLI UI is the open source UI layer that powers CloudCLI Cloud. You can self-host it on your own machine, run it in a Docker sandbox for isolation, or use CloudCLI Cloud for a fully managed environment.
| Self-Hosted (npm) | Self-Hosted (Docker Sandbox) (Experimental) | CloudCLI Cloud | |
|---|---|---|---|
| Best for | Local agent sessions on your own machine | Isolated agents with web/mobile IDE | Teams who want agents in the cloud |
| How you access it | Browser via [yourip]:port |
Browser via localhost:port |
Browser, any IDE, REST API, n8n |
| Setup | npx @cloudcli-ai/cloudcli |
npx @cloudcli-ai/cloudcli@latest sandbox ~/project |
No setup required |
| Isolation | Runs on your host | Hypervisor-level sandbox (microVM) | Full cloud isolation |
| Machine needs to stay on | Yes | Yes | No |
| Mobile access | Any browser on your network | Any browser on your network | Any device, native app coming |
| Agents supported | Claude Code, Cursor CLI, Codex, Gemini CLI | Claude Code, Codex, Gemini CLI | Claude Code, Cursor CLI, Codex, Gemini CLI |
| File explorer and Git | Yes | Yes | Yes |
| MCP configuration | Synced with ~/.claude |
Managed via UI | Managed via UI |
| REST API | Yes | Yes | Yes |
| Team sharing | No | No | Yes |
| Platform cost | Free, open source | Free, open source | Starts at $7/month |
All options use your own AI subscriptions (Claude, Cursor, etc.) — CloudCLI provides the environment, not the AI.
Security & Tools Configuration
🔒 Important Notice: All Claude Code tools are disabled by default. This prevents potentially harmful operations from running automatically.
Enabling Tools
To use Claude Code's full functionality, you'll need to manually enable tools:
- Open Tools Settings - Click the gear icon in the sidebar
- Enable Selectively - Turn on only the tools you need
- Apply Settings - Your preferences are saved locally
Tools Settings interface - enable only what you need
Recommended approach: Start with basic tools enabled and add more as needed. You can always adjust these settings later.
Plugins
CloudCLI has a plugin system that lets you add custom tabs with their own frontend UI and optional Node.js backend. Install plugins from git repos directly in Settings > Plugins, or build your own.
Available Plugins
| Plugin | Description |
|---|---|
| Project Stats | Shows file counts, lines of code, file-type breakdown, largest files, and recently modified files for your current project |
| Web Terminal | Full xterm.js terminal with multi-tab support |
Build Your Own
Plugin Starter Template → — fork this repo to create your own plugin. It includes a working example with frontend rendering, live context updates, and RPC communication to a backend server.
Plugin Documentation → — full guide to the plugin API, manifest format, security model, and more.
FAQ
How is this different from Claude Code Remote Control?
Claude Code Remote Control lets you send messages to a session already running in your local terminal. Your machine has to stay on, your terminal has to stay open, and sessions time out after roughly 10 minutes without a network connection.
CloudCLI UI and CloudCLI Cloud extend Claude Code rather than sit alongside it — your MCP servers, permissions, settings, and sessions are the exact same ones Claude Code uses natively. Nothing is duplicated or managed separately.
Here's what that means in practice:
- All your sessions, not just one — CloudCLI UI auto-discovers every session from your
~/.claudefolder. Remote Control only exposes the single active session to make it available in the Claude mobile app. - Your settings are your settings — MCP servers, tool permissions, and project config you change in CloudCLI UI are written directly to your Claude Code config and take effect immediately, and vice versa.
- Works with more agents — Claude Code, Cursor CLI, Codex, and Gemini CLI, not just Claude Code.
- Full UI, not just a chat window — file explorer, Git integration, MCP management, and a shell terminal are all built in.
- CloudCLI Cloud runs in the cloud — close your laptop, the agent keeps running. No terminal to babysit, no machine to keep awake.
Do I need to pay for an AI subscription separately?
Yes. CloudCLI provides the environment, not the AI. You bring your own Claude, Cursor, Codex, or Gemini subscription. CloudCLI Cloud starts at $7/month for the hosted environment on top of that.
Can I use CloudCLI UI on my phone?
Yes. For self-hosted, run the server on your machine and open [yourip]:port in any browser on your network. For CloudCLI Cloud, open it from any device — no VPN, no port forwarding, no setup. A native app is also in the works.
Will changes I make in the UI affect my local Claude Code setup?
Yes, for self-hosted. CloudCLI UI reads from and writes to the same ~/.claude config that Claude Code uses natively. MCP servers you add via the UI show up in Claude Code immediately and vice versa.
Community & Support
- Documentation — installation, configuration, features, and troubleshooting
- Discord — get help and connect with other users
- GitHub Issues — bug reports and feature requests
- Contributing Guide — how to contribute to the project
License
GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later) — see LICENSE for the full text, including additional terms under Section 7.
This project is open source and free to use, modify, and distribute under the AGPL-3.0-or-later license. If you modify this software and run it as a network service, you must make your modified source code available to users of that service.
CloudCLI UI - (https://cloudcli.ai).
Acknowledgments
Built With
- Claude Code - Anthropic's official CLI
- Cursor CLI - Cursor's official CLI
- Codex - OpenAI Codex
- Gemini-CLI - Google Gemini CLI
- React - User interface library
- Vite - Fast build tool and dev server
- Tailwind CSS - Utility-first CSS framework
- CodeMirror - Advanced code editor
- TaskMaster AI (Optional) - AI-powered project management and task planning