Web Dashboard Interface
Relevant source files
The following files were used as context for generating this wiki page:
The CCS Web Dashboard is a React-based graphical interface designed to manage profiles, providers, and runtimes for Claude Code, Codex, and other compatible CLI tools. It serves as a visual companion to the CCS CLI, providing a unified surface for monitoring account health, configuring model providers, and managing shared resources such as agents and skills.
The interface is built with a strict design system comprising two primary body archetypes: Config (rail-anchored forms with optional JSON editors) and Monitor (KPI-driven grids for live status). It ensures environment parity by allowing users to manage configurations that are applied to native runtimes like Codex and Claude.
Sources: ui/src/pages/_styleguide.tsx:106-125, AGENTS.md:12-25, README.md:112-140
Design System and Layout Archetypes
The dashboard adheres to specific layout invariants to maintain consistency across all feature pages. These patterns dictate how identity, navigation, and content are structured within the viewport.
Layout Invariants
- Two-Column Shell: Config pages use a strict two-column shell where the left column (rail/list) owns the page identity and the right column contains main content.
- Viewport Constraints: Pages must not use
h-screenormin-h-screendirectly; instead, they rely on a shared layout contract for viewport height management. - Resizable Panes: The split between form and JSON views is user-resizable, with ratios persisted in
localStorage.
Sources: ui/src/pages/_styleguide.tsx:127-145, ui/tests/unit/ui/pages/dashboard-page-height-contract.test.ts:25-33
Identity Strip Patterns
| Pattern | Usage | Key Elements |
|---|---|---|
| HeroBar | Home/Dashboard pages | Logo, version, and up to 4 dense inline stats. |
| Rail-Anchored | Multi-entity Config pages | Identity (brand/status) lives inside the left rail; no top chrome. |
| PageHeader | Monitor-only pages | Horizontal strip below topbar for KPIs and actions; never used with ConfigLayout. |
Sources: ui/src/pages/_styleguide.tsx:110-120, ui/src/pages/_styleguide.tsx:185-218
Architectural Data Flow
The following diagram illustrates how the Dashboard interacts with the local CCS configuration and native binaries.
The dashboard uses custom hooks to fetch and patch configurations via the API server, which manages both internal CCS settings and external native tool configurations.
Sources: ui/src/pages/codex.tsx:28-40, ui/src/pages/shared.tsx:43-55, AGENTS.md:27-38
Core Feature Modules
Codex Management Center
The Codex module provides a specialized interface for managing config.toml, the upstream configuration file for the Codex CLI. It features a split-view between structured controls (Control Center) and a raw TOML editor.
- Diagnostics: Surfaces binary installation status, versioning, and path resolution (e.g.,
$CODEX_HOME). - Control Center: Provides structured UI for model providers, profiles, MCP servers, and feature flags.
- Raw Editor: A
CodeEditorbased panel for direct TOML manipulation with conflict detection based onmtime.
Sources: ui/src/pages/codex.tsx:26-90, ui/src/components/compatible-cli/codex-overview-tab.tsx:80-140
Shared Resources Interface
The Shared page manages global assets used across different runtime profiles. It uses a master-detail layout to browse and inspect local files.
- Resource Categories: Commands, Skills, Agents, Plugins, and Settings.
- Resource Policy: Displays how accounts are partitioned between "shared" and "profile-local" modes.
- Content Viewer: Includes a Markdown renderer and JSON code editor for inspecting resource definitions.
Sources: ui/src/pages/shared.tsx:25-80, ui/src/pages/shared.tsx:325-350
IDE & Extension Bindings
The Claude Extension page facilitates the binding of CCS profiles to specific IDE hosts (VS Code, Cursor, Windsurf).
This flow ensures that IDE extensions use the same environment variables and model routing as the CCS CLI by injecting managed blocks into IDE settings files.
Sources: ui/src/pages/claude-extension.tsx:238-315, ui/src/pages/claude-extension.tsx:500-550
Technical Implementation Details
Component Organization
The dashboard relies on functional React components and a variety of UI primitives.
| Component | Source File | Purpose |
|---|---|---|
ConfigLayout | ui/src/pages/_styleguide.tsx | Standard 3-pane layout for configurations. |
CodeEditor | ui/src/pages/shared.tsx | Read-only and editable JSON/TOML views. |
StatusItem | ui/src/pages/copilot.tsx | Renders connectivity/health states with Lucide icons. |
TargetStatusCard | ui/src/pages/claude-extension.tsx | Displays file existence and drift status for extension settings. |
Sources: ui/src/pages/_styleguide.tsx:244-270, ui/src/pages/claude-extension.tsx:145-175, ui/src/pages/copilot.tsx:35-65
Configuration Patching Logic
The dashboard uses a "structured patch" pattern to modify configurations without destroying manual edits in raw files. For example, in the Codex module, patchConfigAsync targets specific TOML keys while preserving comments and unsupported objects.
Sources: ui/src/pages/codex.tsx:125-148, tests/unit/web-server/codex-dashboard-service.test.ts:316-340
Conclusion
The Web Dashboard Interface acts as the central management plane for the CCS ecosystem. By bridging the gap between raw CLI configuration and visual monitoring, it enables complex model routing strategies (like weighted round-robin) and environment synchronization across multiple IDEs and AI runtimes. Its strict adherence to layout archetypes ensure that as the project grows, the management experience remains consistent and predictable for developers.
Sources: ui/src/pages/_styleguide.tsx:155-165, AGENTS.md:75-80