Related Pages

Related topics: System Architecture, Quick Start Guide

Introduction to cc-connect

cc-connect is a bridge service that connects local AI coding agents to messaging platforms, enabling developers to interact with their AI development assistants from anywhere through popular chat applications.

Overview

cc-connect acts as a middleware layer between AI coding agents and messaging platforms. It allows developers to leverage the power of AI coding tools like Claude Code, Cursor, Codex, Gemini CLI, and iFlow from messaging applications such as Feishu/Lark, DingTalk, Slack, Telegram, Discord, LINE, and WeChat Work.

Sources: npm/README.md:1-12

Architecture

cc-connect consists of three main components:

The backend service runs as a daemon process and maintains persistent connections to both the local AI coding agent and the configured messaging platforms.

Sources: INSTALL.md:1-50

Supported AI Agents

cc-connect integrates with multiple AI coding agents through a unified agent interface:

Sources: INSTALL.md:60-75

Supported Messaging Platforms

The service supports integration with multiple enterprise and consumer messaging platforms:

• Feishu/Lark - ByteDance's enterprise communication platform
• DingTalk - Alibaba's enterprise messaging tool
• Slack - Popular team collaboration platform
• Telegram - Cloud-based instant messaging
• Discord - Community and gaming communication
• LINE - Japanese messaging application
• WeChat Work - Tencent's enterprise WeChat variant

Sources: npm/README.md:3

Project Management

cc-connect organizes work through projects, where each project links a code folder to one or more messaging platforms.

[[projects]]
name = "my-project"

[projects.agent]
type = "claudecode"  # or "codex", "cursor", "gemini", "qoder", "opencode", "iflow"

[projects.agent.options]
work_dir = "/absolute/path/to/your/project"
mode = "default"

Sources: INSTALL.md:30-45

Configuration

Configuration File Locations

cc-connect searches for configuration in this order:

If no config file exists, running cc-connect will auto-create a starter template at ~/.cc-connect/config.toml.

Sources: INSTALL.md:8-18

Global Settings

Web Interface

The web admin interface provides a graphical dashboard for managing all cc-connect functionality:

Sessions Management

The sessions feature displays active chat sessions with real-time status indicators:

• Live session badges showing active connections
• Last message preview with role indicators
• Session switching and creation capabilities

Sources: web/src/pages/Sessions/SessionList.tsx:10-30

Bridge Status Monitoring

The interface displays connection status between cc-connect and the configured messaging platforms:

Sources: web/src/pages/Chat/ChatView.tsx:1-25

Provider Management

Providers define the messaging platform connections. Each provider can have multiple models and agent types associated with it.

Sources: web/src/pages/Providers/ProviderList.tsx:1-30

API Client

The web interface communicates with the backend through a RESTful API client:

get<T>(path: string, params?: Record<string, string>)
post<T>(path: string, body?: any)
put<T>(path: string, body?: any)
patch<T>(path: string, body?: any)
delete<T>(path: string)
async raw(path: string): Promise<string>

The client supports JWT Bearer token authentication and handles unauthorized access with automatic callback notification.

Sources: web/src/api/client.ts:1-50

Internationalization

cc-connect supports multiple languages for its user interface and messages:

Sources: core/i18n.go:1-50

Installation Methods

Package Managers

Manual Installation

1. Download the binary from GitHub Releases
2. Make it executable: chmod +x cc-connect
3. Move to PATH: sudo mv cc-connect /usr/local/bin/

Build from Source

Requires Go 1.22+:

git clone https://github.com/chenhg5/cc-connect.git
cd cc-connect
make build

Sources: INSTALL.md:80-110

Daemon Management

cc-connect can run as a background service managed by the operating system:

On Linux, this uses systemd user services. On macOS, it uses launchd LaunchAgents. On Windows, it creates a Task Scheduler task.

Sources: INSTALL.md:150-175

Workflow Diagram

graph TD
    A[User on Messaging Platform] -->|Sends Message| B[Messaging Platform API]
    B -->|Routes Message| C[cc-connect Bridge]
    C -->|Processes & Formats| D[Local AI Agent]
    D -->|AI Response| C
    C -->|Formats Response| B
    B -->|Delivers Message| A
    
    E[Web Admin UI] -->|Configuration| C
    F[config.toml] -->|Settings| C

Skills System

cc-connect supports an extensible skills system that allows AI agents to gain additional capabilities:

• Recommended Skills - Curated skill presets that can be downloaded
• Custom Skills - User-defined skills for specific workflows
• Skill Presets - Pre-configured skill collections with metadata

Skills include metadata such as:

• Display name and description
• Version information
• Pricing model
• Author attribution
• Source URL and provider information

Sources: web/src/pages/Skills/SkillList.tsx:1-100

Summary

cc-connect provides a unified bridge between local AI coding agents and enterprise messaging platforms, enabling developers to:

• Access AI coding assistance from any messaging platform
• Manage multiple projects with different AI agents
• Configure flexible provider settings
• Monitor connections through a web-based dashboard
• Extend capabilities through a skills system

The architecture prioritizes reliability with automatic reconnection, comprehensive logging, and daemon-based operation for continuous availability.

Related Pages

Related topics: Introduction to cc-connect, Configuration Guide, Deployment and Operations

Quick Start Guide

cc-connect is a bridge service that connects local AI coding agents (Claude Code, Codex, Cursor, Gemini CLI, etc.) with messaging platforms (Feishu, Telegram, Discord, Slack, etc.). This enables natural language interaction with AI coding agents through familiar chat interfaces.

Prerequisites

Before installing cc-connect, ensure your environment meets these requirements:

You must also install at least one supported AI coding agent:

# Claude Code
npm install -g @anthropic-ai/claude-code

# Codex
npm install -g @openai/codex

# Gemini CLI
npm install -g @google/gemini-cli

# iFlow CLI
npm install -g @iflow-ai/if

Installation Methods

Option A: Homebrew (macOS/Linux)

brew tap chenhg5/tap
brew install cc-connect

Option B: Download Binary

Download pre-built binaries from GitHub Releases:

curl -L -o cc-connect https://github.com/chenhg5/cc-connect/releases/latest/download/cc-connect-linux-amd64
chmod +x cc-connect
sudo mv cc-connect /usr/local/bin/

On macOS, remove the quarantine attribute:

xattr -d com.apple.quarantine cc-connect

Option C: Build from Source

git clone https://github.com/chenhg5/cc-connect.git
cd cc-connect
make build

Sources: INSTALL.md:1-80

Configuration

Config File Location

cc-connect searches for configuration in this order:

1. -config <path> flag (explicit path)
2. ./config.toml (current directory)
3. ~/.cc-connect/config.toml (global, recommended)

Sources: INSTALL.md:10-15

Create Starter Config

The easiest method is to let cc-connect auto-generate a starter config:

# Run once - creates ~/.cc-connect/config.toml automatically
cc-connect

Or manually create from the example:

mkdir -p ~/.cc-connect
cp config.example.toml ~/.cc-connect/config.toml

Configuration Structure

# Optional global settings
# language = "en"  # "en", "zh", or "" (auto-detect)

[log]
level = "info"  # debug, info, warn, error

# Each [[projects]] entry connects one code folder to one or more messaging platforms
[[projects]]
name = "my-project"

[projects.agent]
type = "claudecode"  # or "codex", "cursor", "gemini", "qoder", "opencode", "iflow"

[projects.agent.options]
work_dir = "/absolute/path/to/your/project"
mode = "default"  # "default", "acceptEdits", "plan", "yolo"

[[projects.platforms]]
type = "feishu"  # or "telegram", "discord", "slack", "dingtalk", etc.

[projects.platforms.options]
app_id = "cli_xxx"
app_secret = "xxx"

Sources: INSTALL.md:30-60

Agent Permission Modes

Sources: web/src/pages/Projects/ProjectDetail.tsx:1-30

Running the Application

Basic Startup

# Run with config.toml in current directory
cc-connect

# Or specify config path
cc-connect -config /path/to/config.toml

# Check version
cc-connect --version

Expected output:

level=INFO msg="platform started" project=my-project platform=feishu
level=INFO msg="engine started" project=my-project agent=claudecode platforms=1
level=INFO msg="cc-connect is running" projects=1

Claude Code Session Note

If running inside a Claude Code session, you must unset the CLAUDECODE environment variable before starting:

unset CLAUDECODE && cc-connect

Alternatively, open a separate terminal to run cc-connect.

Sources: INSTALL.md:75-90

Chat Commands

Once running, use these slash commands on your configured messaging platform:

Sources: INSTALL.md:95-110

Scheduled Tasks (Cron)

Create automated tasks that run through the agent or execute shell commands directly.

Add a Scheduled Task

cc-connect cron add --cron "<min> <hour> <day> <month> <weekday>" --prompt "<task description>" --desc "<short label>"

Cron Expression Format

Examples

# Run every day at 6am through the agent
cc-connect cron add --cron "0 6 * * *" --prompt "Collect GitHub trending repos and send a summary" --desc "Daily GitHub Trending"

# Run every Monday at 9am
cc-connect cron add --cron "0 9 * * 1" --prompt "Generate a weekly project status report" --desc "Weekly Report"

