ccs/docs/codebase-summary.md

CCS Codebase Summary

Last Updated: 2026-03-28

Comprehensive overview of the modularized CCS codebase structure following the Phase 9 modularization effort (Settings, Analytics, Auth Monitor splits + Test Infrastructure), v7.1 Remote CLIProxy feature, v7.2 Kiro + GitHub Copilot (ghcp) OAuth providers, v7.14 Hybrid Quota Management, v7.34 Image Analysis Hook, account-context validation hardening, Official Claude Channels runtime support, and native Codex runtime target support.

Repository Structure

ccs/
├── src/                      # CLI TypeScript source
├── dist/                     # Compiled JavaScript (npm package)
├── lib/                      # Native shell scripts (bash, PowerShell)
├── ui/                       # React dashboard application
│   ├── src/                  # UI source code
│   └── dist/                 # Built UI bundle
├── docker/                   # Docker deployment configuration
│   ├── Dockerfile            # Multi-stage build (bun 1.2.21, node:20-bookworm-slim)
│   ├── docker-compose.yml    # Compose setup with resource limits, healthcheck
│   ├── entrypoint.sh         # Entrypoint with privilege dropping, usage help
│   └── README.md             # Docker deployment guide
├── tests/                    # Test suites
├── docs/                     # Documentation
└── assets/                   # Static assets (logos, screenshots)

---

CLI Source (src/)

The main CLI is organized into domain-specific modules with barrel exports.

Directory Structure

