CCEM

CCEM

One control center for Claude Code, Codex, OpenCode and every model behind them.

Website | English | 中文

Table of Contents

• Why ccem
• Highlights
• Quick Start
• CLI
• Desktop App
• External Control: JSON-RPC, Deeplinks & CLI
• How ccem Compares
• Data Storage
• Agent Data & Sign-in
• Tech Stack
• Contributing
• License

Why ccem

Claude Code is great. Using it seriously every day is where things get messy.

• Model sprawl. KIMI for frontend, DeepSeek for scripts, GLM for refactors, a local Ollama model on the plane. Each switch means hand-exporting env vars, and eight terminal tabs later nobody knows which tab talks to which provider.
• Your best model doing busywork. Claude or Codex burns top-tier tokens renaming config keys and writing boilerplate tests.
• Permission fatigue. Clicking Approve 200 times a day wears you out. --dangerously-skip-permissions feels like a bad idea next to your .env.
• No idea what you spent. Claude Code, Codex and OpenCode each keep their own logs. Nothing adds them up.
• You're away from your desk. You're out getting coffee, a test is red, and your laptop is at home.
• The work that should run itself. Nightly test runs, a Monday PR sweep, a changelog every Friday, with the results sent to your phone.

ccem handles all of it. It's a free, open-source CLI plus a native Tauri desktop app that switches models in one keystroke, sets permissions with one word, lets the Claude and Codex apps hand routine tasks to cheaper models, routes subagents the same way, tracks every token, runs cron jobs, and lets you continue a session from Telegram, WeChat, WeCom or Feishu.

Highlights

The CLI and Desktop read the same config file (~/.ccem/config.json), so an environment you add in one shows up in the other immediately.

Quick Start

CLI: 30 seconds, no install

npx ccem              # Interactive menu

Or install it globally:

npm install -g ccem
ccem add kimi         # Name it, pick the KIMI preset, paste your key
ccem use kimi         # Switch to it
ccem dev              # Launch Claude Code in "dev" permission mode

Desktop

Download from GitHub Releases:

• macOS: .dmg for Apple Silicon (aarch64) and Intel (x86_64)
• Windows: .exe installer (x64)

Open it, add an environment, pick Claude, Codex or OpenCode, describe your task, and press Cmd+Enter.

CLI

Everything you need from the terminal: environments, permissions, usage, skills, cron, DeepSeek Harness, tmux sessions, and remote control of a running Desktop app.

Install

npm install -g ccem
# or: pnpm add -g ccem
# or just: npx ccem

Environment Management

ccem              # Interactive menu
ccem add kimi     # Name an environment, then choose a preset or enter settings
ccem use kimi     # Switch environment
ccem ls           # List all environments
ccem current      # Show active environment
ccem env          # Print export commands (pipe-friendly)
ccem env --json   # Same, as JSON
ccem run <cmd>    # Run any command with the env vars injected
ccem del <name>   # Delete
ccem rename <a> <b>
ccem cp <src> <dst>

Built-in Presets

Each preset fills in the base URL and maps Claude Code's Opus / Sonnet / Haiku tiers to that provider's models (ANTHROPIC_DEFAULT_OPUS_MODEL, …_SONNET_MODEL, …_HAIKU_MODEL), with ANTHROPIC_MODEL=opus. Claude Code's /model picker and its subagents then use the right model for each tier.

Any other Anthropic-compatible endpoint works too: just enter the base URL, key and models yourself. API keys are encrypted at rest.

Shell Integration

ccem use can't change the env vars of the shell you're already in. Either prefix commands with ccem run, or add this to ~/.zshrc:

ccem() {
  command ccem "$@"
  local exit_code=$?
  if [[ $exit_code -eq 0 ]]; then
    if [[ "$1" == "use" || -z "$1" ]]; then
      eval "$(command ccem env)"
    fi
  fi
  return $exit_code
}

Then source ~/.zshrc.

Permission Modes

Five presets that sit between "approve everything" and "approve nothing".

ccem yolo | auto | dev | readonly | safe           # Apply temporarily; reverted when Claude Code exits
ccem setup perms --dev                           # Write it into the project's .claude/settings.json
ccem setup default-mode --dev                    # Make it the default
ccem --mode                                      # Show the current mode
ccem --list-modes                                # Show all modes

The retired ci and audit modes still resolve: saved defaults and API callers that use them get safe and readonly.

Usage Analytics

ccem usage          # Interactive view with a calendar heatmap
ccem usage --json   # Machine-readable

ccem parses Claude Code's JSONL logs from the CCEM profile (~/.ccem/agents/claude/projects/) and the official ~/.claude/projects/, and calculates tokens and cost from cached LiteLLM model prices.

Skill Management

ccem skill add              # Interactive picker (Tab switches groups)
ccem skill add <name>       # Install a preset
ccem skill add <github-url> # Install from any GitHub repo or subfolder
ccem skill ls               # List installed skills
ccem skill rm <name>        # Remove

Official presets (16): frontend-design, skill-creator, web-artifacts-builder, canvas-design, algorithmic-art, theme-factory, mcp-builder, webapp-testing, pdf, docx, pptx, xlsx, brand-guidelines, doc-coauthoring, internal-comms, slack-gif-creator

Curated community skills: superpowers, ui-ux-pro-max, Humanizer-zh, skill-writer

ccem also ships skills that teach Claude Code to use ccem itself:

ccem setup cron       # Installs the ccem-cron skill: Claude can schedule tasks for you
ccem setup bot-bind   # Installs the ccem-bot-bind skill: Claude can attach a session to a chat bot

Agent Profiles & Sign-in

Claude Code launched through ccem uses its own profile, so your official Claude Code setup is left alone. Codex shares the official profile by default. See Agent Data & Sign-in for details.