# Run every 30 minutes with direct shell command
cc-connect cron add --cron "*/30 * * * *" --exec "df -h" --desc "Disk usage check"

Additional Cron Options

Sources: cmd/cc-connect/cron.go:1-50

Multi-Project Setup

A single cc-connect process can manage multiple projects, each with its own agent, work directory, and platforms:

[[projects]]
name = "backend"
[projects.agent]
type = "claudecode"
[projects.agent.options]
work_dir = "/path/to/backend"
mode = "default"
[[projects.platforms]]
type = "feishu"
[projects.platforms.options]
app_id = "cli_xxx"
app_secret = "xxx"

[[projects]]
name = "frontend"
[projects.agent]
type = "codex"
[projects.agent.options]
work_dir = "/path/to/frontend"
mode = "full-auto"
[[projects.platforms]]
type = "telegram"
[projects.platforms.options]
token = "xxx"

[[projects]]
name = "design-system"
[projects.agent]
type = "cursor"
[projects.agent.options]
work_dir = "/path/to/design-system"
mode = "force"
[[projects.platforms]]
type = "discord"
[projects.platforms.options]
token = "xxx"

Sources: INSTALL.md:150-180

Running as a Background Service

Install the Daemon

cc-connect daemon install --config ~/.cc-connect/config.toml

Or specify the work directory containing config.toml:

cc-connect daemon install --work-dir ~/.cc-connect

Service Control Commands

cc-connect daemon start
cc-connect daemon stop
cc-connect daemon restart
cc-connect daemon status

View Logs

cc-connect daemon logs           # tail current log
cc-connect daemon logs -f         # follow (like tail -f)
cc-connect daemon logs -n 100     # last 100 lines
cc-connect daemon logs --log-file /path/to/log  # custom log file

Logs auto-rotate at the configured max size and keep one backup.

On Windows, this creates a Task Scheduler task that runs at user logon.

Sources: INSTALL.md:190-220

Agent Integration

Claude Code

Claude Code handles cc-connect integration automatically via --append-system-prompt - no extra setup needed.

Other Agents

For Codex, Cursor Agent, Qoder CLI, Gemini CLI, OpenCode, or iFlow CLI, add instructions to the agent's project-level instruction file:

Create/edit the file in your project's work_dir with cc-connect integration instructions. The agent will automatically use cc-connect cron add commands when scheduling tasks.

Tip: Add these files to .gitignore if you don't want cc-connect instructions committed to version control.

Sources: AGENTS.md:1-30

Web UI

The cc-connect web interface provides a visual dashboard for managing projects. Access it at:

http://localhost:18792

The web UI allows you to:

• View and manage projects
• Configure platforms
• Manage provider settings
• View and manage agent sessions
• Configure and monitor skills

Sources: web/index.html:1-15

Upgrade Instructions

Package Manager Users

brew upgrade cc-connect

Binary Users

# Download new binary
curl -L -o cc-connect https://github.com/chenhg5/cc-connect/releases/latest/download/cc-connect-linux-amd64
chmod +x cc-connect
sudo mv cc-connect /usr/local/bin/

Source Users

cd cc-connect
git pull
make build

After upgrading, restart the running cc-connect process.

Sources: INSTALL.md:85-100

Verification Checklist

Before going to production, verify:

• [ ] Build passes: go build ./...
• [ ] Tests pass: go test ./...
• [ ] Configuration file is valid TOML
• [ ] Agent is installed and accessible from PATH
• [ ] Platform credentials are configured correctly
• [ ] Network connectivity to platform APIs works
• [ ] Web UI is accessible
• [ ] Basic chat commands work (/new, /list, /history)

Sources: AGENTS.md:1-10

Related Pages

Related topics: Core Components, Agent Integrations, Platform Integrations

System Architecture

Overview

cc-connect is a bridge service that connects AI coding agents (such as Claude Code, Codex, Cursor, Gemini, Qoder, OpenCode, and iFlow) with messaging platforms (Feishu, WeChat Work, Telegram, Discord, Slack, DingTalk, WeCom, WeChat, QQ, Line, Weibo). The system acts as a bidirectional relay, translating messages between agent sessions and chat platforms in real-time.

High-Level Architecture

graph TD
    subgraph "Messaging Platforms"
        FEISHU[Feishu]
        WECHAT[WeChat Work]
        TELEGRAM[Telegram]
        DISCORD[Discord]
        SLACK[Slack]
        DINGTALK[DingTalk]
        WECOM[WeCom]
        WEIXIN[WeChat]
        QQ[QQ]
    end

    subgraph "cc-connect Core"
        BRIDGE[Bridge Manager]
        ENGINE[Engine]
        RELAY[Relay Handler]
        SESSION[Session Manager]
    end

    subgraph "AI Agents"
        CLAUDE[Claude Code]
        CODEX[Codex]
        CURSOR[Cursor]
        GEMINI[Gemini]
        QODER[Qoder]
        OPENCODE[OpenCode]
        IFLOW[iFlow]
    end

    FEISHU <--> BRIDGE
    WECHAT <--> BRIDGE
    TELEGRAM <--> BRIDGE
    DISCORD <--> BRIDGE
    SLACK <--> BRIDGE
    DINGTALK <--> BRIDGE
    WECOM <--> BRIDGE
    WEIXIN <--> BRIDGE
    QQ <--> BRIDGE

    BRIDGE <--> ENGINE
    ENGINE <--> RELAY
    ENGINE <--> SESSION
    RELAY <--> CLAUDE
    RELAY <--> CODEX
    RELAY <--> CURSOR
    RELAY <--> GEMINI
    RELAY <--> QODER
    RELAY <--> OPENCODE
    RELAY <--> IFLOW

Core Components

Bridge Manager

The Bridge Manager (core/bridge.go) is the central coordinator that maintains WebSocket connections to all configured messaging platforms. It handles:

• Connection lifecycle management (connect, reconnect, disconnect)
• Message routing between platforms and the engine
• Bridge status monitoring for the web UI

The web UI displays bridge status using icons and text:

// Connected state - ChatView.tsx:45
bridgeStatus === 'error' ? (
  <div className="flex items-center gap-2 text-amber-600">
    <WifiOff size={14} />
    <span>{t('sessions.bridgeDisconnected')}</span>
  </div>
) : (
  <div className="flex items-center gap-2 text-gray-400">
    <Loader2 size={14} className="animate-spin" />
    <span>{t('sessions.bridgeConnecting')}</span>
  </div>
)

Engine

The Engine (core/engine.go) serves as the central processing unit that:

• Manages project configurations and agent assignments
• Coordinates message processing and response handling
• Maintains session state across multiple concurrent conversations

Relay Handler

The Relay Handler (core/relay.go) acts as the message translation layer between platforms and agents:

• Converts incoming platform messages to agent-readable format
• Translates agent responses back to platform-specific formats
• Handles multi-turn conversations and context preservation

Session Management

Each project can have multiple sessions, allowing concurrent conversations. The system supports:

graph LR
    subgraph "Project: my-project"
        S1[Session: session-1]
        S2[Session: session-2]
        S3[Session: session-3]
    end

    S1 <--> A1[Claude Code]
    S2 <--> A2[Claude Code]
    S3 <--> A3[Claude Code]

Sessions are accessible via the UI drawer component:

// ProjectList.tsx:120
<SessionDrawer
  open={drawerOpen}
  onClose={() => setDrawerOpen(false)}
  sessions={sessions}
  currentSessionId={currentSession?.id || ''}
  onSelect={switchToSession}
  onNewSession={handleNewSession}
/>

Agent System

Supported Agents

Agent Configuration

Agents are configured per project in config.toml:

[[projects]]
name = "my-project"

[projects.agent]
type = "claudecode"

[projects.agent.options]
work_dir = "/absolute/path/to/your/project"
mode = "default"

Sources: INSTALL.md

Adding New Agents

The architecture follows a plugin pattern for extensibility. To add a new agent:

1. Create agent/newagent/newagent.go
2. Implement core.Agent and core.AgentSession interfaces
3. Register in init(): core.RegisterAgent("newagent", factory)
4. Create cmd/cc-connect/plugin_agent_newagent.go with //go:build tag

Sources: AGENTS.md

Platform System

Supported Platforms

Platform Setup Flow

graph TD
    A[Add Platform] --> B{Is QR Platform?}
    B -->|Yes| C[Show QR Code]
    B -->|No| D{Has Manual Form?}
    D -->|Yes| E[Platform Manual Form]
    D -->|No| F[Manual Config Hint]
    C --> G[Complete]
    E --> G
    G --> H[Restart Required Modal]
    H --> I[Restart Service]

Platform setup is handled dynamically in the UI:

// ProjectDetail.tsx:85
(addPlatType) ? (
  <PlatformSetupQR
    platformType={addPlatType as 'feishu' | 'weixin'}
    projectName={name!}
    onComplete={() => {
      setShowAddPlatform(false);
      setShowRestartModal(true);
    }}
    onCancel={() => setAddPlatType('')}
  />
) : platformMeta[addPlatType] ? (
  <PlatformManualForm
    platformType={addPlatType}
    projectName={name!}
    onComplete={() => {
      setShowAddPlatform(false);
      setShowRestartModal(true);
    }}
    onCancel={() => setAddPlatType('')}
  />
) : (
  <div>
    <p>{t('setup.manualHint', 'For {{platform}}, please configure credentials in config.toml')}</p>
  </div>
)