src/
├── ccs.ts                    # Main entry point & profile execution flow
├── bin/                      # Dedicated runtime entrypoints
│   ├── droid-runtime.ts      # Forces droid target for ccs-droid / ccsd package bins
│   ├── codex-runtime.ts      # Forces codex target for ccs-codex / ccsx package bins
│   └── ccsxp-runtime.ts      # Forces built-in codex profile + codex target for ccsxp
├── types/                    # TypeScript type definitions
│   ├── index.ts              # Barrel export (aggregates all types)
│   ├── cli.ts                # CLI types (ParsedArgs, ExitCode)
│   ├── config.ts             # Config types (Settings, EnvVars)
│   ├── delegation.ts         # Delegation types (sessions, events)
│   ├── glmt.ts               # Legacy transformer types (messages, transforms)
│   └── utils.ts              # Utility types (ErrorCode, LogLevel)
│
├── commands/                 # CLI command handlers
│   ├── api-command/          # API profile subcommands (split facade + handlers)
│   │   ├── index.ts          # API command facade/router
│   │   ├── shared.ts         # Shared API arg parsing helpers
│   │   └── [subcommand files...]
│   ├── cliproxy-command.ts   # CLIProxy subcommand handling
│   ├── config-command.ts     # Config management commands
│   ├── config-image-analysis-command.ts  # First-class ImageAnalysis config (NEW v7.34)
│   ├── named-command-router.ts  # Reusable named-command dispatcher
│   ├── doctor-command.ts     # Health diagnostics
│   ├── env-command.ts        # Export shell env vars for third-party tools (v7.39)
│   ├── help-command.ts       # Help text generation
│   ├── install-command.ts    # Install/uninstall logic
│   ├── root-command-router.ts  # Extracted top-level command dispatch from ccs.ts
│   ├── shell-completion-command.ts
│   ├── sync-command.ts       # Symlink synchronization
│   ├── update-command.ts     # Self-update logic
│   └── version-command.ts    # Version display
│
├── targets/                  # Multi-target adapter system (NEW)
│   ├── index.ts              # Barrel export
│   ├── target-adapter.ts     # TargetAdapter interface contract
│   ├── target-registry.ts    # Registry for runtime adapter lookup
│   ├── target-resolver.ts    # Resolution logic (flag > runtime entrypoint / argv[0] > config)
│   ├── target-metadata.ts    # Runtime vs persisted target metadata and alias lists
│   ├── target-runtime-compatibility.ts # Guardrails for target/profile combinations
│   ├── claude-adapter.ts     # Claude Code CLI implementation
│   ├── droid-adapter.ts      # Factory Droid CLI implementation
│   ├── codex-adapter.ts      # Native Codex CLI implementation
│   ├── codex-detector.ts     # Codex binary detection and capability probing
│   ├── droid-detector.ts     # Droid binary detection & version checks
│   └── droid-config-manager.ts  # ~/.factory/settings.json management
│
├── auth/                     # Authentication module
│   ├── index.ts              # Barrel export
│   ├── commands/             # Auth-specific CLI commands
│   │   └── index.ts
│   ├── account-switcher.ts   # Account switching logic
│   └── profile-detector.ts   # Profile detection (474 lines)
│
├── config/                   # Configuration management
│   ├── index.ts              # Barrel export
│   ├── unified-config-loader.ts  # Central config loader (546 lines)
│   └── migration-manager.ts  # Config migration logic
│
├── channels/                 # Official Claude channel integration
│   ├── official-channels-runtime.ts  # Runtime gating, plugin specs, setup guidance
│   └── official-channels-store.ts    # Claude channel token/env storage helpers
│
├── cliproxy/                 # CLIProxyAPI integration (heavily modularized)
│   ├── index.ts              # Barrel export (137 lines, extensive)
│   ├── auth/                 # OAuth handlers, token management
│   │   └── index.ts
│   ├── binary/               # Binary management
│   │   └── index.ts
│   ├── services/             # Service layer
│   │   └── index.ts
│   ├── cliproxy-executor.ts  # Main executor (666 lines)
│   ├── config-generator.ts   # Config file generation (531 lines)
│   ├── account-manager.ts    # Account management (509 lines)
│   ├── quota-manager.ts      # Hybrid quota management (NEW v7.14)
│   ├── quota-fetcher.ts      # Provider quota API integration (NEW v7.14)
│   ├── platform-detector.ts  # OS/arch detection
│   ├── binary-manager.ts     # Binary download/update
│   ├── auth-handler.ts       # Authentication handling
│   ├── model-catalog.ts      # Provider model definitions
│   ├── model-config.ts       # Model configuration
│   ├── codex-plan-compatibility.ts  # Codex free/paid model fallback guardrails
│   ├── service-manager.ts    # Background service
│   ├── proxy-detector.ts     # Running proxy detection
│   ├── startup-lock.ts       # Race condition prevention
│   ├── remote-proxy-client.ts    # Remote proxy health checks (v7.1)
│   ├── proxy-config-resolver.ts  # CLI/env/config merging (v7.1)
│   ├── types.ts              # ResolvedProxyConfig for local/remote modes
│   └── [more files...]
│
├── copilot/                  # GitHub Copilot integration
│   ├── index.ts              # Barrel export
│   └── copilot-package-manager.ts  # Package management (515 lines)
│
├── glmt/                     # Legacy transformer internals kept for compatibility
│   ├── index.ts              # Barrel export
│   ├── pipeline/             # Processing pipeline
│   │   └── index.ts
│   ├── glmt-proxy.ts         # Legacy proxy runtime kept for internal compatibility
│   └── delta-accumulator.ts  # Delta processing (484 lines)
│
├── delegation/               # Task delegation & headless execution
│   ├── index.ts              # Barrel export
│   ├── executor/             # Execution engine
│   └── [delegation files...]
│
├── errors/                   # Centralized error handling
│   ├── index.ts              # Barrel export
│   ├── error-handler.ts      # Main error handler
│   ├── exit-codes.ts         # Exit code definitions
│   └── cleanup.ts            # Cleanup logic
│
├── management/               # Doctor diagnostics
│   ├── index.ts              # Barrel export
│   ├── checks/               # Diagnostic checks
│   │   ├── index.ts
│   │   └── image-analysis-check.ts  # ImageAnalysis runtime validation (NEW v7.34)
│   └── repair/               # Auto-repair logic
│       └── index.ts
│
├── api/                      # API utilities & services
│   ├── index.ts              # Barrel export
│   └── services/             # API services
│       ├── index.ts
│       ├── profile-reader.ts
│       └── profile-writer.ts
│
├── utils/                    # Utilities (modularized into subdirs)
│   ├── index.ts              # Barrel export
│   ├── ui/                   # Terminal UI utilities
│   │   ├── index.ts
│   │   ├── boxes.ts          # Box drawing
│   │   ├── colors.ts         # Terminal colors
│   │   └── spinners.ts       # Progress spinners
│   ├── websearch/            # Search tool integrations
│   │   └── index.ts
│   ├── hooks/                # Claude Code compatibility hooks (NEW v7.34)
│   │   ├── index.ts
│   │   ├── image-analyzer-hook-installer.ts
│   │   ├── image-analyzer-hook-configuration.ts
│   │   ├── image-analyzer-profile-hook-injector.ts
│   │   └── get-image-analysis-hook-env.ts
│   ├── image-analysis/       # ImageAnalysis MCP/runtime utilities (NEW v7.34)
│   │   ├── index.ts
│   │   ├── hook-installer.ts
│   │   ├── mcp-installer.ts
│   │   └── claude-tool-args.ts
│   └── [utility files...]
│
└── web-server/               # Express web server (heavily modularized)
    ├── index.ts              # Server entry & barrel export
    ├── routes/               # 15+ route handlers
    │   ├── index.ts
    │   ├── accounts-route.ts
    │   ├── auth-route.ts
    │   ├── channels-routes.ts
    │   ├── cliproxy-route.ts
    │   ├── copilot-route.ts
    │   ├── doctor-route.ts
    │   ├── glmt-route.ts
    │   ├── health-route.ts
    │   ├── profiles-route.ts
    │   └── [more routes...]
    ├── health/               # Health check system
    │   └── index.ts
    ├── usage/                # Usage analytics module
    │   ├── index.ts
    │   ├── handlers.ts       # Request handlers (633 lines)
    │   ├── aggregator.ts     # Data aggregation (538 lines)
    │   └── data-aggregator.ts
    ├── services/             # Shared services
    │   └── index.ts
    └── model-pricing.ts      # Model cost definitions (676 lines)

