# Claudeck > A browser-based UI for Claude Code — chat, run workflows, manage MCP servers, track costs, and orchestrate autonomous agents from a local web interface. Installable as a PWA. - **Type:** MCP server - **Install:** `agentstack add mcp-hamed-farag-claudeck` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [hamed-farag](https://agentstack.voostack.com/s/hamed-farag) - **Installs:** 0 - **Category:** [Web & Browser](https://agentstack.voostack.com/c/web-and-browser) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [hamed-farag](https://github.com/hamed-farag) - **Source:** https://github.com/hamed-farag/claudeck - **Website:** https://claudeck.app/ ## Install ```sh agentstack add mcp-hamed-farag-claudeck ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About Claudeck A browser-based UI for Claude Code — chat, workflows, agents, cost tracking, and more. --- ## Quick Start ```bash # One-command launch (no install needed) npx claudeck # Custom port npx claudeck --port 3000 # Enable authentication (for remote access via Cloudflare Tunnel, etc.) npx claudeck --auth # Or install globally npm install -g claudeck claudeck ``` On first run, Claudeck will ask you to choose a port (default: `9009`), then open your browser to the URL shown in the terminal. The port is saved to `~/.claudeck/.env` for future runs. > Requires **Node.js 18+** and Claude Code CLI authentication (`claude auth login`). User data lives in `~/.claudeck/` (config, database, plugins) — safe for NPX upgrades. --- ## Why Claudeck? - **Zero-framework** — Vanilla JS + Web Components, 6 npm dependencies, no build step - **Full agent orchestration** — Chains, DAGs, orchestrator, and monitoring dashboard - **Persistent memory** — Cross-session project knowledge with FTS5 search and AI optimization - **Cost visibility** — Per-session tracking, daily charts, token breakdowns - **Secure remote access** — Token-based auth for Cloudflare Tunnel or reverse proxy setups - **Works everywhere** — PWA, mobile responsive, Telegram AFK approval - **Extensible** — Full-stack plugin system with auto-discovery --- ## Features ### Chat & Sessions - Real-time WebSocket streaming with session persistence - **Multi-client sync** — multiple browsers/devices viewing the same session see streamed responses in real time - **Parallel mode** — 2x2 grid of 4 independent conversations - **Message pagination** — lazy-loads older messages on scroll-up (cursor-based, 30 per page) - Background sessions that keep running when you switch away - Session search, pinning, auto-generated titles - **Session branching** — fork any conversation at an assistant message to explore alternatives - **Message recall** — press `↑` on empty input to cycle through previous messages, or click the history button to browse and re-use - Voice input via Web Speech API (Chrome/Safari) ### Autonomous Agents - 4 built-in agents: PR Reviewer, Bug Hunter, Test Writer, Refactoring - **Agent Chains** — Sequential pipelines with context passing - **Agent DAGs** — Visual dependency graph editor with parallel execution - **Orchestrator** — Describe a task, it auto-delegates to specialist agents - **Agent Monitor** — Metrics, cost aggregation, success rates, leaderboard ### Workflows - Multi-step workflows with full CRUD - 4 pre-built: Review PR, Onboard Repo, Migration Plan, Code Health - Each step carries context forward ### Code & Files - **File Explorer** — Lazy tree, syntax-highlighted preview, drag-to-chat - **File Picker** — Attach files with type dots, binary detection, search, selected chips - **Git Panel** — Branch switching, staging, commit, log, inline diff viewer - **Git Worktrees** — Run any chat/agent task in an isolated worktree; merge, diff, or discard results - **Repos Manager** — Organize repos in nested groups with GitHub links - Code diff viewer with LCS-based line highlighting ### Cost & Analytics - Per-session cost tracking with daily timeline charts - Input/output token breakdown, streaming token counter - Error pattern analysis (9 categories), tool usage stats ### Persistent Memory - Cross-session project knowledge that survives restarts - Auto-capture from assistant responses using pattern-based heuristic extraction - `/remember` command for manual memory creation - FTS5 full-text search with relevance scoring and time-decay - AI-powered optimization (consolidation via Claude Haiku) - Memory panel in right sidebar with search, filtering, and inline editing ### Notifications - **Notification Bell** — Persistent notification history with unread badge in the header - Background session events (completed, errored, input needed) logged automatically - Agent completion/error notifications with cost and duration metrics - Full history modal with type/status filters, bulk actions, and pagination - 4 read strategies: explicit click, mark all, auto-read on view, click-through to session - Real-time cross-tab sync via WebSocket broadcasts ### Skills Marketplace - **SkillsMP Integration** — Browse and install agent skills from the [SkillsMP](https://skillsmp.com/) registry - Keyword search and AI semantic search with mode toggle - Install skills globally (`~/.claude/skills/`) or per-project (`.claude/skills/`) - Enable/disable skills via toggle (renames `SKILL.md` ↔ `SKILL.md.disabled`) - Installed skills auto-register as `/` slash commands - "Skill used" system messages in chat for both user-invoked and model-invoked skills - Token-gated — enter your free SkillsMP API key to activate ### Integrations - **MCP Manager** — Add/edit/remove MCP servers (global + per-project) - **Telegram** — Rich notifications + AFK approve/deny via inline keyboard - **Push Notifications** — Web-push with audio chime, works when browser is closed ### Prompt & Command System - 16 built-in prompt templates with `{{variable}}` placeholders - Auto-discovers `.claude/commands/` and `.claude/skills/` from your project - 40+ slash commands for every feature ### Permissions | Mode | Behavior | |------|----------| | **Bypass** | Auto-approve everything | | **Confirm Writes** | Auto-approve reads, prompt for writes | | **Confirm All** | Prompt for every tool call | | **Plan Mode** | No execution, planning only | ### Security & UI - **Authentication** — `--auth` flag enables token-based auth with login page, HttpOnly cookies, and WebSocket verification. Localhost bypasses auth by default (auto-detected proxy headers like `X-Forwarded-For` disable the bypass for tunneled requests). - Dark theme (terminal CRT aesthetic) and light theme - Installable as a PWA with offline fallback - Mobile responsive with tablet/mobile breakpoints - Welcome screen with Whaly mascot and 18-step guided tour - Full-stack plugin system with marketplace UI --- ## Architecture ``` browser ──── WebSocket ──── server.js ──── Claude Code SDK | server/routes/ ~/.claudeck/ server/agent-loop.js ├── config/ (JSON configs) server/orchestrator.js ├── plugins/ (user plugins) server/dag-executor.js ├── data.db (SQLite + memories) server/notification-logger.js server/utils/git-worktree.js server/auth.js server/memory-optimizer.js └── .env (VAPID keys, auth token) db.js → db/sqlite.js (adapter pattern) plugins/ ``` | Layer | Technology | |-------|------------| | Runtime | Node.js 18+ (ESM) | | Backend | Express 4, WebSocket (ws 8), web-push 3 | | AI SDK | @anthropic-ai/claude-code | | Database | SQLite via better-sqlite3 (WAL mode), adapter pattern for multi-DB support | | Frontend | Vanilla JS ES modules + Web Components (Light DOM), CSS custom properties | | Testing | Vitest + happy-dom (2,507+ unit tests, 55% coverage) + WS perf benchmarks | | Rendering | highlight.js, Mermaid (diagrams) — CDN | --- ## Slash Commands ``` /clear /new /parallel /export /theme /shortcuts App /costs /analytics Dashboards /files /git /repos /events /mcp /tips /skills Panels /remember Memory /review-pr /onboard-repo /migration-plan /code-health Workflows /agent-pr-reviewer /agent-bug-hunter /agent-test-writer Agents /orchestrate /monitor /chain-* /dag-* Multi-Agent /code-review /find-bugs /write-tests /refactor ... Prompts (16) /run Shell ``` --- ## Keyboard Shortcuts | Shortcut | Action | |----------|--------| | `Cmd+K` | Session search | | `Cmd+N` | New session | | `Cmd+B` | Toggle right panel | | `Cmd+/` | Show all shortcuts | | `Cmd+Shift+E/G/R/V/T` | Files / Git / Repos / Events / Tips | | `Cmd+1`-`4` | Focus parallel pane | | `↑` / `↓` | Recall previous/next message (empty input) | --- ## Configuration All user data lives in `~/.claudeck/` (override with `CLAUDECK_HOME`): ``` ~/.claudeck/ ├── config/ │ ├── folders.json Projects │ ├── prompts.json Prompt templates │ ├── workflows.json Workflows │ ├── agents.json Agent definitions │ ├── agent-chains.json Sequential pipelines │ ├── agent-dags.json Dependency graphs │ ├── repos.json Repository groups │ ├── bot-prompt.json Assistant bot prompt │ ├── telegram-config.json Telegram config │ └── skillsmp-config.json Skills Marketplace config ├── plugins/ User-installed plugins ├── data.db SQLite database └── .env VAPID keys, port, auth token ``` Defaults are copied on first run. User edits are never overwritten on upgrade. See [CONFIGURATION.md](docs/CONFIGURATION.md) for the full guide. --- ## Plugins Claudeck includes 2 built-in plugins, a community marketplace, and supports user plugins via `~/.claudeck/plugins/`: | Plugin | Description | |--------|-------------| | **Claude Editor** | Edit CLAUDE.md project instructions in-app | | **Repos** | Repository management with tree view | **Community Marketplace** — browse, install, and update community plugins directly from the Plugin Marketplace tab. Plugins like Linear (moved from built-in in v1.4.2), Tasks, Event Stream, Sudoku, and Tic-Tac-Toe are available from the [marketplace](https://github.com/hamed-farag/claudeck-marketplace). **Create your own** — drop files in `~/.claudeck/plugins//` (persists across upgrades) with `client.js` and optionally `server.js`, `client.css`, `config.json`. No fork needed. See [CONFIGURATION.md](docs/CONFIGURATION.md#user-plugins) for details. **Scaffold with Claude Code** — install the plugin creator skill and let Claude build plugins for you: ```bash npx skills add https://github.com/hamed-farag/claudeck-skills # Then in Claude Code: /claudeck-plugin-create my-widget A dashboard showing system metrics ``` --- ## Documentation | Document | Description | |----------|-------------| | [DOCUMENTATION.md](docs/DOCUMENTATION.md) | Full feature docs, API reference, database schema | | [TAB-SDK.md](docs/TAB-SDK.md) | Plugin SDK reference — ctx API, events, state, CSS tokens, examples | | [CONFIGURATION.md](docs/CONFIGURATION.md) | User data directory, config files, plugin system | | [AGENT-ARCHITECTURE.md](docs/AGENT-ARCHITECTURE.md) | How agents, chains, DAGs, and orchestrator work | | [PLAN-sqlite-adapter.md](docs/PLAN-sqlite-adapter.md) | Database adapter pattern, async interface, multi-DB roadmap | | [CROSS-PLATFORM-AUDIT.md](docs/CROSS-PLATFORM-AUDIT.md) | Windows/Linux compatibility | | [COMPETITIVE-ANALYSIS.md](docs/COMPETITIVE-ANALYSIS.md) | Feature comparison with similar tools | --- ## Testing ```bash npm test # Run all 2,507+ tests npm test -- --coverage # With coverage report npm run test:perf # WebSocket performance benchmarks ``` | Layer | Tests | Coverage | |-------|-------|----------| | **components/** (Web Components) | 170+ | 100% | | **core/** | 110+ | 90% | | **ui/** | 280+ | 65% | | **features/** | 210+ | 22% | | **panels/** | 150+ | 35% | | **server/** | 1,350+ | 95% | 20 Web Components in `public/js/components/` — each is a self-contained Custom Element (Light DOM) that owns its HTML, testable with zero mocks. ### Performance Benchmarks The `test:perf` suite measures WebSocket relay performance with real TCP connections over localhost (no mocked sockets). Results from 4 scenarios: **Approval Round-Trip Latency** — server sends `permission_request` → client responds → server receives: | Concurrent Sessions | p50 | p95 | p99 | |---|---|---|---| | 1 | 70 µs | 132 µs | 196 µs | | 5 | 187 µs | 222 µs | 244 µs | | 10 | 300 µs | 466 µs | 721 µs | | 25 | 382 µs | 570 µs | 764 µs | **Message Throughput** — streaming text chunks to connected clients: | Clients | Total msg/s | |---|---| | 1 | ~295k | | 10 | ~393k | | 50 | ~435k | **Connection Scaling** — 100 simultaneous connections: p50 establish time 156 µs, ~35 KB memory per connection. **Broadcast Fan-Out** — notification delivery to all connected clients: p50 under 1 ms even at 100 clients. --- ## Contributing Contributions are welcome! Fork the repo, make your changes, and open a PR. ```bash git clone https://github.com/hamed-farag/claudeck.git cd claudeck npm install npm start npm test # Run tests before submitting ``` See [DOCUMENTATION.md](docs/DOCUMENTATION.md) for architecture details and [CONFIGURATION.md](docs/CONFIGURATION.md) for the config system. --- ## License [MIT](LICENSE) --- Built with Whaly by Hamed Farag ## Source & license This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code. - **Author:** [hamed-farag](https://github.com/hamed-farag) - **Source:** [hamed-farag/claudeck](https://github.com/hamed-farag/claudeck) - **License:** MIT - **Homepage:** https://claudeck.app/ Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** yes - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** yes - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/mcp-hamed-farag-claudeck - Seller: https://agentstack.voostack.com/s/hamed-farag - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.