Adding New Platforms

New platforms follow the same plugin architecture:

1. Create platform/newplatform/newplatform.go
2. Implement core.Platform interface
3. Register in init(): core.RegisterPlatform("newplatform", factory)
4. Add //go:build !no_newplatform tag in plugin file
5. Add platform to ALL_PLATFORMS in Makefile

Sources: AGENTS.md

Web API Client

The frontend communicates with the backend via a typed API client:

// client.ts:25
export class ApiClient {
  async request<T>(method: string, path: string, body?: any, params?: Record<string, string>): Promise<T> {
    const h: HeadersInit = {};
    if (this.token) h['Authorization'] = `Bearer ${this.token}`;
    const res = await fetch(`${API_BASE}${path}`, { method, headers: h, body, params });
    // ...
  }

  get<T>(path: string, params?: Record<string, string>) { return this.request<T>('GET', path, undefined, params); }
  post<T>(path: string, body?: any) { return this.request<T>('POST', path, body); }
  put<T>(path: string, body?: any) { return this.request<T>('PUT', path, body); }
  delete<T>(path: string) { return this.request<T>('DELETE', path); }
}

Sources: web/src/api/client.ts

Provider System

Global providers allow centralized API key management for multiple projects:

graph TD
    subgraph "Global Providers"
        P1[Provider: anthropic]
        P2[Provider: openai]
        P3[Provider: google]
    end

    subgraph "Projects"
        PRJ1[my-project]
        PRJ2[work-project]
        PRJ3[test-project]
    end

    P1 --> PRJ1
    P1 --> PRJ2
    P2 --> PRJ2
    P2 --> PRJ3
    P3 --> PRJ3

Provider configurations include base URL, default model, model lists, and thinking settings:

// ProviderList.tsx:150
{
  label: t('globalProviders.form.thinking'),
  type: 'select',
  value: form.thinking || '',
  options: [
    { value: '', label: t('globalProviders.form.thinkingDefault') },
    { value: 'enabled', label: 'enabled' },
    { value: 'disabled', label: 'disabled' },
  ]
}

Cron Scheduling

The system supports scheduled tasks for automated workflows:

cc-connect cron add --cron "0 6 * * *" --prompt "Collect GitHub trending data" --desc "Daily Trending"
cc-connect cron add --cron "*/30 * * * *" --exec "df -h" --desc "Disk usage check"

Available cron options:

Sources: cmd/cc-connect/cron.go

Configuration Structure

The system uses TOML configuration with the following precedence:

1. -config <path> flag (explicit)
2. ./config.toml (current directory)
3. ~/.cc-connect/config.toml (global, recommended)

# Optional global settings
# language = "en"  # "en", "zh", or "" (auto-detect)

[log]
level = "info"  # debug, info, warn, error

[[projects]]
name = "my-project"

[projects.agent]
type = "claudecode"

[projects.agent.options]
work_dir = "/absolute/path/to/your/project"
mode = "default"

Sources: INSTALL.md

Data Flow

sequenceDiagram
    participant User
    participant Platform as Messaging Platform
    participant Bridge as Bridge Manager
    participant Engine as Engine
    participant Relay as Relay Handler
    participant Agent as AI Agent

    User->>Platform: Send message
    Platform->>Bridge: WebSocket event
    Bridge->>Engine: Process message
    Engine->>Relay: Route to agent
    Relay->>Agent: Format & forward
    Agent->>Relay: Generate response
    Relay->>Engine: Process response
    Engine->>Bridge: Route response
    Bridge->>Platform: Send reply
    Platform->>User: Display message

Extension Points

Disabling Features

Build tags allow excluding specific platforms or agents:

no_gemini, no_iflow, no_opencode, no_qoder, no_feishu, no_telegram,
no_discord, no_slack, no_dingtalk, no_wecom, no_weixin, no_qq, no_line, no_weibo

Sources: AGENTS.md

Build Requirements

The pre-commit checklist ensures code quality:

1. Build passes: go build ./...
2. Tests pass: go test ./...
3. No new hardcoded platform/agent names in core
4. i18n complete: all new user-facing strings have translations
5. No secrets in code: no API keys in source files

Related Pages

Related topics: System Architecture, Configuration Guide

Core Components

The cc-connect project is structured around a layered architecture consisting of a Go-based core backend and a React-based web interface. The core components provide the essential infrastructure for agent management, message handling, internationalization, and scheduled task execution.

Architecture Overview

The system follows a modular plugin-based architecture where core interfaces define contracts for platforms and agents.

graph TD
    A[User/CLI] --> B[Web UI or CLI]
    B --> C[Core Backend API]
    C --> D[Agent Plugins]
    C --> E[Platform Plugins]
    F[Config File] --> C
    G[i18n] --> B

Internationalization System

The internationalization (i18n) subsystem in core/i18n.go provides multi-language support for all user-facing messages.

Supported Languages

Sources: core/i18n.go

Message Structure

Messages are defined using a MessageMap type that maps language codes to translated strings:

MsgProviderSwitchHint: {
    LangEnglish:            "`/provider switch <name>` to switch | `/provider clear` to reset",
    LangChinese:            "`/provider switch <名称>` 切换 | `/provider clear` 清除",
    LangTraditionalChinese: "`/provider switch <名稱>` 切換 | `/provider clear` 清除",
    LangJapanese:           "`/provider switch <名前>` で切り替え | `/provider clear` でリセット",
    LangSpanish:            "`/provider switch <nombre>` para cambiar | `/provider clear` para restablecer",
},

The system includes messages for:

• Provider management (switching, listing, errors)
• Session management
• Command execution feedback
• Error handling

Sources: core/i18n.go

API Client

The web interface communicates with the backend through web/src/api/client.ts, which provides a typed REST client.

ApiClient Methods

Sources: web/src/api/client.ts

Error Handling

export class ApiError extends Error {
  constructor(message: string, public status: number) {
    super(message);
    this.name = 'ApiError';
  }
}

The client handles:

• JSON response parsing
• 401 Unauthorized with callback notification
• Generic HTTP error propagation

Agent Architecture

Agents are implemented as plugins following a defined interface. The AGENTS.md documentation outlines the agent system design.

Adding a New Agent

1. Create agent/newagent/newagent.go
2. Implement core.Agent and core.AgentSession interfaces
3. Register in init(): core.RegisterAgent("newagent", factory)
4. Create plugin file with //go:build !no_newagent tag
5. Add to ALL_AGATFORMS in Makefile
6. Add unit tests

Sources: AGENTS.md

Supported Agent Types

Based on the configuration structure, the following agent types are supported:

Agent Modes

Sources: web/src/pages/Projects/ProjectDetail.tsx

Provider System

Providers manage API credentials and configuration for LLM services. The provider system is managed through the web interface in web/src/pages/Providers/ProviderList.tsx.

Provider Configuration

Providers include:

• Name: Unique identifier
• Base URL: API endpoint
• Model: Default model
• Models: Available models array
• Thinking: Thinking mode (enabled, disabled, or default)
• Agent Types: Supported agent types

interface GlobalProvider {
  name: string;
  base_url?: string;
  model?: string;
  models?: string[];
  thinking?: string;
  agent_types?: string[];
}

Thinking Configuration

The thinking setting can be configured per-provider:

Sources: web/src/pages/Providers/ProviderList.tsx

Scheduled Tasks (Cron)

The cron subsystem in cmd/cc-connect/cron.go enables scheduled task execution.

Cron Command Options

Cron Expression Format

Standard 5-field cron format:

<min> <hour> <day> <month> <weekday>

Session Modes

Examples

# Daily task at 6 AM
cc-connect cron add --cron "0 6 * * *" --prompt "Collect GitHub trending data" --desc "Daily Trending"

# Every 30 minutes
cc-connect cron add --cron "*/30 * * * *" --exec "df -h" --desc "Disk usage check"

Sources: cmd/cc-connect/cron.go

Project Management

Projects connect code folders to messaging platforms. Each project configuration includes:

[[projects]]
name = "my-project"

[projects.agent]
type = "claudecode"  # or "codex", "cursor", "gemini", etc.

[projects.agent.options]
work_dir = "/absolute/path/to/your/project"
mode = "default"

Project Features

Sources: web/src/pages/Projects/ProjectList.tsx

Skill System

Skills extend agent capabilities through a plugin-like configuration system.

Skill Types

• Local Skills: Project-specific skills defined in local directories
• Recommended Skills: Preset skill configurations

Skill Configuration

Each skill includes:

• name: Skill identifier
• display_name: Human-readable name
• description: Skill purpose
• source: Skill origin/path

Scan Directories

Projects can define scan directories for discovering skills:

interface ProjectSkills {
  project: string;
  agent_type: string;
  skills?: Skill[];
  dirs?: string[];  // Scan directories
}

Sources: web/src/pages/Skills/SkillList.tsx

Configuration

The system uses TOML configuration files, searching in this order:

1. -config <path> flag (explicit path)
2. ./config.toml (current directory)
3. ~/.cc-connect/config.toml (global, recommended)

If no config exists, cc-connect auto-creates a starter template at ~/.cc-connect/config.toml.

Sources: INSTALL.md

Web Interface Structure

The React web interface is organized by functional areas:

Bridge Connection Status

The UI displays connection status indicators:

Sources: web/src/pages/Chat/ChatView.tsx

Related Pages

Related topics: System Architecture, Platform Integrations

Agent Integrations

Overview

Agent Integrations in CC-Connect provide a unified abstraction layer for connecting to various AI agent backends. The system supports multiple agent providers including Claude Code, OpenAI Codex, Cursor, Gemini, and Kimi, allowing projects to utilize different AI capabilities through a consistent interface.

Architecture

The agent integration system follows a plugin-style architecture where each agent implementation conforms to a common interface defined in core/interfaces.go. This design enables runtime provider switching and consistent interaction patterns across all supported agents.

graph TD
    A[User/Project] --> B[CC-Connect Core]
    B --> C[Agent Interface]
    C --> D[Claude Code Agent]
    C --> E[Codex Agent]
    C --> F[Cursor Agent]
    C --> G[Gemini Agent]
    C --> H[Kimi Agent]
    C --> I[ACP Agent]
    
    J[Provider Config] --> B
    K[Platform Integration] --> B

Supported Agent Types

The system currently supports the following agent backends:

Core Interface Definition

Each agent must implement the Agent interface defined in core/interfaces.go. The interface specifies the contract for agent lifecycle management, message handling, and capability reporting.

Sources: core/interfaces.go

Agent Configuration

Agent Type Selection

Projects specify their agent type through the agent_type field. This selection determines which agent backend will be used for processing requests.

<select
  value={selectedAgentType}
  onChange={(e) => setSelectedAgentType(e.target.value)}
>
  {agentTypes.map(a => <option key={a} value={a}>{a}</option>)}
</select>

Sources: web/src/pages/Projects/ProjectDetail.tsx

Thinking Mode

Agents support a configurable thinking mode that controls how the AI processes requests:

<select value={form.thinking || ''} onChange={e => set('thinking', e.target.value)}>
  <option value="">{t('globalProviders.form.thinkingDefault')}</option>
  <option value="enabled">enabled</option>
  <option value="disabled">disabled</option>
</select>

Sources: web/src/pages/Providers/ProviderList.tsx

Permission Modes

The system supports granular permission control for agent operations:

<select value={agentMode}>
  <option value="default">default</option>
  <option value="acceptEdits">acceptEdits (edit)</option>
  <option value="plan">plan</option>
  <option value="bypassPermissions">bypassPermissions (yolo)</option>
  <option value="dontAsk">dontAsk</option>
</select>

Sources: web/src/pages/Projects/ProjectDetail.tsx

Provider-Agent Relationship

Providers define which agent types they support through the agent_types configuration array:

{p.agent_types && p.agent_types.length > 0 && (
  <div className="mt-2 flex flex-wrap gap-1">
    {p.agent_types.map(a => (
      <Badge key={a} variant="info" className="text-xs">{a}</Badge>
    ))}
  </div>
)}

Sources: web/src/pages/Providers/ProviderList.tsx

Project Agent Assignment

Each project is associated with a specific agent type and can be configured with custom agent settings:

<div>
  <label>{t('projects.agentType', 'Agent type')}</label>
  <select value={selectedAgentType} onChange={(e) => setSelectedAgentType(e.target.value)}>
    {agentTypes.map(a => <option key={a} value={a}>{a}</option>)}
    {selectedAgentType && !agentTypes.includes(selectedAgentType) && (
      <option value={selectedAgentType}>{selectedAgentType}</option>
    )}
  </select>
  {selectedAgentType !== project.agent_type && (
    <p className="text-[11px] text-amber-500">
      {t('projects.agentTypeChangeHint', 'Changing agent type requires restart. Incompatible providers will be removed.')}
    </p>
  )}
</div>

Sources: web/src/pages/Projects/ProjectDetail.tsx

Workflow: Agent Selection and Switching

sequenceDiagram
    participant User
    participant UI as Web Interface
    participant Core as CC-Connect Core
    participant Provider as Provider Manager
    participant Agent as Agent Backend
    
    User->>UI: Select Project
    UI->>Core: Fetch Project Config
    Core->>UI: Return Project with agent_type
    User->>UI: Change Agent Type
    UI->>Core: Update Project agent_type
    Core->>Provider: Validate Provider Compatibility
    Provider-->>Core: Return Compatible Providers
    Core-->>UI: Confirm Configuration

Data Flow

When a message is processed through an agent integration:

1. Input: User message received via platform (WeChat, Slack, etc.)
2. Routing: Message routed to appropriate project based on session
3. Agent Selection: Project's agent_type determines agent backend
4. Provider Selection: Associated provider configuration loaded
5. Processing: Agent backend processes request with provider credentials
6. Response: Agent response returned through platform integration

Session Management

Sessions track the active agent context:

<div className="flex items-center gap-1.5 min-w-0">
  <MessageSquare size={14} className={s.live ? 'text-accent shrink-0' : 'text-gray-400 shrink-0'} />
  <span className="text-sm font-medium truncate">
    {s.name || s.user_name || s.id.slice(0, 8)}
  </span>
  {s.live && <Circle size={5} className="fill-emerald-500 text-emerald-500 shrink-0" />}
</div>

Sources: web/src/pages/Sessions/SessionList.tsx

Configuration File Structure

Agent integrations are configured through config.toml or via the admin interface:

[[agents]]
name = "my-project"
agent_type = "claude"
thinking = "enabled"

[[providers]]
name = "anthropic"
base_url = "https://api.anthropic.com"
models = ["claude-sonnet-4-20250514"]

Best Practices

1. Provider Compatibility: When changing agent types, verify the new type is supported by your configured provider
2. Permission Mode: Use bypassPermissions only in controlled environments
3. Thinking Mode: Enable thinking for complex reasoning tasks; disable for simple operations to reduce latency
4. Session Persistence: Active sessions maintain agent context across multiple interactions

Related Pages

Related topics: System Architecture, Agent Integrations

Platform Integrations

Overview

Platform Integrations in cc-connect enable AI agents to connect and communicate across multiple messaging and collaboration platforms. The system acts as a unified bridge, allowing a single AI agent to serve users on different platforms simultaneously without requiring separate deployments.

Architecture Overview

The platform integration system follows a plugin-based architecture where each messaging platform is implemented as a separate module conforming to a common Platform interface.

graph TD
    A[User] -->|Message| B[Platform Adapter]
    B --> C[Core Agent]
    C -->|Response| B
    B -->|Deliver| A
    
    D[Telegram] --> B
    E[Slack] --> B
    F[Discord] --> B
    G[DingTalk] --> B
    H[WeChat] --> B
    I[Feishu] --> B
    J[WeCom] --> B
    K[QQ] --> B
    L[LINE] --> B
    M[Weibo] --> B

Supported Platforms

cc-connect supports the following messaging platforms:

Sources: AGENTS.md:1

Platform Configuration

Configuration Structure

Each platform is configured within the [[projects.platforms]] section of config.toml:

[[projects.platforms]]
type = "telegram"  # Platform type identifier

[projects.platforms.options]
token = "1234567890:ABCdefGHIjklMNOpqrsTUVwxyz"

Project-Level Platform Assignment

Projects can specify which platforms they utilize through the platforms field:

interface Project {
  name: string;
  agent_type: string;
  platforms?: string[];  // e.g., ["telegram", "slack"]
  heartbeat_enabled?: boolean;
  sessions_count?: number;
}

Sources: web/src/pages/Projects/ProjectList.tsx:1-15

Adding a New Platform

The platform integration system is designed for extensibility. New platforms can be added by following this checklist:

1. Create Platform Module: Create platform/newplatform/newplatform.go
2. Implement Interface: Implement the core.Platform interface (and optional interfaces as needed)
3. Register Platform: Register in init(): core.RegisterPlatform("newplatform", factory)
4. Create Build Plugin: Create cmd/cc-connect/plugin_platform_newplatform.go with //go:build !no_newplatform tag
5. Update Build System: Add newplatform to ALL_PLATFORMS in Makefile
6. Document Configuration: Add config example in config.example.toml
7. Add Tests: Add unit tests for the platform module

Sources: AGENTS.md:15-23

Connection Methods

Long Polling

Some platforms (like Telegram) use long polling, where the client repeatedly requests new messages from the platform's API:

sequenceDiagram
    Client->>Platform API: GET /updates (long poll)
    Platform API-->>Client: Messages (or timeout)
    Client->>Platform API: GET /updates (long poll)

Webhook

Other platforms require a publicly accessible webhook endpoint:

sequenceDiagram
    Platform->>CC-Connect: POST /webhook/{platform}
    CC-Connect->>Platform: 200 OK
    CC-Connect->>Core: Process Message
    Core-->>Platform: Response

Platform-Specific Features

Telegram

Telegram uses long polling, eliminating the need for a public IP address. Setup requires:

1. Create a bot via @BotFather
2. Obtain the bot token
3. Configure in config.toml