Module Categories

Category	Directories	Purpose
Core	commands/, errors/	CLI commands, error handling
Targets	bin/, targets/	Multi-CLI adapter pattern (Claude Code, Factory Droid, Codex CLI, extensible)
Auth	auth/, cliproxy/auth/	Authentication across providers
Config	config/, types/	Configuration & type definitions
Providers	cliproxy/, copilot/, glmt/	Provider integrations plus retained legacy transformer internals
Quota	cliproxy/quota-*.ts, account-manager.ts	Hybrid quota management (v7.14)
Remote Proxy	cliproxy/remote-*.ts, proxy-config-resolver.ts	Remote CLIProxy support (v7.1)
Image Analysis	utils/image-analysis/, utils/hooks/	Vision model proxying (v7.34)
Services	web-server/, api/	HTTP server, API services
Utilities	utils/, management/	Helpers, diagnostics

Account Context Metadata Flow

• Source fields: accounts.<name>.context_mode, accounts.<name>.context_group, accounts.<name>.continuity_mode in ~/.ccs/config.yaml.
• Runtime policy resolver: src/auth/account-context.ts.
• Metadata storage normalization: src/auth/profile-registry.ts.
• API write validation: PUT /api/config in src/web-server/routes/config-routes.ts.
• Rules:
  • mode is isolation-first (isolated default, shared opt-in)
  • shared mode requires non-empty valid context_group
  • shared mode continuity depth is standard by default, optional deeper
  • context_group is normalized (trim + lowercase + whitespace collapse to -)
  • API route rejects context_group/continuity_mode when mode is not shared
  • registry normalization drops malformed persisted context_group values

Shared Plugin Layout

