### Start Proxy with Host and Port Options

Source: https://github.com/kaitranntt/ccs/blob/main/docs/openai-compatible-providers.md

Start the proxy with specific host and port configurations. This allows for precise control over network binding.

```bash
ccs proxy start hf --host 127.0.0.1
```

```bash
ccs proxy start hf --port 3460
```

--------------------------------

### Install and Launch CCS Bar Immediately

Source: https://github.com/kaitranntt/ccs/blob/main/docs/ccs-bar.md

Installs CCS Bar and launches it immediately without prompting the user. This is useful for automated setups or immediate use after installation.

```bash
ccs bar install --launch
```

--------------------------------

### Start, Activate, and Stop Proxy

Source: https://github.com/kaitranntt/ccs/blob/main/docs/openai-compatible-providers.md

Manually manage the proxy lifecycle. Use 'start' to begin, 'activate' to set up environment variables, and 'stop' to terminate.

```bash
ccs proxy start hf
eval "$(ccs proxy activate)"
ccs proxy status
ccs proxy stop
```

--------------------------------

### Install and Configure CCS

Source: https://github.com/kaitranntt/ccs/blob/main/README.md

Install the CCS CLI globally using npm and run the initial configuration command.

```bash
npm install -g @kaitranntt/ccs
ccs config
```

--------------------------------

### Runtime Entrypoint Shim Examples

Source: https://github.com/kaitranntt/ccs/blob/main/docs/system-architecture/target-adapters.md

Shows how dedicated bin shims can be used to specify the target runtime entrypoint.

```bash
ccs-droid / ccsd → droid
```

```bash
ccs-codex / ccsx → codex
```

```bash
ccsxp → codex, then prepends `--config model_provider="cliproxy"`
```

--------------------------------

### argv[0] Detection Examples

Source: https://github.com/kaitranntt/ccs/blob/main/docs/system-architecture/target-adapters.md

Illustrates how the binary name or custom aliases are used to map to target adapters.

```bash
ccs-droid (explicit alias) → droid
```

```bash
ccsd (legacy shortcut) → droid
```

```bash
ccs-codex (explicit alias) → codex
```

```bash
ccs-x (short alias) → codex
```

```bash
ccs (regular command) → default
```

--------------------------------

### CLI Browser Commands

Source: https://github.com/kaitranntt/ccs/blob/main/docs/browser-automation.md

Use these commands for setting up, checking status, troubleshooting, and managing browser policy for CCS. The `setup` command is the primary one-command setup path.

```bash
ccs help browser
ccs browser setup
ccs browser status
ccs browser doctor
ccs browser policy
ccs browser policy --all manual
```

--------------------------------

### Starting UI Development Server from ui/ Directory

Source: https://github.com/kaitranntt/ccs/blob/main/ui/README.md

Navigate to the 'ui/' directory and run the development server for frontend-only development.

```bash
cd ui
bun run dev
```

--------------------------------

### Per-Profile Config Example

Source: https://github.com/kaitranntt/ccs/blob/main/docs/system-architecture/target-adapters.md

Shows how a target can be specified within a profile configuration file.

```yaml
profiles:
      glm:
        target: droid
```

--------------------------------

### Install OpenCode LLM CLI

Source: https://github.com/kaitranntt/ccs/blob/main/docs/websearch.md

This command installs the OpenCode LLM CLI. Ensure you have bash and curl installed to execute the installation script.

```bash
curl -fsSL https://opencode.ai/install | bash
```

--------------------------------

### Install Grok CLI

Source: https://github.com/kaitranntt/ccs/blob/main/docs/websearch.md

Install the Grok CLI using npm. This command requires Node.js and npm to be installed on your system.

```bash
npm i -g @vibe-kit/grok-cli
```

--------------------------------

### Install Antigravity (agy) CLI

Source: https://github.com/kaitranntt/ccs/blob/main/docs/websearch.md

Use this command to install the Antigravity (agy) CLI, recommended as an LLM CLI fallback. This script fetches and installs the necessary components.

```bash
curl -fsSL https://antigravity.google/cli/install.sh | bash
```

--------------------------------

### Conventional Commit Examples (Bash)

Source: https://github.com/kaitranntt/ccs/blob/main/docs/code-standards.md

Demonstrates the correct format for conventional commit messages, including type, scope, and description. Incorrect examples are also shown for clarity.

```bash
# Correct
git commit -m "feat(cliproxy): add OAuth token refresh"
git commit -m "fix(doctor): handle missing config gracefully"
git commit -m "refactor(ui): split provider-editor into modules"

# Incorrect - REJECTED
git commit -m "added new feature"
git commit -m "Fixed bug"
```

--------------------------------

### System-wide Installation for Fish Shell Completion

Source: https://github.com/kaitranntt/ccs/blob/main/scripts/completion/README.md