Sources: INSTALL.md:1-30

Slack

Slack uses Socket Mode (WebSocket) for receiving events, which does not require a public IP:

1. Enable Socket Mode in app settings
2. Generate App-Level Token (xapp-...)
3. Subscribe to bot events: message.im, app_mention
4. Configure required Bot Token Scopes

Sources: INSTALL.md:40-55

Build Tags and Platform Exclusion

Platform integrations can be excluded at compile time using build tags:

Build tags are listed in AGENTS.md:

no_gemini, no_iflow, no_opencode, no_qoder, no_feishu, no_telegram, no_discord, no_slack, no_dingtalk, no_wecom, no_weixin, no_qq, no_qqbot, no_line, no_weibo.

Sources: AGENTS.md:1-3

Pre-Commit Checklist

When adding platform integrations, ensure compliance with:

1. Build passes: go build ./...
2. Tests pass: go test ./...
3. No new hardcoded platform/agent names in core: grep for platform names in core/*.go
4. i18n complete: All new user-facing strings have translations for all languages
5. No secrets in code: No API keys, tokens, or credentials in source files

Sources: AGENTS.md:5-11

Web Interface Management

The cc-connect admin web interface (CC-Connect Admin) provides UI components for managing platform-related settings:

Project Platform Assignment

Projects can be assigned multiple platforms through the web UI:

<div className="flex flex-wrap gap-1.5 mb-3">
  <Badge variant="info">{p.agent_type}</Badge>
  {p.platforms?.slice(0, 3).map((pl) => <Badge key={pl}>{pl}</Badge>)}
  {(p.platforms?.length ?? 0) > 3 && (
    <Badge>+{p.platforms!.length - 3}</Badge>
  )}
</div>

Sources: web/src/pages/Projects/ProjectList.tsx:1-10

Provider Thinking Configuration

Platform providers can have thinking modes configured per-agent:

{p.thinking && (
  <p className="mt-1.5 text-xs text-amber-600 dark:text-amber-400">
    thinking: {p.thinking}
  </p>
)}

Supported thinking modes:

• enabled - Thinking explicitly enabled
• disabled - Thinking explicitly disabled
• "" (empty) - Use default setting

Sources: web/src/pages/Providers/ProviderList.tsx:1-10

Message Processing Flow

graph LR
    A[Incoming Message] --> B[Platform Adapter]
    B --> C{Message Type?}
    C -->|Text| D[Parse Intent]
    C -->|Command| E[Handle Command]
    C -->|Media| F[Process Attachment]
    D --> G[Agent Processing]
    E --> G
    F --> G
    G --> H[Response Generation]
    H --> I[Markdown Rendering]
    I --> J[HTML Sanitization]
    J --> K[Platform Delivery]
    K --> L[End User]

Internationalization

All platform-related user-facing messages support multiple languages:

Provider-related messages include:

• MsgProviderSwitchHint: Command hints for switching providers
• MsgProviderNotFound: Error when provider doesn't exist
• MsgProviderSwitched: Confirmation when provider changes

Sources: core/i18n.go:1-30

Session Management

Sessions are tracked per-platform with metadata:

interface Session {
  id: string;
  name?: string;
  user_name?: string;
  live?: boolean;
  updated_at?: string;
  created_at?: string;
  last_message?: {
    role: 'user' | 'bot';
    content: string;
  };
}

Sources: web/src/pages/Sessions/SessionList.tsx:1-20

Markdown to HTML Rendering

Platform integrations utilize the MarkdownToSimpleHTML function for rendering agent responses:

func MarkdownToSimpleHTML(md string) string

Features supported:

• Code blocks with language syntax (<pre><code class="language-go">)
• Links (<a href="...">)
• Headings converted to bold (<b>)
• Blockquotes (<blockquote>)
• HTML escaping for special characters (<, >, &)

Sources: core/markdown_html_test.go:1-40

Summary

Platform Integrations in cc-connect provide a unified, extensible system for connecting AI agents to multiple messaging platforms. The architecture emphasizes:

• Modularity: Each platform is a separate plugin
• Flexibility: Multiple connection methods (webhook, long polling, WebSocket)
• Security: Build tags allow excluding platforms
• Internationalization: Full multi-language support
• Web Management: Admin UI for platform configuration

Related Pages

Related topics: Session Management, Web UI Administration

Configuration Guide

Overview

The cc-connect configuration system provides a flexible, multi-layered approach to managing AI provider settings, project configurations, and skill definitions. This guide covers all configuration aspects including global providers, project-specific settings, and skill presets.

Configuration Architecture

The system uses a hierarchical configuration model with three primary layers:

graph TD
    A[config.toml - Global Config] --> B[Project-level Settings]
    B --> C[Provider Configuration]
    C --> D[Model & API Settings]
    
    E[Skill Presets] -.-> B
    F[Provider Presets] -.-> C

Global Configuration

Global settings are managed through config.toml located in the application root directory. This file contains default providers and system-wide settings that apply across all projects.

Provider Configuration

Providers define the API endpoints and models used by agents. Each provider can be configured with multiple models and supports various agent types.

Sources: web/src/pages/Providers/ProviderList.tsx:1-50

Agent Types

The system supports multiple agent types with different capability profiles:

Sources: web/src/pages/Projects/ProjectDetail.tsx:1-30

Permission Modes

Agents can operate in different permission modes controlling their operational boundaries:

Sources: web/src/pages/Projects/ProjectDetail.tsx:30-60

Provider Presets

Provider presets provide pre-configured settings for common AI providers, sorted by pricing tier.

Tier System

Presets are organized into tiers reflecting cost and capability levels:

graph LR
    A[Tier 1 - Premium] --> B[Tier 2 - Standard]
    B --> C[Tier 3 - Budget]
    C --> D[Tier 4 - Free/Local]

Sources: web/src/pages/Providers/ProviderList.tsx:80-120

Adding Providers from Presets

interface ProviderPreset {
  name: string;
  tier: number;
  agent_types: string[];
  models: string[];
  thinking?: string;
}

The preset grid displays available presets sorted by tier. Existing provider names are filtered out using Set<string> to prevent duplicates.

Sources: web/src/pages/Providers/ProviderList.tsx:100-150

Project Configuration

Each project maintains its own configuration including agent type, working directory, and platform-specific settings.

Project Settings Structure

Sources: web/src/pages/Projects/ProjectList.tsx:1-50

Heartbeat Configuration

Projects can enable heartbeat monitoring with the following settings:

Sources: web/src/pages/Projects/ProjectDetail.tsx:200-250

Skill Presets

Skill presets define collections of skills organized by project type and agent capability.

Skill Preset Structure

interface SkillPreset {
  project: string;        // Project type identifier
  agent_type: string;      // Required agent type
  dirs?: string[];         // Scan directories for skills
  skills?: Skill[];       // Associated skills
}

Sources: web/src/pages/Skills/SkillList.tsx:50-100

Skill Structure

interface Skill {
  name: string;           // Skill identifier
  display_name?: string;  // User-friendly name
  description?: string;  // Skill description
  source: {
    url?: string;         // Source URL
    name?: string;         // Provider name
    provider?: string;     // Provider identifier
  };
  author?: string;        // Skill author
  url?: string;           // Download URL
}

Sources: web/src/pages/Skills/SkillList.tsx:100-150

CLI Configuration Commands

The command-line interface provides provider management commands:

Sources: core/i18n.go:1-100

Provider Switching

When switching providers, the system validates provider existence and updates the active configuration:

sequenceDiagram
    User->>CLI: /provider switch <name>
    CLI->>Config: Validate provider exists
    Config-->>CLI: Provider found
    CLI->>Config: Update active provider
    Config-->>User: Provider switched to <name>

Sources: core/i18n.go:100-150

Configuration File Example

# Global Providers Section
[providers.openai]
base_url = "https://api.openai.com/v1"
model = "gpt-4"
models = ["gpt-4", "gpt-3.5-turbo"]

[providers.claude]
base_url = "https://api.anthropic.com"
model = "claude-3-sonnet-20240229"
thinking = "enabled"

# Project-specific Configuration
[project.my-project]
agent_type = "claude"
work_dir = "/path/to/project"
platforms = ["github"]

# Heartbeat Configuration
[heartbeat.my-project]
interval_mins = 5

Platform-Specific Settings

Different platforms may require specific configuration:

Sources: AGENTS.md:1-50

Build Tags for Platform Support

Platform support is controlled via Go build tags:

ALL_PLATFORMS = gemini iflow opencode qoder feishu telegram discord slack dingtalk wecom weixin qq qqbot line weibo

To exclude specific platforms:

go build -tags "no_gemini,no_iflow"

Sources: AGENTS.md:50-100

Best Practices

1. Provider Organization: Use provider presets as templates and customize as needed
2. Project Isolation: Each project should have its own working directory
3. Permission Mode: Use plan mode for testing, bypassPermissions only when necessary
4. Heartbeat: Enable for long-running projects to monitor agent health
5. i18n: All user-facing strings should have translations for all supported languages

Summary

The cc-connect configuration system provides a comprehensive framework for managing AI providers, projects, and skills. By understanding the hierarchical relationship between global settings, project configurations, and skill presets, administrators can effectively customize the system for various use cases and platform requirements.

Related Pages

Related topics: Configuration Guide, Core Components

Session Management

Overview

Session Management is the core system responsible for maintaining conversational state between users and AI agents in cc-connect. Each session represents a single conversation context, preserving message history, working directory state, and agent configuration across interactions. The system enables users to switch between multiple concurrent conversations while maintaining isolation of context and state per session.

Sessions serve as the fundamental unit of work in cc-connect, allowing agents to maintain context across multiple requests, store conversation history, and provide seamless user experience through features like session switching, history retrieval, and live session indicators.

Architecture Overview

graph TD
    User[User] -->|Chat/CLI| WebUI[Web UI / CLI]
    WebUI -->|Bridge| Bridge[Session Bridge]
    Bridge -->|Manage| SessionMgr[Session Manager]
    SessionMgr -->|Persist| Store[Session Store]
    SessionMgr -->|Agent Comm| Agent[Agent Session]
    Agent -->|Execute| CodeAgent[Claude Code / Codex / etc]
    
    SessionMgr -->|State| ProjectState[Project State]
    SessionMgr -->|History| DirHistory[Directory History]
    SessionMgr -->|Schedule| Cron[Cron Jobs]
    
    subgraph Per-Session
        S1[Session 1]
        S2[Session 2]
        SN[Session N]
    end
    
    SessionMgr -.->|Created| S1
    SessionMgr -.->|Created| S2
    SessionMgr -.->|Created| SN

Session Data Model

Core Session Structure

type Session struct {
    ID              string           // Unique session identifier
    ProjectName     string           // Associated project
    Name            string           // Display name
    UserName        string           // Creator identifier
    ActiveSessionKeys []string       // Active session references
    Live            bool             // Currently active/in-use
    CreatedAt       time.Time        // Creation timestamp
    UpdatedAt       time.Time        // Last modification
    LastMessage     *HistoryEntry    // Most recent message
    Messages        []HistoryEntry   // Full message history
}

History Entry Structure

Each message in a session is stored as a HistoryEntry:

Session Lifecycle

Lifecycle States

stateDiagram-v2
    [*] --> Created: /new-session
    Created --> Active: First Message
    Active --> Active: Send Message
    Active --> Paused: /history or Switch
    Paused --> Active: Resume Session
    Active --> Closed: /close or Timeout
    Closed --> [*]: Cleanup
    
    Created --> Deleted: /delete
    Active --> Deleted: /delete
    Paused --> Deleted: /delete
    Deleted --> [*]

Session Creation

Sessions are created in multiple scenarios:

1. Explicit Creation: Via /new-session command or CLI cc-connect sessions new
2. Automatic on First Project Use: When a project has no existing sessions
3. Cron Job Sessions: Fresh sessions created per cron run (when session-mode: new-per-run)

Session Persistence

Sessions are persisted to storage with the following behavior:

• Active Session Tracking: ActiveSessionKeys array tracks currently active sessions per project
• Last Message Cache: The LastMessage field is updated after each exchange for quick retrieval
• History Truncation: When limit > 0, only the most recent N entries are retained (configurable per request)

Project State Management

Sessions are scoped to projects. The ProjectState interface manages this relationship:

type ProjectState interface {
    GetActiveSessionKey(project string) string
    SetActiveSessionKey(project, sessionKey string)
    AddSession(project string, session Session) error
    ListSessions(project string) ([]Session, error)
    GetSession(project, sessionKey string) (*Session, error)
}

Project-Session Relationship

Session History

History Entry Format

Sessions store a chronological list of HistoryEntry objects:

type HistoryEntry struct {
    Role      string    `json:"role"`
    Content   string    `json:"content"`
    Timestamp time.Time `json:"timestamp"`
    Thinking  string    `json:"thinking,omitempty"` // Codex reasoning
}

History Retrieval Commands

History Display

In the web UI, session history is displayed with:

• Role Indicators: User messages show User icon, assistant messages show Bot icon
• Timestamp: Relative time display using timeAgo() function
• Message Preview: Last 100 characters of content, newlines replaced with spaces
• Line Clamping: Messages limited to 2 lines in list view

Session Switching

Switch Session Methods

graph LR
    A[User] -->|/session| B[Switch Command]
    A -->|UI Click| C[SessionDrawer]
    B -->|Validate| D{Valid Session?}
    D -->|Yes| E[Set Active Session]
    D -->|No| F[Error: Not Found]
    E --> G[Update ProjectState]
    G --> H[Load Session Context]
    
    C -->|Select| I[switchToSession]
    I --> G

Active Session Management

The system maintains a single active session per project:

// ProjectState maintains active session key
func (ps *projectState) GetActiveSessionKey(project string) string
func (ps *projectState) SetActiveSessionKey(project, sessionKey string)

Session Drawer Component

The SessionDrawer component in web/src/pages/Sessions/SessionList.tsx provides:

Directory History Integration

Sessions track working directory changes via DirHistory:

type DirHistory struct {
    SessionID string   // Associated session
    Paths     []string // Ordered list of visited directories
    Index     int      // Current position in history
}

Directory Commands

This allows agents to maintain working context across sessions when the same session is resumed.

Scheduled Tasks (Cron) Integration

Sessions interact with the cron system through the --session-mode flag:

Session Modes

# Example: Daily task with reused session
cc-connect cron add --cron "0 6 * * *" --prompt "Summarize emails" --desc "Morning Summary"

# Example: Task requiring fresh context each run
cc-connect cron add --cron "*/30 * * * *" --exec "df -h" --session-mode new-per-run