• Shared payload owner: src/management/shared-manager.ts.
• Profile entry point: src/management/instance-manager.ts.
• plugins/marketplaces/, plugins/cache/, and installed_plugins.json stay shared through the ~/.ccs/shared/ topology.
• known_marketplaces.json is now instance-local under ~/.ccs/instances/<profile>/plugins/ so Claude Code validates installLocation against the active CLAUDE_CONFIG_DIR instead of a last-writer-wins shared file.

Official Claude Channels

• Runtime contract lives in src/channels/official-channels-runtime.ts and is consumed from src/ccs.ts, src/commands/config-channels-command.ts, and src/web-server/routes/channels-routes.ts.
• Canonical config lives under channels.* in ~/.ccs/config.yaml; legacy discord_channels.* remains read-compatible only when canonical fields are absent.

Native Codex Runtime Target

• Dedicated runtime entrypoints: ccs-codex and ccsx resolve through src/bin/codex-runtime.ts, while ccsxp resolves through src/bin/ccsxp-runtime.ts; all three set CCS_INTERNAL_ENTRY_TARGET=codex before delegating to src/targets/target-resolver.ts.
• Provider shortcut behavior: ccsxp also strips user-supplied --target overrides and rewrites argv to ccs codex --target codex ..., so it always lands on the built-in Codex-via-CLIProxy route.
• argv[0] alias mapping still exists in src/targets/target-resolver.ts for same-binary/custom alias scenarios, but the built-in npm bins above do not depend on that map at runtime.
• Metadata boundary: src/targets/target-metadata.ts keeps Codex runtime-only in v1, so persisted default targets remain claude | droid.
• Compatibility guardrails: src/targets/target-runtime-compatibility.ts centralizes which profile types can execute on Codex.
• Adapter behavior: src/targets/codex-adapter.ts and src/targets/codex-detector.ts launch native Codex without rewriting ~/.codex/config.toml; CCS-backed routes use transient codex -c key=value overrides and env-key injection.
• Dashboard control center: src/web-server/services/codex-dashboard-service.ts, src/web-server/routes/codex-routes.ts, ui/src/pages/codex.tsx, and ui/src/components/compatible-cli/codex-*.tsx expose a split-view Codex dashboard with guided editors for top-level settings, trust, profiles, providers, MCP servers, and feature flags plus a raw TOML fallback.
• Structured-edit boundary: guided Codex saves intentionally reserialize the whole TOML document, so comments/formatting are normalized and the raw editor remains the fidelity-preserving escape hatch.
• Follow-up behavior: structured saves refresh the raw snapshot immediately, refresh discards stale raw drafts, structured controls stay disabled while raw TOML is dirty/invalid/unreadable, project trust paths must be absolute or ~/..., unsupported upstream top-level shapes are preserved instead of deleted, and feature flags can be reset to default.
• Supported Codex flows in v1:
  • default
  • CLIProxy provider codex
  • settings/API profiles only when they resolve to a Codex CLIProxy bridge
• Telegram and Discord bot tokens are intentionally written into Claude-managed machine state under ~/.claude/channels/<channel>/.env, unless the official *_STATE_DIR environment override redirects that channel elsewhere.
• iMessage is tokenless, macOS-only, and still depends on Claude-side plugin install plus OS permissions.
• Auto-enable is gated on Bun availability, verified Claude Code v2.1.80+, verified claude.ai auth, native Claude default/account sessions, and per-channel setup readiness.
• The dashboard channels section surfaces Bun/version/auth/state-scope status from /api/channels, preserves token drafts when save-follow-up refresh fails, and keeps unsupported selected iMessage visible only so it can be turned off.

Target Adapter Module

The targets module provides an extensible interface for dispatching profiles to different CLI implementations.

Key components:

1. TargetAdapter Interface - Contract that each CLI implementation must fulfill:

   • binary detection
   • credential preparation
   • target-specific args/env construction
   • process execution
   • profile compatibility checks