Installs the CCS completion script system-wide for Fish. Requires sudo privileges.

```fish
sudo cp scripts/completion/ccs.fish /usr/share/fish/vendor_completions.d/
```

--------------------------------

### CLI Target Flag Example

Source: https://github.com/kaitranntt/ccs/blob/main/docs/system-architecture/target-adapters.md

Demonstrates how to specify a target adapter using the --target flag in the CLI.

```bash
ccs --target droid glm
```

```bash
ccs --target codex
```

--------------------------------

### Starting the CCS Development Server

Source: https://github.com/kaitranntt/ccs/blob/main/ui/README.md

Start the CCS server and open a local browser URL for the dashboard. This command also prints bind/network details and an auth reminder if applicable.

```bash
bun run dev
```

--------------------------------

### Conventional Commit Examples

Source: https://github.com/kaitranntt/ccs/blob/main/CONTRIBUTING.md

Examples of correctly formatted conventional commits for various types of changes.

```bash
git commit -m "fix(doctor): handle missing config gracefully"
git commit -m "feat(cliproxy): add provider quota check"
git commit -m "docs(contributing): simplify contributor workflow"
```

```bash
git commit -m "fix stuff"
git commit -m "WIP"
git commit -m "update file"
```

--------------------------------

### Run Native Unix Tests (Bash)

Source: https://github.com/kaitranntt/ccs/blob/main/tests/README.md

Execute native installation tests on Unix-like systems using bash scripts. This verifies the native installation process.

```bash
bun run test:native
```

--------------------------------

### Basic CCS Command Completion Example

Source: https://github.com/kaitranntt/ccs/blob/main/scripts/completion/README.md

Demonstrates how tab completion suggests root commands and help topics.

```bash
$ ccs <TAB>
auth      api       cliproxy  config    doctor    docker    help
```

```bash
$ ccs help <TAB>
profiles  providers  completion  targets
```

--------------------------------

### Dashboard Auth Configuration Example

Source: https://github.com/kaitranntt/ccs/blob/main/docs/dashboard-auth-cli.md

Example configuration for dashboard authentication in `~/.ccs/config.yaml`. This includes enabling auth, setting username, and providing a password hash.

```yaml
# Dashboard Auth: Optional login protection for CCS dashboard
# Generate password hash: npx bcrypt-cli hash "your-password"
# ENV override: CCS_DASHBOARD_AUTH_ENABLED, CCS_DASHBOARD_USERNAME, CCS_DASHBOARD_PASSWORD_HASH
dashboard_auth:
  enabled: true
  username: "admin"
  password_hash: "$2b$10$..."
  session_timeout_hours: 24
```

--------------------------------

### Start Local Proxy Explicitly

Source: https://github.com/kaitranntt/ccs/blob/main/docs/openai-compatible-providers.md

Starts the local proxy explicitly for a given profile. This command can also be used to pin a one-off port for the proxy.

```bash
ccs proxy start <profile>
```

```bash
ccs proxy start hf --port 3460
```

--------------------------------

### Setup Dashboard Authentication

Source: https://github.com/kaitranntt/ccs/blob/main/docs/dashboard-auth-cli.md

Use this command to interactively set up username and password for dashboard access. The password will be hashed with bcrypt.

```bash
$ ccs config auth setup

╭─────────────────────────────────╮
│  Dashboard Auth Setup           │
╰─────────────────────────────────╯

[i] Configure username and password for dashboard access.
    Password will be hashed with bcrypt before storage.

Username
Enter username: admin

Password
    Minimum 8 characters
Enter password: ********
Confirm password: ********

[i] Hashing password...

[OK] Dashboard authentication configured

[i] Settings saved to ~/.ccs/config.yaml
[i] Username: admin
[i] Session timeout: 24 hours

    Start dashboard: ccs config
    Show status: ccs config auth show
    Disable auth: ccs config auth disable

```

--------------------------------

### Clone and Install CCS Dependencies

Source: https://github.com/kaitranntt/ccs/blob/main/CONTRIBUTING.md

Follow these steps to clone the CCS repository, set up remotes, switch to the development branch, pull upstream changes, and install project dependencies for both the main project and the UI.

```bash
git clone https://github.com/YOUR_USERNAME/ccs.git
cd ccs
git remote add upstream https://github.com/kaitranntt/ccs.git

git checkout dev
git pull upstream dev

bun install
cd ui && bun install && cd ..
```

--------------------------------

### User Installation for Fish Shell Completion

Source: https://github.com/kaitranntt/ccs/blob/main/scripts/completion/README.md

Fish automatically loads completions from ~/.config/fish/completions/. Copy the CCS completion script to this directory.

```fish
# Create completion directory if it doesn't exist
mkdir -p ~/.config/fish/completions
```