Cron Session Configuration

CLI Session Commands

Available Commands

# List sessions for current project
cc-connect sessions list

# Create new session
cc-connect sessions new

# Switch to session
cc-connect sessions switch <session-id>

# Show session history
cc-connect sessions history <session-id> [limit]

# Delete session
cc-connect sessions delete <session-id>

Session Options (from `cmd/cc-connect/sessions.go`)

Bridge Communication

The web UI communicates with sessions via a bridge protocol:

sequenceDiagram
    participant UI as ChatView
    participant Bridge as Session Bridge
    participant Session as Session Manager
    
    UI->>Bridge: connect(project, sessionId)
    Bridge->>Session: Register connection
    Session-->>Bridge: session state
    Bridge-->>UI: bridge status: connected
    
    UI->>Bridge: send(message)
    Bridge->>Session: Process message
    Session->>Session: Update history
    Session-->>Bridge: response
    Bridge-->>UI: stream events
    
    Note over Bridge: status: "connected" | "connecting" | "error" | "disconnected"

Bridge Status States

Session Storage

Storage Location

• Default Directory: ~/.cc-connect
• Session Data: Stored in project-specific storage
• Session Key Environment Variable: CC_SESSION_KEY

Storage Schema

~/.cc-connect/
├── projects/
│   └── <project-name>/
│       └── sessions/
│           └── <session-id>/
│               ├── meta.json       # Session metadata
│               ├── messages.jsonl  # Message history
│               └── context/        # Agent context files

Agent-Specific Session Handling

Codex Agent

The Codex agent includes special session handling (agent/codex/session.go):

func patchSessionSource(sessionID, codexHome string) {
    // Rewrites session_meta line in Codex JSONL transcript
    // Sets source="cli" and originator="codex_cli_rs"
    // Makes session visible in interactive codex terminal
}

Session Context Loading

Codex sessions retry context loading with:

Best Practices

1. Session Naming: Use descriptive names for easy identification
2. History Cleanup: Periodically delete old sessions to maintain performance
3. Project Isolation: Keep sessions scoped to their project for proper context
4. Timeout Configuration: Set appropriate --timeout-mins for long-running tasks
5. Session Mode Selection: Use new-per-run for isolated tasks, reuse for conversational agents

Related Commands Reference

Related Pages

Related topics: Configuration Guide, Deployment and Operations

Web UI Administration

The Web UI Administration module in cc-connect provides a comprehensive, single-page administrative interface for managing the entire platform. Built with React and TypeScript, the web interface serves as the primary control center for administrators to configure projects, manage agent providers, monitor sessions, and administer scheduled cron jobs—all without requiring command-line interaction.

Architecture Overview

The web administration system follows a client-server architecture where the React frontend communicates with the Go backend through a RESTful API. The backend serves both static assets and dynamic API endpoints, while the frontend manages routing, state, and user interactions.

graph TD
    A[Browser Client] --> B[React SPA Frontend]
    B --> C[API Client Layer]
    C --> D[Go Backend API]
    D --> E[(SQLite Database)]
    D --> F[Platform Connectors<br/>Feishu/WeChat]
    D --> G[Agent Providers<br/>Claude/Codex/Gemini]
    
    B --> H[Dashboard]
    B --> I[Projects]
    B --> J[Sessions]
    B --> K[Providers]
    B --> L[Skills]
    B --> M[Cron Jobs]

Frontend Application Structure

App Entry Point and Routing

The main application entry point (web/src/App.tsx) initializes the React application with routing capabilities. The application uses client-side routing to navigate between different administrative sections.

Sources: web/src/App.tsx:1-50

Page Modules