2. Target Resolution - Priority order:

   • --target <cli> flag (CLI argument)
   • Explicit runtime entrypoint via CCS_INTERNAL_ENTRY_TARGET (used by src/bin/droid-runtime.ts, src/bin/codex-runtime.ts, and src/bin/ccsxp-runtime.ts)
   • argv[0] detection for custom/same-binary runtime aliases
   • Per-profile target field (from config.yaml)
   • Default: claude

3. Implementations:

   • ClaudeAdapter - Wraps existing behavior; delivers credentials via environment variables
   • DroidAdapter - New; writes to ~/.factory/settings.json and spawns with -m custom:ccs-<profile> flag

4. Registry - Map-based lookup (O(1)) for registered adapters at runtime

Usage flow:

Profile resolution (existing)
  ↓
Target resolution (via resolver.ts)
  ↓
Get adapter from registry
  ↓
Prepare credentials (adapter.prepareCredentials)
  ↓
Build args & env (adapter.buildArgs, buildEnv)
  ↓
Spawn target CLI (adapter.exec)

---

UI Source (ui/src/)

The React dashboard organized by domain with barrel exports at every level.

Directory Structure

ui/src/
├── components/
│   ├── index.ts              # Main barrel (aggregates all domains)
│   │
│   ├── account/              # Account management
│   │   ├── index.ts          # Barrel export
│   │   ├── accounts-table.tsx
│   │   ├── add-account-dialog.tsx
│   │   └── flow-viz/         # Flow visualization (split from 1,144-line file)
│   │       ├── index.tsx     # Main component (200 lines)
│   │       ├── account-card.tsx
│   │       ├── account-card-stats.tsx
│   │       ├── connection-timeline.tsx
│   │       ├── flow-paths.tsx
│   │       ├── flow-viz-header.tsx
│   │       ├── provider-card.tsx
│   │       ├── hooks.ts
│   │       ├── types.ts
│   │       ├── utils.ts
│   │       ├── path-utils.ts
│   │       └── zone-utils.ts
│   │
│   ├── analytics/            # Usage charts, stats cards
│   │   ├── index.ts
│   │   ├── cliproxy-stats-card.tsx
│   │   └── usage-trend-chart.tsx
│   │
│   ├── cliproxy/             # CLIProxy configuration
│   │   ├── index.ts          # Barrel export (30 lines)
│   │   ├── provider-editor/  # Split from 921-line file
│   │   │   ├── index.tsx     # Main editor (250 lines)
│   │   │   └── [13 focused modules]
│   │   ├── config/           # YAML editor, file tree
│   │   │   ├── config-split-view.tsx
│   │   │   ├── diff-dialog.tsx
│   │   │   ├── file-tree.tsx
│   │   │   └── yaml-editor.tsx
│   │   ├── overview/         # Health lists, preferences
│   │   │   ├── credential-health-list.tsx
│   │   │   ├── model-preferences-grid.tsx
│   │   │   └── quick-stats-row.tsx
│   │   └── [7 top-level component files]
│   │
│   ├── copilot/              # Copilot settings
│   │   ├── index.ts
│   │   └── config-form/      # Split from 846-line file
│   │       └── [13 focused modules]
│   │
│   ├── health/               # System health gauges
│   │   └── index.ts
│   │
│   ├── layout/               # App structure
│   │   ├── index.ts
│   │   ├── sidebar.tsx
│   │   └── footer.tsx
│   │
│   ├── monitoring/           # Error logs, auth monitor
│   │   ├── index.ts
│   │   ├── proxy-status-widget.tsx
│   │   ├── auth-monitor/     # Split from 465-line file (8 files)
│   │   │   ├── index.tsx     # Main component
│   │   │   ├── types.ts
│   │   │   ├── hooks.ts
│   │   │   ├── utils.ts
│   │   │   └── components/
│   │   │       ├── live-pulse.tsx
│   │   │       ├── inline-stats-badge.tsx
│   │   │       ├── provider-card.tsx
│   │   │       └── summary-card.tsx
│   │   └── error-logs/       # Split from 617-line file
│   │       └── [6 focused modules]
│   │
│   ├── profiles/             # Profile management
│   │   ├── index.ts
│   │   ├── profile-dialog.tsx
│   │   ├── profile-create-dialog.tsx
│   │   └── editor/           # Split from 531-line file
│   │       └── [10 focused modules]
│   │
│   ├── setup/                # Quick setup wizard
│   │   ├── index.ts
│   │   └── wizard/           # Step-based wizard
│   │       ├── index.tsx
│   │       └── steps/
│   │
│   ├── shared/               # Reusable components (19 components)
│   │   ├── index.ts
│   │   ├── ccs-logo.tsx
│   │   ├── code-editor.tsx
│   │   ├── confirm-dialog.tsx
│   │   ├── provider-icon.tsx
│   │   ├── settings-dialog.tsx
│   │   ├── stat-card.tsx
│   │   └── [13 more shared components]
│   │
│   └── ui/                   # shadcn/ui primitives
│       ├── button.tsx
│       ├── card.tsx
│       ├── dialog.tsx
│       ├── searchable-select.tsx  # Shared searchable combobox for model pickers
│       ├── sidebar.tsx       # Custom sidebar (674 lines)
│       └── [UI primitives...]
│
├── contexts/                 # React Contexts
│   ├── privacy-context.tsx
│   ├── theme-context.tsx
│   └── websocket-context.tsx
│
├── hooks/                    # Custom hooks (domain-prefixed)
│   ├── use-accounts.ts
│   ├── use-cliproxy.ts
│   ├── use-health.ts
│   ├── use-profiles.ts
│   ├── use-websocket.ts
│   └── [more hooks...]
│
├── lib/                      # Utilities
│   ├── api.ts                # API client
│   ├── model-catalogs.ts     # Model definitions
│   └── utils.ts              # Helper functions
│
├── pages/                    # Page components (lazy-loaded)
│   ├── analytics/            # Split from 420-line file (8 files)
│   │   ├── index.tsx         # Main layout
│   │   ├── types.ts          # Analytics types
│   │   ├── hooks.ts          # Data fetching hooks
│   │   ├── utils.ts          # Utility functions
│   │   └── components/
│   │       ├── analytics-header.tsx
│   │       ├── analytics-skeleton.tsx
│   │       ├── charts-grid.tsx
│   │       └── cost-by-model-card.tsx
│   ├── settings/             # Split from 1,781-line file (20 files)
│   │   ├── index.tsx         # Main layout with lazy loading
│   │   ├── context.tsx       # Settings provider wrapper
│   │   ├── settings-context.ts
│   │   ├── types.ts
│   │   ├── hooks.ts          # Legacy re-exports
│   │   ├── hooks/
│   │   │   ├── index.ts
│   │   │   ├── context-hooks.ts
│   │   │   ├── use-official-channels-config.ts
│   │   │   ├── use-settings-tab.ts
│   │   │   ├── use-proxy-config.ts
│   │   │   ├── use-websearch-config.ts
│   │   │   ├── use-globalenv-config.ts
│   │   │   └── use-raw-config.ts
│   │   ├── components/
│   │   │   ├── section-skeleton.tsx
│   │   │   └── tab-navigation.tsx
│   │   └── sections/
│   │       ├── channels.tsx
│   │       ├── globalenv-section.tsx
│   │       ├── websearch/
│   │       │   ├── index.tsx
│   │       │   └── provider-card.tsx
│   │       └── proxy/
│   │           ├── index.tsx
│   │           ├── local-proxy-card.tsx
│   │           └── remote-proxy-card.tsx
│   ├── api.tsx               # API profiles page (350 lines)
│   ├── cliproxy.tsx          # CLIProxy page (405 lines)
│   ├── copilot.tsx           # Copilot page (295 lines)
│   └── health.tsx            # Health page (256 lines)
│
└── providers/                # Context providers
    └── websocket-provider.tsx