ccem auth claude      # Sign in to the CCEM Claude Code profile (for an official subscription)
ccem auth codex       # Sign in to whichever Codex profile is selected

API keys from your ccem environments work without signing in.

DeepSeek Harness (dsh)

Run a ccem environment through DeepSeek Harness, a separate agent runtime. ccem converts your environment into a dsh provider config, mapping the Opus/Sonnet/Haiku tiers to models, so the same keys work in both runtimes.

ccem dsh doctor                       # Offline readiness check: binary, versions, config
ccem dsh inspect --env deepseek       # Preview the dsh provider config (secrets redacted)
ccem dsh run --tier sonnet "fix the flaky test in auth.spec.ts"

run accepts --env, --tier opus|sonnet|haiku, --model, --cwd and --permission read-only|workspace-write|danger-full-access. Desktop release builds bundle dsh, and its sessions appear in the History page under DeepSeek.

tmux Sessions

When tmux is installed, interactive sessions run inside tmux, so you can pick them up from any terminal:

ccem sessions         # List tmux-backed interactive sessions
ccem attach [id]      # Attach to one in your terminal

Team Config Sharing

Distribute API configurations to your team over an encrypted channel:

ccem load https://your-server.com/api/env --key YOUR_KEY --secret YOUR_SECRET
# or keep secrets out of shell history:
echo '{"key":"…","secret":"…"}' | ccem load https://your-server.com/api/env --credentials-stdin

A ready-to-deploy server lives in server/. It uses AES-256-GCM authenticated envelopes and rate limiting, and ships with an example config and a PM2 ecosystem file.

Scheduled Tasks from the CLI

ccem cron create --name weekday-review --schedule '0 9 * * 1-5' \
  --prompt 'Inspect this project and summarize issues that need attention' \
  --execution-profile conservative --disabled --json
ccem cron list --json
ccem cron trigger weekday-review      # Run it now via the running Desktop app
ccem cron delete weekday-review
ccem cron notification-targets        # Show where results can be delivered

Other options: --working-dir, --env-name, --max-budget-usd, --allowed-tools, --disallowed-tools, --timeout-secs, --template-id, --from-json, and --wecom-result / --wecom-bot-id / --wecom-peer-id to send results to WeCom. Scheduled runs fire from the Desktop scheduler. The CLI writes the task record, and trigger asks the running Desktop to run it.

Drive Desktop from the CLI

This is also how the Claude and Codex apps delegate work. Install the CCEM agent skill (Settings → Agent Skill) and they run these commands themselves: keep planning in the app you're talking to, start a session on a cheaper environment for the routine part, then read its events and send follow-ups.

With the Desktop app running:

ccem desktop health --json
ccem desktop create --provider claude --cwd "$PWD" --env deepseek \
  --prompt "write auth tests" --perm dev --json        # Start a background session
ccem desktop sessions --cwd . --status running --json
ccem desktop status <runtimeId> --json
ccem desktop events <runtimeId> --since 0 --limit 50 --json
ccem desktop send <runtimeId> --text "now add tests"   # Send input, idempotent with --message-id
ccem desktop routes <runtimeId> --set Explore=glm      # Re-bind a routing key mid-session
ccem desktop open 'ccem://workspace/session?…'         # Focus a session in Desktop

CLI Command Reference

Desktop App

A native app built on Tauri 2 (a Rust backend and a React frontend, not an Electron wrapper) for macOS and Windows. Everything the CLI does, plus a full workspace for running agents.

Workspace: Claude Code, Codex & OpenCode in One Place

The Workspace isn't just a launcher. It's where you start, steer and review agent runs.

• Three agents: start a Claude Code, Codex or OpenCode session from the same composer. Claude and Codex run in the native GUI. OpenCode sessions open in OpenCode Web.
• A detailed composer: $skill tokens, /slash commands (scanned from your installed Claude Code commands and .claude/commands/), @file mentions, image and file drops, and model, provider and effort selectors.
• Steer mid-turn: send a message while Claude is working and it is delivered into the running turn without an interrupt. Stop still cancels.
• Todo card & next steps: the agent's todo list stays at the bottom of the transcript. When a turn ends, ccem suggests up to two follow-ups that you can run here or as a new session.
• Annotations: highlight any part of a reply in five colors and attach notes to it.
• Fork from any turn: branch a new Claude session that keeps the full context up to that turn, leaving the original unchanged.
• File checkpoints & rewind: restore the working tree to any Claude file checkpoint from the transcript.
• Built-in browser side panel: an embedded browser with isolated login profiles, so your own Chrome data stays untouched. The agent can drive it. You can pause it, take over, and review its screenshots, console logs and an action audit trail. The same side panel has Changes, Browse and Agents tabs.
• Global search (Cmd+K): search every project and past conversation.
• Hand off to a bot: attach a running session to a paired chat bot. Hermes decides which updates are worth sending, and replies from chat continue the session.

Per-Subagent Model Routing

Why pay top-model prices for grep? Turn on Dynamic routing for a Claude session and ccem runs it through a local routing proxy (bound to 127.0.0.1) that splits the work across environments:

• Bind subagent types (for example Explore) and background tasks to different environments. The main thread follows the composer's environment.
• Save reusable route profiles, or generate them from templates: Budget chores (send Explore and the background model to a cheaper environment) or Specialty split (bind one subagent type to a specialist).
• Optionally let the agent re-route itself to an allow-listed environment.
• Change bindings mid-session. Changes apply from the next request.
• See which environment handled what in the session's routed usage breakdown.

Routing is opt-in for each session, and sessions that don't use it run direct. The routing chip in the top bar shows Direct or Routed and opens the routing popover.

Sessions & Session Review

![Session Review](https://raw.githubusercontent.com/genuifx/ccem/HEA