The web interface is organized into several distinct page modules, each handling a specific domain of administrative functionality:

Sources: web/src/pages/Dashboard.tsx:1-30

Core Features

Dashboard

The Dashboard provides an at-a-glance view of the system status. It displays key metrics including version information, uptime statistics, connected platform count, and total project count.

// Key dashboard metrics displayed
<StatCard label={t('dashboard.version')} value={status?.version || '-'} accent />
<StatCard label={t('dashboard.uptime')} value={status ? formatUptime(status.uptime_seconds) : '-'} />
<StatCard label={t('dashboard.platforms')} value={status?.connected_platforms?.length ?? 0} />
<StatCard label={t('dashboard.projects')} value={status?.projects_count ?? 0} />

The dashboard also includes a projects section with quick navigation links to the full projects list.

Sources: web/src/pages/Dashboard.tsx:20-45

Project Management

Projects are the central organizational unit in cc-connect. The project management interface allows administrators to:

• Create new projects with the Add Project Wizard
• Configure platform integrations (Feishu, WeChat)
• Set up agent types and working directories
• View session counts and heartbeat status

#### Project List View

The project list displays all configured projects with key metadata including agent type, supported platforms, session count, and heartbeat status indicators.

// Project card displays key information
<Badge variant="info">{p.agent_type}</Badge>
{p.platforms?.slice(0, 3).map((pl) => <Badge key={pl}>{pl}</Badge>)}
<span>{p.sessions_count} {t('nav.sessions').toLowerCase()}</span>
{p.heartbeat_enabled && (
  <span className="flex items-center gap-1 text-emerald-500">
    <Heart size={12} /> {t('heartbeat.title')}
  </span>
)}

Sources: web/src/pages/Projects/ProjectList.tsx:1-80

#### Project Detail Settings

Individual project pages expose granular configuration options:

Sources: web/src/pages/Projects/ProjectDetail.tsx:1-50

#### Add Project Wizard

The wizard guides users through a multi-step setup process:

1. Name Step - Enter project name (alphanumeric, hyphen, underscore only)
2. Platform Step - Select integration platform (Feishu, WeChat, or manual setup)
3. QR Step - Generate QR code for mobile platform authentication
4. Form Step - Manual configuration form for advanced settings

// Project name validation
value={newProjName}
onChange={(e) => setNewProjName(e.target.value.replace(/[^a-zA-Z0-9_-]/g, ''))}

Sources: web/src/pages/Projects/ProjectList.tsx:80-120

Session Management

The Session List view provides a chronological view of all chat sessions across projects. Each session entry shows:

• Session name or ID
• Live status indicator
• Last activity timestamp
• Message preview (first 100 characters)
• Associated project and platform badges
• Message count

// Session display with live indicator
<MessageSquare size={14} className={s.live ? 'text-accent shrink-0' : 'text-gray-400 shrink-0'} />
<span className="text-sm font-medium text-gray-900 dark:text-white truncate">
  {s.name || s.user_name || s.id.slice(0, 8)}
</span>
{s.live && <Circle size={5} className="fill-emerald-500 text-emerald-500 shrink-0" />}

Sources: web/src/pages/Sessions/SessionList.tsx:1-60

Provider Administration

The Provider Management interface allows configuration of LLM agent providers with support for both global and per-project provider assignments.

#### Provider Features

• Model Selection - Configure base URL and model identifiers
• Multi-Model Support - Define model lists with default selection
• Thinking Control - Enable or disable extended thinking per provider
• Agent Type Filtering - Restrict providers to specific agent types

#### Provider Form Configuration

Sources: web/src/pages/Providers/ProviderList.tsx:1-100

#### CC-Switch Import

The interface supports importing provider configurations from CC-Switch, enabling migration of existing setups.

Skills Management

The Skills interface manages skill presets that can be assigned to projects. Skills define capabilities and behaviors for agents, with support for:

• Display name and description (with localization)
• Source tracking (URL, provider, author)
• Version information
• Pricing metadata
• Tag-based categorization

#### Recommended Skills

A preset grid displays available skill templates that administrators can add to their projects.

Cron Job Scheduling

The Cron List view administers scheduled tasks that execute prompts on projects at configured intervals.

// Cron job display includes mode, project, and timing
<Badge variant="outline" className="text-[10px] px-1.5 py-0">{job.mode || t('cron.modeDefault')}</Badge>
<span className="font-medium w-12 shrink-0 text-gray-400">{t('cron.project')}</span>
<span className="truncate">{job.project}</span>
<span className="font-medium w-12 shrink-0 text-gray-400">{t('cron.lastRun')}</span>
<span>{formatTime(job.last_run)}</span>

Sources: web/src/pages/Cron/CronList.tsx:1-50

API Client Layer

The frontend communicates with the backend through an API client module (web/src/api/index.ts). This layer abstracts HTTP communication and provides typed interfaces for all administrative operations.

Key API Operations

Sources: web/src/api/index.ts:1-100

Backend Server

Web Server Initialization

The Go backend initializes the web server with static file serving and API routing.

Sources: cmd/cc-connect/web.go:1-50

Web Manager

The core web manager handles the lifecycle of the web interface, including configuration, middleware setup, and request routing.

// Web server configuration structure
type WebConfig struct {
    Host     string
    Port     int
    TLS      bool
    CertFile string
    KeyFile  string
}

Sources: core/web_manager.go:1-80

Internationalization

The web interface supports multiple languages through an internationalization system defined in core/i18n.go. Supported languages include:

• English
• Simplified Chinese (简体中文)
• Traditional Chinese (繁體中文)
• Japanese (日本語)
• Spanish (Español)

The UI automatically detects the browser language and falls back to English when translations are unavailable.

User Interface Components

Common UI Elements

The interface uses a consistent component library including:

• Card - Container for grouped content
• Badge - Status indicators and labels
• Button - Action triggers with variants (primary, secondary, ghost)
• Modal - Dialog overlays for forms and confirmations
• Input - Form field components with validation
• Badge variants - default, outline, info, success for semantic coloring

Dark Mode Support

All components support dark mode theming through CSS custom properties and Tailwind dark variants:

// Example dark mode styling pattern
className="text-gray-900 dark:text-white bg-white dark:bg-white/[0.02]"
className="border-gray-200 dark:border-white/[0.06]"

Configuration and State Management

The frontend uses React hooks for state management with several key patterns:

1. Server State - Data fetched from the API (projects, sessions, providers)
2. UI State - Local component state (modals, forms, selections)
3. Preferences - User settings like language and theme

Key State Hooks

Security Considerations

The web interface handles sensitive operations including:

• API key management for provider configurations
• Project authentication credentials
• Session data access

All sensitive fields use password input types with visibility toggles:

<Input
  type={showKey ? 'text' : 'password'}
  value={form.api_key || ''}
  placeholder="sk-..."
/>
<button onClick={() => setShowKey(!showKey)}>
  {showKey ? <EyeOff size={16} /> : <Eye size={16} />}
</button>

Sources: web/src/pages/Providers/ProviderList.tsx:150-180

Data Flow Diagram

sequenceDiagram
    participant User
    participant ReactApp
    participant API
    participant GoBackend
    participant Database

    User->>ReactApp: Navigate to Projects
    ReactApp->>API: GET /api/projects
    API->>GoBackend: HTTP Request
    GoBackend->>Database: Query projects
    Database->>GoBackend: Project records
    GoBackend->>API: JSON response
    API->>ReactApp: Project list data
    ReactApp->>User: Render ProjectList

Conclusion

The Web UI Administration module provides a complete, production-ready administrative interface for cc-connect. Its modular design separates concerns across page components, while the typed API client ensures reliable communication with the backend. The support for dark mode, internationalization, and responsive design makes it suitable for deployment in varied operational environments.

Related Pages

Related topics: Quick Start Guide

Deployment and Operations

This page covers the operational aspects of cc-connect, including installation, daemon management, service configuration, and system-level integration.

Overview

cc-connect is a bridge application that connects local AI coding agents to messaging platforms. It supports multiple deployment scenarios ranging from manual binary execution to automated system service management across Linux (systemd), macOS (launchd), and Windows (Task Scheduler).

Sources: INSTALL.md

Installation Methods

cc-connect offers four primary installation approaches depending on your environment and requirements.

Package Manager Installation

macOS (Homebrew):

brew install cc-connect

Linux (Homebrew):

brew install cc-connect

Sources: INSTALL.md

Pre-built Binary Download

Download platform-specific binaries from the GitHub Releases page.

Installation Example (Linux):

curl -L -o cc-connect https://github.com/chenhg5/cc-connect/releases/latest/download/cc-connect-linux-amd64
chmod +x cc-connect
sudo mv cc-connect /usr/local/bin/

macOS Quarantine Removal:

xattr -d com.apple.quarantine cc-connect

Sources: INSTALL.md

Build from Source

Building from source requires Go 1.22 or later.

git clone https://github.com/chenhg5/cc-connect.git
cd cc-connect
make build
# Binary output: ./cc-connect

Sources: INSTALL.md

Configuration File Management

cc-connect searches for configuration files in the following order:

1. -config <path> flag (explicit path)
2. ./config.toml (current directory)
3. ~/.cc-connect/config.toml (global, recommended)

