Skip to main content

​
Your First CCS Session

Complete end-to-end guide for your first CCS experience. We’ll use Gemini (free tier available), but steps apply to all providers.

​
Prerequisites

Before starting, ensure you have: 
# Check CCS is installed
ccs --version

# If not installed:
npm install -g @kaitranntt/ccs

​
Step 1: Choose Your Provider

CCS supports 9 providers across 3 categories: For this guide, we’ll use Gemini (free tier).

​
Step 2: First Authentication

​
Run Your First Command

Simply run CCS with the provider name: 
ccs gemini "explain what CCS does"
What happens:
1

Browser Opens Automatically

CCS spawns local OAuth server and opens browser to Google login
2

Google Sign-In

Sign in with any Google account (personal Gmail works for free tier)
3

OAuth Callback

Browser redirects back to CCS with authentication token
4

Token Saved

OAuth credentials cached at ~/.ccs/cliproxy/auth/
5

Session Starts

CCS executes your prompt using Claude Code interface with Gemini backend

​
Visual Guide

OAuth Authentication Flow
First-time setup: On first run with Gemini, you’ll be prompted to select a model (Gemini 2.5 Pro for free tier, Gemini 3 Pro for paid accounts). Choose “Gemini 2.5 Pro” if using free Google account.

​
Step 3: Run Your First Query

After authentication completes, you’ll see the Claude Code interface: 
ccs gemini "show me how to create a React component"

# CCS starts interactive session:
# Claude Code CLI v0.x.x
# Model: Gemini 2.5 Pro
#
# [Response appears here with code examples]

​
Interactive Mode

By default, CCS runs in interactive mode - you can continue the conversation: 
You: show me how to create a React component

Claude: [Provides React component code]

You: now add TypeScript types

Claude: [Updates code with TypeScript]

You: /exit
# Session ends

​
One-Shot Mode

For single queries without starting interactive session: 
# Execute and exit
ccs gemini "what is React?" --one-shot

# Or use quotes only (auto-exits after response)
ccs gemini "quick question: what is JSX?"

​
Step 4: Understanding Session Persistence

CCS sessions persist until you explicitly exit:

​
Session State

What's Saved

  • Conversation history
  • File context (if working in project)
  • Environment variables
  • Active skills/commands

What's Not Saved

  • Interactive chat after exit
  • Unsaved file edits
  • Terminal state
  • Background processes

​
Session Commands

# Check session status
/status

# List active files in context
/files

# Clear conversation history
/clear

# Exit session
/exit
# or: Ctrl+C

​
Session Isolation

Each provider runs isolated sessions: 
# Terminal 1: Gemini session
ccs gemini "task A"

# Terminal 2: Codex session (separate history)
ccs codex "task B"

# Both run independently
Running same provider in multiple terminals shares session state and may cause conflicts. Use different providers or Claude account profiles for concurrent work.

​
Step 5: Switching Between Accounts (Same Provider)

Add multiple Google accounts to Gemini provider:
1

Add Second Account

ccs gemini --auth --add
# Browser opens - sign in with different Google account
2

List All Accounts

ccs gemini --accounts

# Output:
# Available Gemini accounts:
# * john (john@gmail.com) - default
#   work (alice@company.com)
3

Switch Default Account

ccs gemini --use work
# Now `ccs gemini` uses work account by default
4

Use Specific Account Once

# Override default for single query
ccs gemini --account work "check company docs"

​
Account Nicknames

Accounts auto-nicknamed from email prefix, or customize: 
# Auto: john@gmail.com → "john"
ccs gemini --accounts

# Custom nickname
ccs gemini --nickname personal
# Account renamed: john → personal

​
Step 6: Basic Troubleshooting

​
Browser Doesn’t Open

Problem: OAuth flow stuck waiting for browser Solution 1: Headless Mode 
ccs gemini --headless

# Output shows URL to open manually:
# Open this URL on any device:
# https://accounts.google.com/o/oauth2/auth?...
#
# Waiting for authentication...
Solution 2: Check System Browser 
# Ensure default browser configured
xdg-settings get default-web-browser  # Linux
# or
open -a "Google Chrome"                # macOS

​
Authentication Fails

Problem: Browser completes login but CCS shows error Solution: 
# Clear existing tokens and retry
ccs gemini --logout
ccs gemini --auth

​
Wrong Account Used

Problem: CCS uses unexpected Google account Solution: 
# Check which account is default
ccs gemini --accounts

# Switch to correct account
ccs gemini --use john

​
Model Selection Error

Problem: “Model not supported” or tool call failures Solution: 
# Reconfigure model (choose "Gemini 2.5 Pro" for free tier)
ccs gemini --config

# Interactive prompt:
# 1. Gemini 3 Pro (High) - Paid tier
# 2. Gemini 2.5 Pro - Free tier ✓
# Select model [1-2]: 2

​
Token Expired Mid-Session

Problem: UND_ERR_SOCKET errors during execution Solution: Token refresh is automatic (5 min before expiry). If error persists: 
ccs gemini --logout
ccs gemini --auth

​
Next Steps

Provider Comparison

Compare all 9 providers and choose the best for your needs

Multiple Claude Accounts

Set up work/personal Claude subscriptions

Model Configuration

Configure Gemini models (2.5 Pro vs 3 Pro)

CLI Commands Reference

Full command reference and flags

​
Quick Reference

​
Common Commands

# Execute query (auto-starts interactive session)
ccs gemini "your prompt"

# One-shot execution (no interactive mode)
ccs gemini "quick question" --one-shot

# Authentication only (no session)
ccs gemini --auth

# Add new account (preserves existing)
ccs gemini --auth --add

# List accounts
ccs gemini --accounts

# Switch default account
ccs gemini --use work

# Configure model
ccs gemini --config

# Logout (clear tokens)
ccs gemini --logout

# Headless mode (manual URL)
ccs gemini --headless

​
Session Commands (During Interactive Mode)

/status       # Show current session info
/files        # List files in context
/clear        # Clear conversation history
/help         # Show available commands
/exit         # Exit session (or Ctrl+C)

​
Storage Locations

PathDescription
~/.ccs/cliproxy/auth/OAuth tokens (one file per account)
~/.ccs/cliproxy/accounts.jsonAccount registry and nicknames
~/.ccs/cliproxy/sessions.jsonActive session tracking
~/.ccs/gemini.settings.jsonModel selection preferences
~/.ccs/config.yamlGlobal CCS configuration

​
Congratulations!

You’ve completed your first CCS session. You can now:
  • ✅ Authenticate with OAuth providers
  • ✅ Run queries and start interactive sessions
  • ✅ Manage multiple accounts per provider
  • ✅ Switch between providers
  • ✅ Troubleshoot common issues
Explore other providers or dive deeper into advanced features:
  • 7 OAuth Providers: Zero API keys, just browser login
  • Multiple Claude Accounts: Work/personal separation with concurrent sessions
  • API Profiles: Custom endpoints and self-hosted models
  • Remote Proxy: Connect to external CLIProxy servers
  • WebSearch Integration: Live web search in prompts