ccWeb

# Tool List ## Overview Based on **Claude Agent SDK(Python) + Anthropic compatible API**, ccWeb is a multi-user web platform that provides native capabilities of Claude Code: tool execution, `canUseTool` permission gate, hooks, MCP, and subagents. The underlying model uses Anthropic compatible endpoints (the default example is Volc Engine), which does not consume Claude subscriptions and uses a shared pool model. Suitable for scenarios such as **team sharing a smart station**, **online smart programming/operation and maintenance**, and **multi-project collaboration**. ## Project Vision 1. **Reduce AI intelligent body usage threshold**: Let more people enjoy the convenience of AI intelligent bodies, without worrying about deployment difficulties and docking difficulties. 2. **Let intelligent bodies understand needs better**: Sufficient project context helps AI understand task background more accurately, thereby completing more precise development and decision-making. 3. **Make team collaboration smoother**: One-click sharing projects to other team members, and configure read and write control permissions to achieve secure collaborative work. 4. **Available anytime and anywhere**: As long as you can log in to the web, you can use your smart station on any device. ## Pain Points Solved 1. **Vibe coding background information insufficient leading to development deviation**: Current vibe coding is undertaking a large number of daily technical iteration needs, but coding agents are usually driven by technology and need to provide sufficient background descriptions to agents. When information is insufficient, agents have unclear judgments on demand and cannot develop accurately. ccWeb solves this by sharing projects, precipitating documents by position, and letting agents read complete context during implementation, significantly reducing deviations. 2. **Team project isolation and permission control difficulties**: During team collaboration and development, ccWeb supports sharing projects and controlling member read and write permissions, providing a good working environment for project isolation, personnel isolation, and shared project context. 3. **Lack of customizable online agents**: Can be used as an independent agent, creating independent projects, supporting custom system prompts, and agents can call tools, skills, and MCP servers. 4. **System-level security and controllability**: Can utilize Docker deployment, through mounting directory read and write permissions to control agent file access range from the system source, ensuring system security. 5. **External system docking complexity**: Provides rich API interfaces, simple external docking, and can achieve streaming and non-streaming capabilities, seamlessly docking with business systems. 6. **Online experience and local Claude Code gap**: ccWeb maintains almost no sense of difference with local use of Claude Code, supporting locale settings, project-level subagents, skills, etc. 7. **Lack of team-level account and usage management**: Provides team account management, day/week/month quota management, conversation records, token records, and rich usage dashboards. 8. **Context token consumption is high**: For each conversation, you can flexibly set tool call permissions, access permissions, and skill call permissions, effectively saving context token consumption, and up to 80% savings. ## Core Features - **Multi-user & permission isolation**: Administrators can create/disable users, allocate day/week/month token quotas; ordinary users can only access their own projects and sessions. - **Project-level workspace**: Each session binds a project, file operations are limited to the project directory (soft isolation), supporting file upload, directory tree, online preview, and export zip. - **Native Claude Code capabilities**: Through `ClaudeSDKClient`, supports tool calls, permission confirmation, hooks, MCP servers, and subagents. - **Online conversation**: SSE streaming output, supporting tool authorization backfill, session context continuation, and token usage real-time statistics. - **Usage dashboard**: Statistics input/output/cache/cost by user/project/model, supporting day/week/month quota restrictions. - **Agent configuration**: Can preset system prompts, permission modes, bind tools/skills, and switch model gears. - **Project-level API Token**: For external system access, does not automatically invalidate, and can control fine-grained by project. - **One-click Docker deployment**: `docker-compose up -d --build` can start PostgreSQL + ccWeb. ## Skills Management ccWeb supports **global skills list** and **project-level skills whitelist**, balancing "capability visibility" and "on-demand loading". ### Global Skills List - During service startup, the background probe runs a light session through `ClaudeSDKClient`, dynamically collecting the complete set of tools, skills, agents, and MCP servers from the SDK's `init` event, and caching it in memory. - The frontend obtains the list through `GET /api/catalog`, used for the agent configuration page's checkbox. - After installing new skills or SDK upgrades, administrators can call `POST /api/catalog/refresh` to re-collect, without restarting the service. - When dynamic collection fails, it automatically falls back to the hardcoded list in `backend/app/sdk/catalog.py`, ensuring interface availability. ### Project-level Skills Whitelist - In "Agent Configuration", select the skills to load for a certain configuration, and after saving, the configuration carries `skills_whitelist`. - After the session binds the agent configuration, `SessionRunner` only passes the whitelist skills to the SDK; other skills do not load, significantly reducing context token consumption. - During runtime, it actively cuts off SDK default setting sources (`~/.claude`), avoiding automatic loading of 40+ default skills, ensuring the whitelist takes effect strictly. - Common built-in skills include document processing (`xlsx`/`docx`/`pptx`/`pdf`), design (`frontend-design`/`canvas-design`/`theme-factory`), and development process (`superpowers:*` series), etc. ### Custom Skills - Within the project working directory, you can place `.claude/skills/{skill_name}/SKILL.md` as a project-level custom skill. - As long as the skill is added to the `skills_whitelist` of the corresponding agent configuration, the current project session can call it. ## System Screenshots > The following screenshots are all from the `docs/pic/` directory sample images, which can be previewed directly in README. ### Project Workspace  ### Project Sharing  ### Session History  ### Tool Authorization  ### Agent Configuration  ### Usage Dashboard  ### User Management and Quota  ### Function Introduction Video <video src="docs/pic/ccweb功能介绍.mp4" controls width="100%"></video> ## Architecture ``` Frontend (single-file SPA) → Application Layer (FastAPI) → Capability Layer (claude-agent-sdk) → Model Layer (Anthropic compatible API) ``` - **Frontend**: Native JS + CDN (Chart.js/marked/dompurify), no build steps, statically hosted by the backend. - **Application Layer**: FastAPI + SQLAlchemy 2.0 async + asyncpg, responsible for sessions/projects/authentication/billing/usage. - **Capability Layer**: `ClaudeSDKClient` encapsulation, blocking SDK raw types, unified `SdkEvent` externally. - **Model Layer**: Anthropic compatible API (`ANTHROPIC_BASE_URL` + `ANTHROPIC_AUTH_TOKEN`), model names all go through environment variables, code does not pass `model`. The default example uses Volc Engine endpoints. ## Quick Start (Docker Compose, recommended) ### 1. Prepare Environment ```bash git clone https://github.com/zhangyifei1/ccWeb.git cd ccWeb cp .env.example .env ``` Edit `.env`, filling in at least the following required items: | Variable | Description | |---|---| | `ANTHROPIC_AUTH_TOKEN` | Anthropic compatible API Token/Key (for session authentication) | | `BOOTSTRAP_ADMIN_PASSWORD` | Initial administrator password, **must be modified before the first startup** | | `JWT_SECRET` | JWT signature key, production environment please fill in a fixed-length random string | ### 2. Start ```bash docker-compose up -d ``` - The first build takes about 3-5 minutes (including `claude-agent-sdk`'s ~227MB bundled CLI). - ccweb will wait for PostgreSQL health check to pass before starting, and **automatically create tables** (`init_db`, no alembic). - Visit `http://<server IP>:8000`, log in with `admin` and the password you set. View logs: ```bash docker-compose logs -f ccweb ``` ### 3. Stop ```bash docker-compose down ``` Data is saved in `./pgdata` and `./workspaces`, backup these two directories. For more deployment details (external database, port modification, upgrade, troubleshooting), see [`DEPLOY.md`](DEPLOY.md). ## Local Development ```bash cd backend pip install -e ".[dev]" cd .. cp .env.example .env # Modify as needed, local DATABASE_URL defaults to localhost:5432 cd backend uvicorn app.main:app --reload --host 127.0.0.1 --port 8000 ``` The frontend has no build steps, and after the backend starts, visit http://127.0.0.1:8000/. ## Main Configuration Description `cp .env.example .env` and modify as needed. Common required items: | Variable | Default Value | Description | |---|---|---| | `ANTHROPIC_BASE_URL` | `https://ark.cn-beijing.volces.com/api/coding` | Anthropic compatible endpoint (default example is Volc Engine Beijing node) | | `ANTHROPIC_AUTH_TOKEN` | *(required)* | Anthropic compatible API Token (note is `AUTH_TOKEN`, not `API_KEY`; Volc Engine corresponds to Ark Token) | | `ANTHROPIC_MODEL` | `glm-5.2` | Main model | | `ANTHROPIC_DEFAULT_*_MODEL` | `deepseek-v4-pro` | Haiku/Sonnet/Opus gear mapping | | `BOOTSTRAP_ADMIN_USERNAME` | `admin` | Administrator account created at first startup | | `BOOTSTRAP_ADMIN_PASSWORD` | *(required)* | Administrator password created at first startup | | `JWT_SECRET` | *(recommended)* | JWT signature key, empty generates temporary key on restart | | `AUTH_REQUIRED` | `true` | `false` disables authentication (only for transition/local debugging) | | `ALLOW_REGISTRATION` | `false` | `false` prohibits free registration, administrators allocate accounts | | `DEFAULT_DAILY/WEEKLY/MONTHLY_QUOTA` | Unlimited | Newly registered user default token quota | Complete variables see `.env.example` internal Chinese comments. ## Main API All under `/api/`: | Route | Description | |---|---| | `/api/auth` | Register/login/current user | | `/api/projects` | Project CRUD + file upload/tree/preview | | `/api/projects/{id}/tokens` | Project-level API Token (for external system access) | | `/api/sessions` | Session CRUD | | `/api/sessions/{id}/chat` | SSE streaming conversation | | `/api/chat` | Unified conversation endpoint (no `session_id` automatically creates a new session) | | `/api/sessions/{id}/permission` | Tool authorization backfill | | `/api/agent-configs` | Agent configuration (tools/skills/permission mode) | | `/api/usage` | Usage dashboard | | `/api/admin` | User management (only administrators) | | `/api/catalog` | Tools/skills list | | `/api/health/credential` | Credential health (administrators) | > Frontend "Project" page click **「📖 API」** button to view complete interface documentation, top one-click copy Authorization/project ID/session ID/agent configuration ID. ## Directory Structure ``` ccWeb/ ├── backend/ │ ├── app/ │ │ ├── api/ # Route (auth/projects/sessions/chat/admin/usage/catalog/permission/health) │ │ ├── sdk/ # SDK encapsulation layer (runner/permission/hooks/path_guard/registry/events) │ │ ├── config.py # Configuration loading │ │ ├── security.py # Authentication (JWT + project token) │ │ ├── models.py # ORM model (all with user_id forward-looking design) │ │ ├── quota.py # Quota (day/week/month) │ │ └── main.py # FastAPI entry │ ├── tests/ # pytest suite │ ├── workspaces/ # Runtime user working directory (gitignore) │ └── pyproject.toml ├── frontend/ │ ├── index.html # Single-file SPA │ ├── login.html │ ├── assets/ # logo and other static resources │ ├── app/ # Modular JS │ └── styles/ # CSS ├── docker-compose.yml # One-click deployment ├── Dockerfile ├── .env.example # Environment variable template └── LICENSE # Open-source agreement ``` ## Key Design - **Model controlled by environment variables**: Code does not pass `model`, SDK subprocess injects `ANTHROPIC_*` environment variables. Consistent with front-end claude-web configuration. - **Capability layer uses `ClaudeSDKClient`**: Supports `can_use_tool` permission gate, hooks, MCP, and subagents interaction; `query()` one-time function only suitable for no-interaction scenarios. - **Soft isolation (project mode)**: Conversation must bind project, working directory `{WORKSPACE_ROOT}/{user_id}/{project_id}/`. File tool path resolve and verify out-of-bounds hard deny; Bash dangerous commands go through authorization gate. **Not process-level isolation**, designed for internal trusted teams; if you need higher isolation, evaluate M3 containerization solution. - **Table structure designed with `user_id` forward-looking**: All tables with `user_id`, M1 single-user placeholder, M3 connects user system without changing tables. - **Billing is application-layer ledger**: Intercepts SDK `usage`/`model_usage` events to calculate user bills + quota limits, not pursuing exact token alignment with underlying cost. ## Security Tips - Production environment must set `AUTH_REQUIRED` to `true`, `ALLOW_REGISTRATION` to `false`, and fill in strong `JWT_SECRET`. - `BOOTSTRAP_ADMIN_PASSWORD` only takes effect when creating admin at first startup, please modify to strong password before deployment. - `.env` contains sensitive information, added to `.gitignore`, please do not submit to the repository. - Current is **soft isolation**, suitable for trusted team internal use; do not directly expose to untrusted public users. ## License ccWeb adopts **modified Apache License 2.0 based on Dify**, core additional terms: - Can be used for free commercial use; but **multi-tenant SaaS service** needs to obtain commercial authorization from the original author. - When using ccWeb frontend (`frontend/` directory or Docker image frontend static resources), **do not remove or modify LOGO and copyright information**. - Contributors agree that the author can adjust the open-source agreement, and contributed code can be used for commercial purposes. Complete agreement see [`LICENSE`](LICENSE). > Note: The agreement contains custom commercial restriction terms, not OSI-certified pure open-source license; if you have SaaS/multi-tenant commercialization needs, please contact us to obtain authorization. ## Acknowledgments - [Claude Agent SDK](https://github.com/anthropics/claude-code-sdk) —— Capability layer core - [Volc Engine](https://www.volcengine.com/) —— Default model access example