Component Statistics

Domain	Components	Subdirs	Split Files
account	3	flow-viz (12 files)	1 monster split
analytics	3	-	-
cliproxy	10	provider-editor, config, overview	1 monster split
copilot	2	config-form (13 files)	1 monster split
health	2	-	-
layout	3	-	-
monitoring	3	auth-monitor (8 files), error-logs (6 files)	2 monster splits
profiles	4	editor (10 files)	1 monster split
setup	2	wizard/steps	-
shared	19	-	-
Total	51+	10 subdirs	7 splits

Page Statistics

Page	Structure	Files	Notes
analytics	Directory	8	Split 2025-12-21
settings	Directory	20	Split 2025-12-21, lazy-loaded sections
api	Single file	1	350 lines
cliproxy	Single file	1	405 lines
copilot	Single file	1	295 lines
health	Single file	1	256 lines

---

Key File Metrics

Largest Files (Acceptable Exceptions)

CLI (src/):

File	Lines	Status
model-pricing.ts	676	Data file - acceptable
glmt-proxy.ts	675	Legacy internal compatibility path - acceptable for now
cliproxy-executor.ts	666	Core logic - acceptable
cliproxy-command.ts	634	Could split if needed
usage/handlers.ts	633	Could split if needed
ccs.ts	596	Entry point - acceptable
unified-config-loader.ts	546	Complex - acceptable

