# Cdesktop

> Operate the cdesktop coding-session environment — agent teams, session management, file conventions.

- Skill: `cdesktop-ai/cdesktop` (Agent Skill)
- Install (CLI): `npx skillmds@latest add cdesktop-ai/cdesktop`
- Raw SKILL.md: https://api.skillmd.com/api/skills/cdesktop-ai/cdesktop/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: cdesktop-ai (https://skillmd.com/u/cdesktop-ai)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/cdesktop-ai/cdesktop

---


# cdesktop

cdesktop spawns coding-agent sessions per workspace. You may be running as
a standalone session, or as part of a **team** in the same workspace.

## Agent Teams

Use this when delegating parallel subtasks, getting a second opinion, or
running a structured debate. Teammates share your working directory by
default — pick non-overlapping file scopes for write-heavy work.

### Commands

Canonical invocation is `npx cdesktop team ...` (works without global
install). If `cdesktop` is on your `PATH`, you may use it directly as a
shorthand.

- Spawn (lead only): `npx cdesktop team spawn --name <name> [--prompt-file p] [--executor ...] [--model ...] [--provider ...]`
- Send: `npx cdesktop team send <id> --message-file p`
- List: `npx cdesktop team list --json`

Every command requires the `CDESKTOP_SESSION_ID` env var, which cdesktop
injects automatically at executor spawn. If the var is missing, you are
running outside a cdesktop session and `team` commands will refuse.

### When to spawn

- Research from N angles in parallel.
- Parallel implementation on non-overlapping modules.
- Devil's advocate / critique against your plan.

### Roles

Free-text via `--name`. Common labels: `researcher`, `reviewer`,
`refactorer`, `debater`. The name is also the session's pill label in
the cdesktop UI, so prefer short (≤ 24 chars), descriptive names.

### Cross-executor / cross-model

Pass `--executor`, `--variant`, `--model`, `--reasoning`, `--provider`
to spawn a teammate using a different agent / model than yourself. When
you change executor you MUST pass `--model` and `--provider`, otherwise
the server returns `EXECUTOR_REQUIRES_PROVIDER`.

When you omit these flags, the teammate inherits your executor, model,
provider, reasoning effort, and permission mode.

### Peer messaging

Any team member can send to any other (including the lead). The
recipient's executor / model / provider are preserved — `send` never
swaps a teammate's config mid-stream. Encourage debate by spawning two
teammates with opposing prompts and forwarding their findings.

### Anti-patterns

- Don't spawn for trivial subtasks — the orchestration overhead exceeds
  the benefit.
- Don't have N teammates write the same file in parallel — overlapping
  writes will clobber each other. Pick non-overlapping module scopes.
- Watch for ping-pong loops; cut a thread by sending a final resolution
  message or stopping the session in the UI.
- Don't expect teammates to be synchronous — they run in their own
  process and respond when they finish their turn.

## (Future cdesktop sections)

Other cdesktop behaviours will be documented here as they ship.