```fish
# Copy completion script
cp scripts/completion/ccs.fish ~/.config/fish/completions/
```

--------------------------------

### CCS Backend Contract Example

Source: https://github.com/kaitranntt/ccs/blob/main/scripts/completion/README.md

Illustrates direct interaction with the `ccs __complete` backend for shell completion suggestions.

```bash
$ ccs __complete --shell bash --current do
doctor
docker
```

--------------------------------

### Context-Aware CCS Command Completion Example

Source: https://github.com/kaitranntt/ccs/blob/main/scripts/completion/README.md

Shows how tab completion provides relevant options based on the current command context.

```bash
$ ccs auth show <TAB>
work      personal  team      --json
```

```bash
$ ccs api <TAB>
create    list      discover  copy    export  import  remove
```

--------------------------------

### Starting CCS Development Server for Local-Only Access

Source: https://github.com/kaitranntt/ccs/blob/main/ui/README.md

Run the CCS development server with host set to 127.0.0.1 for local-only development.

```bash
bun run dev -- --host 127.0.0.1
```

--------------------------------

### Install CCS Bar Without Launch Prompt

Source: https://github.com/kaitranntt/ccs/blob/main/docs/ccs-bar.md

Installs CCS Bar and suppresses the prompt to launch it immediately. This allows for installation without user interaction for launching.

```bash
ccs bar install --no-launch
```

--------------------------------

### Start CCS and Application Containers

Source: https://github.com/kaitranntt/ccs/blob/main/docker/README.md

Commands to start the CCS stack and your application container using Docker Compose. Ensure CCS is started first to create the 'ccs-net' network.

```bash
docker compose -f docker/compose.yaml up -d   # or: ccs docker up
docker compose -f my-app/compose.yaml up -d
```

--------------------------------

### Start Local Daemon

Source: https://github.com/kaitranntt/ccs/blob/main/docs/cursor-integration.md

Start the local CCS daemon that acts as a bridge for Cursor IDE.

```bash
ccs legacy cursor start
```

--------------------------------

### Show, Backup, and Set Existing Account

Source: https://github.com/kaitranntt/ccs/blob/main/docs/session-sharing-technical-analysis.md

Demonstrates the workflow for an existing account ('ck'). It shows the account details, backs up the default lane, and then sets the 'ck' account as the new default for plain `ccs` sessions.

```bash
ccs auth show ck
ccs auth backup default
ccs auth default ck
```

--------------------------------

### Start the new Docker stack

Source: https://github.com/kaitranntt/ccs/blob/main/docker/README.md

Start the new stack in detached mode using `docker compose up -d`.

```bash
docker compose up -d
```

--------------------------------

### Adapter Registration at Startup

Source: https://github.com/kaitranntt/ccs/blob/main/docs/system-architecture/target-adapters.md

Demonstrates how to register different target adapters when the application initializes. Ensure adapter classes are imported and instantiated before calling `registerTarget`.

```typescript
// src/ccs.ts (initialization)

registerTarget(new ClaudeAdapter());
registerTarget(new DroidAdapter());
registerTarget(new CodexAdapter());
```

--------------------------------

### Codex Runtime Entrypoints

Source: https://github.com/kaitranntt/ccs/blob/main/docs/system-architecture/target-adapters.md

Illustrates the built-in package bin entrypoints for Codex runtime and the 'ccsx' command, including environment variables and target routing. Also shows how to use custom shims with environment variable aliases for target resolution.

```bash
# Built-in package bin entrypoints
ccs-codex
→ dist/bin/codex-runtime.js
→ CCS_INTERNAL_ENTRY_TARGET=codex

ccsx
→ dist/bin/codex-runtime.js
→ CCS_INTERNAL_ENTRY_TARGET=codex
→ passes native Codex diagnostics plus known upstream Codex subcommands and aliases through before CCS profile detection
→ reserves CCS-owned `auth`, `doctor`, and `update`

ccsxp
→ dist/bin/ccsxp-runtime.js
→ CCS_INTERNAL_ENTRY_TARGET=codex
→ injects native `model_provider="cliproxy"` override
→ pins CODEX_HOME to native `~/.codex` unless `CCSXP_CODEX_HOME` is set
→ repairs `[model_providers.cliproxy]` in the active Codex `config.toml`
→ preserves valid custom `base_url` values for remote or non-default CLIProxy endpoints
→ injects the effective CCS CLIProxy auth token into the provider's configured `env_key`
→ ignores the configured CCS default account/profile and stays in native Codex default mode
```

```bash
ln -s /path/to/ccs /path/to/mycodex
CCS_TARGET_ALIASES='codex=mycodex'
# Legacy fallback:
CCS_CODEX_ALIASES='mycodex'
```

--------------------------------

### Start CCS Stack to Create Network