UI (ui/src/):

File	Lines	Status
components/ui/sidebar.tsx	674	shadcn - acceptable
pages/cliproxy.tsx	405	Acceptable
pages/api.tsx	350	Acceptable
pages/copilot.tsx	295	Acceptable
pages/health.tsx	256	Acceptable

Split Files (Completed):

Original	Lines	New Location	Files
pages/settings.tsx	1,781	pages/settings/	20
pages/analytics.tsx	420	pages/analytics/	8
monitoring/auth-monitor.tsx	465	monitoring/auth-monitor/	8

---

Import Patterns

Standard Import Path

// From any file in src/
import { Config, Settings } from '../types';
import { execClaudeWithCLIProxy } from '../cliproxy';
import { handleError } from '../errors';

// From any file in ui/src/
import { AccountsTable, ProviderIcon, StatCard } from '@/components';
import { useAccounts, useProfiles } from '@/hooks';

Barrel Export Pattern

Every domain directory has an index.ts that aggregates exports:

// ui/src/components/cliproxy/index.ts
export { CategorizedModelSelector } from './categorized-model-selector';
export { CliproxyDialog } from './cliproxy-dialog';
// ...

// From subdirectories
export { ProviderEditor } from './provider-editor';
export type { ProviderEditorProps } from './provider-editor';

---

Test Structure

tests/
├── unit/                     # Unit tests (7 core test files)
│   ├── data-aggregator.test.ts
│   ├── cliproxy/
│   │   └── remote-proxy-client.test.ts
│   ├── commands/
│   │   └── env-command.test.ts
│   ├── jsonl-parser.test.ts
│   ├── model-pricing.test.ts
│   ├── unified-config.test.ts
│   └── mcp-manager.test.ts
├── integration/              # Integration tests
├── native/                   # Native install tests
│   ├── linux/
│   ├── macos/
│   └── windows/
├── npm/                      # npm package tests
├── shared/                   # Shared test utilities
└── README.md

Test Metrics

Metric	Value
Total Tests	1440
Passing	1440
Skipped	6
Failed	0
Coverage Threshold	90%
Test Files	41

---

Build Outputs

Output	Source	Purpose
dist/	src/	npm package (CLI)
dist/ui/	ui/src/	Built React app (served by Express)
lib/	N/A	Native shell scripts

---

Related Documentation

• Code Standards - Modularization patterns, file size rules
• System Architecture - High-level architecture diagrams
• Project Roadmap - Modularization phases and future work
• WebSearch - WebSearch feature documentation
• Image Analysis - First-class ImageAnalysis runtime documentation
• CLAUDE.md - AI-facing development guidance