If no configuration file exists, running cc-connect will automatically create a starter template at ~/.cc-connect/config.toml.

Manual Configuration Setup

mkdir -p ~/.cc-connect
# Option 1: Copy example from cloned repo
cp config.example.toml ~/.cc-connect/config.toml
# Option 2: Run cc-connect once to auto-generate
cc-connect

Sources: INSTALL.md

Daemon Management

The daemon subsystem provides persistent background operation with automatic startup on system boot.

Installing the Daemon

Basic Installation:

cc-connect daemon install --config ~/.cc-connect/config.toml

Using Work Directory:

cc-connect daemon install --work-dir ~/.cc-connect

Installation Options:

Sources: cmd/cc-connect/daemon.go

Daemon Lifecycle Commands

cc-connect daemon start      # Start the service
cc-connect daemon stop       # Stop the service
cc-connect daemon restart    # Restart the service
cc-connect daemon status      # Check current status

Platform-Specific Implementation

The daemon manager delegates to platform-specific implementations:

• Linux: Creates a systemd user service Sources: daemon/systemd.go
• macOS: Creates a LaunchAgent plist
• Windows: Creates a Task Scheduler task named cc-connect

graph TD
    A[cc-connect daemon install] --> B{Platform Detection}
    B -->|Linux| C[systemd User Service]
    B -->|macOS| D[LaunchAgent Plist]
    B -->|Windows| E[Task Scheduler Task]
    C --> F[Auto-start on login]
    D --> F
    E --> G[Run at user logon]

Sources: daemon/manager.go

Log Management

Viewing Logs

cc-connect daemon logs              # Display current log
cc-connect daemon logs -f           # Follow mode (tail -f equivalent)
cc-connect daemon logs -n 100       # Show last 100 lines
cc-connect daemon logs --log-file /path/to/log  # Custom log file

Log Rotation

Logs automatically rotate when they reach the configured maximum size. The system maintains one backup of the previous log file.

Sources: INSTALL.md

Update Management

Update Command

The update subsystem handles binary updates with signature verification.

cc-connect update [options]

Update Options:

Update Process Flow

graph TD
    A[cc-connect update] --> B[Check Update Channel]
    B --> C{Fetch Latest Version}
    C -->|Version Available| D[Download Binary]
    C -->|Up to Date| E[Exit: Already current]
    D --> F{Verify Signature}
    F -->|Valid| G[Replace Binary]
    F -->|Invalid| H[Abort Update]
    G --> I[Restart Service]

Sources: cmd/cc-connect/update.go

Manual Update for Package Managers

Homebrew:

brew upgrade cc-connect

Source Users:

cd cc-connect
git pull
make build

After upgrading, restart the running cc-connect process to apply changes.

Sources: INSTALL.md

Process Execution Model

Privilege Escalation

The runas module handles process execution with appropriate privileges:

graph LR
    A[Main Process] -->|Non-elevated| B[User Context]
    A -->|Elevated tasks| C[runas Module]
    C -->|sudo/elevation| D[Privileged Execution]

The module supports:

• Running commands with elevated privileges when required
• Managing user context for different operation modes

Sources: core/runas.go

Operational Best Practices

Recommended Setup

1. Use Global Config Location: Store configuration at ~/.cc-connect/config.toml for consistent access across terminal sessions.

1. Install as System Service: Use daemon install for production deployments to ensure automatic restart on system reboot.

1. Configure Log Rotation: Set appropriate --log-max-size value based on expected message volume.

1. Monitor Log Output: Regularly check cc-connect daemon logs for operational insights and error tracking.

Configuration Structure

A typical multi-project production configuration:

[log]
level = "info"

[[projects]]
name = "backend"
[projects.agent]
type = "claudecode"
[projects.agent.options]
work_dir = "/path/to/backend"
mode = "default"

[[projects.platforms]]
type = "feishu"
[projects.platforms.options]
app_id = "cli_xxx"
app_secret = "xxx"

Health Monitoring

The daemon status command provides current service state:

cc-connect daemon status

This reports whether the service is running, and if applicable, the uptime and last activity timestamp.

Windows-Specific Considerations

On Windows, daemon install creates a Task Scheduler task that:

• Runs at user logon
• Starts immediately after installation
• Is named cc-connect in the Task Scheduler

Sources: INSTALL.md

Doramagic Pitfall Log

Doramagic extracted 16 source-linked risk signals. Review them before installing or handing real data to the project.

1. Installation risk: [Bug]

• Severity: high
• Finding: Installation risk is backed by a source signal: [Bug]. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/chenhg5/cc-connect/issues/933

2. Installation risk: Installation risk needs validation

• Severity: high
• Finding: Installation risk is backed by a source signal: Installation risk needs validation. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/chenhg5/cc-connect/issues/1058

3. Installation risk: [Feature] Preserve full interactive card schema on inbound

• Severity: high
• Finding: Installation risk is backed by a source signal: [Feature] Preserve full interactive card schema on inbound. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/chenhg5/cc-connect/issues/936

4. Installation risk: Installation risk needs validation

• Severity: high
• Finding: Installation risk is backed by a source signal: Installation risk needs validation. Treat it as a review item until the current version is checked.
• User impact: First-time setup may fail or require extra isolation and rollback planning.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/chenhg5/cc-connect/issues/960

5. Configuration risk: Feishu: all messages permanently ignored as 'old message after restart' after every daemon restart (v1.3.3-beta.2)

• Severity: high
• Finding: Configuration risk is backed by a source signal: Feishu: all messages permanently ignored as 'old message after restart' after every daemon restart (v1.3.3-beta.2). Treat it as a review item until the current version is checked.
• User impact: Users may get misleading failures or incomplete behavior unless configuration is checked carefully.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/chenhg5/cc-connect/issues/972

6. Configuration risk: WeChat ilink (weixin): image content is empty, not passed to agent

• Severity: high
• Finding: Configuration risk is backed by a source signal: WeChat ilink (weixin): image content is empty, not passed to agent. Treat it as a review item until the current version is checked.
• User impact: Users may get misleading failures or incomplete behavior unless configuration is checked carefully.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/chenhg5/cc-connect/issues/1057

7. Configuration risk: [Bug] cc-connect send uses default socket path in custom data_dir agent sessions

• Severity: high
• Finding: Configuration risk is backed by a source signal: [Bug] cc-connect send uses default socket path in custom data_dir agent sessions. Treat it as a review item until the current version is checked.
• User impact: Users may get misleading failures or incomplete behavior unless configuration is checked carefully.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/chenhg5/cc-connect/issues/966

8. Security or permission risk: Developers should check this security_permissions risk before relying on the project: [Bug] cc-connect send uses default socket path in custom data_dir agent sessions

• Severity: high
• Finding: Developers should check this security_permissions risk before relying on the project: [Bug] cc-connect send uses default socket path in custom data_dir agent sessions
• User impact: Developers may expose sensitive permissions or credentials: [Bug] cc-connect send uses default socket path in custom data_dir agent sessions
• Recommended check: Before packaging this project, run the relevant install/config/quickstart check for: [Bug] cc-connect send uses default socket path in custom data_dir agent sessions. Context: Observed during installation or first-run setup.
• Evidence: failure_mode_cluster:github_issue | fmev_d8aeb38642d53571d47292761cca7247 | https://github.com/chenhg5/cc-connect/issues/966 | [Bug] cc-connect send uses default socket path in custom data_dir agent sessions

9. Security or permission risk: Security or permission risk needs validation

• Severity: high
• Finding: Security or permission risk is backed by a source signal: Security or permission risk needs validation. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/chenhg5/cc-connect/issues/1054

10. Security or permission risk: Security or permission risk needs validation

• Severity: high
• Finding: Security or permission risk is backed by a source signal: Security or permission risk needs validation. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/chenhg5/cc-connect/issues/968

11. Security or permission risk: Security or permission risk needs validation

• Severity: high
• Finding: Security or permission risk is backed by a source signal: Security or permission risk needs validation. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/chenhg5/cc-connect/issues/1054

12. Security or permission risk: Security or permission risk needs validation

• Severity: high
• Finding: Security or permission risk is backed by a source signal: Security or permission risk needs validation. Treat it as a review item until the current version is checked.
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/chenhg5/cc-connect/issues/233

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using cc-connect with real data or production workflows.

• Community source 1 - github / github_issue
• WeChat ilink (weixin): image content is empty, not passed to agent - github / github_issue
• Community source 3 - github / github_issue
• Community source 4 - github / github_issue
• [[Bug] cc-connect send uses default socket path in custom data_dir agent](https://github.com/chenhg5/cc-connect/issues/966) - github / github_issue
• Community source 6 - github / github_issue
• [[Bug] cursorSession error: unknown option '--trust](https://github.com/chenhg5/cc-connect/issues/923) - github / github_issue
• [[Feature] Preserve full interactive card schema on inbound](https://github.com/chenhg5/cc-connect/issues/936) - github / github_issue
• [[Bug]](https://github.com/chenhg5/cc-connect/issues/933) - github / github_issue
• Feishu: all messages permanently ignored as 'old message after restart' - github / github_issue
• Community source 11 - github / github_issue