Source: https://github.com/kaitranntt/ccs/blob/main/docker/README.md

Command to start the CCS stack using Docker Compose, which creates the 'ccs-net' network. This is necessary if the network is not found.

```bash
docker compose -f docker/compose.yaml up -d
# or: ccs docker up
```

--------------------------------

### Configuration File Setup

Source: https://github.com/kaitranntt/ccs/blob/main/docs/browser-automation.md

Configure browser automation settings by editing the `~/.ccs/config.yaml` file. This allows for manual control over enabling browser lanes and setting specific parameters like user data directories and DevTools ports.

```yaml
browser:
  claude:
    enabled: false
    policy: manual
    user_data_dir: "~/.ccs/browser/chrome-user-data"
    devtools_port: 9222
  codex:
    enabled: false
    policy: manual
```

--------------------------------

### Install CCS CLI Globally

Source: https://github.com/kaitranntt/ccs/blob/main/docs/system-architecture/index.md

Installs the CCS command-line interface globally using npm. This command also sets up runtime aliases and creates a configuration directory on the first run.

```bash
npm install -g @kaitranntt/ccs
```

--------------------------------

### Get Help for Docker CLI Tools

Source: https://github.com/kaitranntt/ccs/blob/main/docker/README.md

Displays the help information for the Claude and Gemini command-line tools inside the Docker container. Use this to understand available options and configurations.

```bash
docker exec -it ccs-dashboard claude --help
```

```bash
docker exec -it ccs-dashboard gemini --help
```

--------------------------------

### CCS Bar Configuration Example

Source: https://github.com/kaitranntt/ccs/blob/main/docs/ccs-bar.md

An example of the `bar.json` configuration file. This file is used by the CCS Bar app to discover the running server, specifying its base URL, port, and authentication mode.

```json
{ "baseUrl": "http://127.0.0.1:3000", "port": 3000, "authMode": "loopback" }
```

--------------------------------

### Install CCS Bar for macOS

Source: https://github.com/kaitranntt/ccs/blob/main/README.md

Use this command to install the CCS Bar application on your macOS system. This application provides quick access to subscription quotas, daily spending, and account controls directly from the menu bar.

```bash
ccs bar install
```

--------------------------------

### Common development workflows

Source: https://github.com/kaitranntt/ccs/blob/main/CONTRIBUTING.md

Execute these commands from the repository root to manage the build process, start the local config dashboard, and manage symlinks for global CCS.

```bash
bun run build            # Compile CLI
```

```bash
bun run dev              # Build server and start local config dashboard
```

```bash
bun run dev:symlink      # Point global ccs to local build
```

```bash
bun run dev:unlink       # Restore original global ccs
```

```bash
cd ui && bun run dev     # Dashboard-only dev server
```

--------------------------------

### Ollama / Local Gateways Provider Setup

Source: https://github.com/kaitranntt/ccs/blob/main/docs/openai-compatible-providers.md

Configure Ollama or other local gateways for AI model access. This setup requires specifying the local base URL, a placeholder auth token, the model, and the CCS provider type. For self-signed HTTPS, set CCS_OPENAI_PROXY_INSECURE to 1.

```json
{
  "env": {
    "ANTHROPIC_BASE_URL": "http://127.0.0.1:11434",
    "ANTHROPIC_AUTH_TOKEN": "ollama",
    "ANTHROPIC_MODEL": "qwen3-coder",
    "CCS_DROID_PROVIDER": "generic-chat-completion-api"
  }
}
```

--------------------------------

### Configuration Priority Pattern (TypeScript)

Source: https://github.com/kaitranntt/ccs/blob/main/docs/code-standards.md

Illustrates the recommended pattern for resolving configuration from multiple sources, prioritizing CLI flags over environment variables, config files, and defaults.

```typescript
// proxy-config-resolver.ts pattern
// Priority: CLI flags > Environment variables > config.yaml > defaults

const resolved = {
  ...DEFAULT_CONFIG,                    // 4. Defaults (lowest)
  ...yamlConfig,                        // 3. config.yaml
  ...envConfig,                         // 2. Environment variables
  ...cliFlags,                          // 1. CLI flags (highest)
};

```

--------------------------------

### Example Structured Log Entry

Source: https://github.com/kaitranntt/ccs/blob/main/docs/logging-contract.md

This is an example of a structured JSONL log entry conforming to the defined schema. It includes essential fields like ID, timestamp, level, source, event, message, process ID, run ID, and optional fields such as requestId, stage, and context.

```jsonl
{"id":"...","timestamp":"2026-04-30T12:34:56.000Z","level":"info","source":"proxy:openai-compat:messages","event":"request.received","message":"Proxy /v1/messages request received","processId":42,"runId":"r1","requestId":"a1b2...","stage":"intake","context":{"method":"POST"}}
```