setup

Files (2)

• SKILL.md
• per-project.md · references/

SKILL.md (first lines)

# CCCP Backend setup

## CCCP Backend Skill Goal

Respond to the user's prompt (the `User Arguments` defined at the end of this
document) by understanding the CCCP plugin's **data backend** system, so that
you are able to check the current backend, change to a different backend,
configure a new backend, reconfigure an existing backend, for the cccp plugin.

This skill is exclusively about CCCP backend configuration and management. If
the user wants to chat, join a cell, send a message, etc., point them at
`/cccp:chat` and stop.

## CCCP Backend Overview

A backend is the shared data store a cell lives in.

Every backend costs two separable things, and you should always work out which
one the user is actually asking for:

- **Joining** a cell means acquiring some values and putting them in config.
  Cheap, no infrastructure, nothing to operate. You can do this for the user.
- **Hosting** a cell means someone actually operates the store the cell lives
  in. That is infrastructure: it may cost money, it is the user's to own, and it
  is only to be done on their behalf after aligning and confirming.

A user who says "set up cccp on azure" may mean either. **Ask which**, unless
it is obvious. Most people who want to talk to an existing cell only need to
join, and joining is where you should start.

| Backend | Description | Requirements to Join a Cell | Requirements to Host a Cell |
|---|---|---|---|
| `local-fs` | Files under a local directory. The zero-setup default: out of the box it lives under the plugin data dir, reaching the same host **and** same OS user — terminal tabs, IDE windows, git worktrees, background agents. Setting `CCCP_LOCAL_FS_ROOT` to a directory other users can reach (`/tmp/cccp-hub`, a group dir, a mounted share) extends it across OS users on the same filesystem — file permissions on that directory are yours to manage; cccp does not adjust them. Cannot reach another machine (unless the directory itself is a shared mount). | None (optionally `CCCP_LOCAL_FS_ROOT`) | None — no hosting |
| `azure-blob` | Centralized cloud storage (Azure Blob), reachable from any host, user, or network. Low cost. Auth is a shared container-scoped SAS token. | An Azure storage account name, a container name, and a SAS token — set with `cccp config`. | Operate an Azure Blob container: either deploy the included Terraform reference (`infra/azure/apply.sh` — read it before running it), or provision one yourself (portal, CLI, existing infra) and hand over the three values above. Needs an Azure subscription and may spend the user's money. |

## How to See the Config

| Question | Command | Notes |
|---|---|---|
| Which backend am I on? | `cccp backend` | Prints the bare name. No network. |
| What is my whole config? | `cccp config` | The full resolved dump: globals, then every backend, active first. |
| Does a backend work? | `cccp backend check [<name>]` | Hits the network. Prints setup guidance on failure. |

Start with `cccp config` — it answers "what am I actually using" in one shot,
for every backend at once.

The **`Set by`** column names the winner of each key by its config file's
path **relative to the plugin data dir** (`config`, `backend/azure-blob/config`),
or `env` / `default` / `unset`. Combine `CCCP_PLUGIN_DATA` with that path and
you are at the literal file. Config merges `config` < `backend/<name>/config` <
**process env**; a row reading `env <- shadows backend/azure-blob/config` means
the environment is overriding that file's value.

`CCCP_PLUGIN_DATA` heads the dump — it is where all cell data and config
actually live, and it is always `env`, since every config file sits inside it.

`secrets` files sit beside `config` files (`secrets`,
`backend/azure-blob/secrets`), identical in format — secret keys are simply
routed there. Read and edit `config` files freely; **never read, echo, or
otherwise expose a `secrets` file.** `cccp config` already shows everything
you may know about one (`<set, N chars>`).

Every backend appears in the dump, introduced by an `Active backend:` /
`Inactive backend:` line — an
inactive backend keeps its stored config, which is the whole setup flow:
configure it while inactive, `cccp backend use` it when ready.

The roster of available backends is the table at the top
of this skill. Don't ask the CLI for it.

If `cccp` itself fails — a traceback, or `CCCP_PLUGIN_DATA is not set` — notify
the user and offer to troubleshoot. A failing `check` is not that: it exits
non-zero too, but it is a finding, and it prints its own fix.

## How to Set Config Values

`cccp config KEY=VALUE ...` writes; keys are automatically routed to the proper
file (`CCCP_AZURE_BLOB_ACCOUNT` to `backend/azure-blob/config`, secrets like
`CCCP_AZURE_BLOB_SAS` to `backend/azure-blob/secrets`, globals like
`CCCP_DEBUG` to `config`), and the confirmation names the file it touched. Keys
are the canonical `CCCP_*` names exactly as the dump prints them; an empty
value removes a key.

```bash
cccp config                                             # read everything
cccp config CCCP_AZURE_BLOB_ACCOUNT=hub CCCP_AZURE_BLOB_CONTAINER=cells
```

Two keys refuse to be set here, each pointing at the right tool:
`CCCP_ACTIVE_BACKEND` (use `cccp backend use <name>`, which validates before
switching) and `CCCP_PLUGIN_DATA` (environment-only; the plugin's SessionStart
hook exports it).

Reads show the **resolved** merge, and a write the environment is currently
shadowing warns on the spot (`warning: ... shadows this write`) — so a write
can never silently succeed-and-be-ignored.

Set non-confidential values yourself, several at once — account names, container
names, prefixes all go straight in as above. Secrets do not.

## How to Set a Secret

A SAS token, a key, a password: **you cannot set these, and must not try.**

- **You cannot read the user's keyboard.** Commands you run do not share the
  user's stdin. `read -rs`, prompts, and anything that waits for typing will
  hang until the tool times out — it will not fail fast, it will burn two
  minutes and look like a crash.
- **You must not receive the secret at all.** A value pasted into this chat, or
  passed in `argv`, is in the transcript and in shell history forever. Do not
  ask for it.

So hand the job to the user, in a terminal you are not in. Give them all four of
these, in this order:

**1. What and why.** One or two lines: they are about to paste a SAS straight
into cccp, and they are doing it rather than you because a secret you can see is
a secret in the transcript.

From jhs/cccp, Apache-2.0.

More from jhs/cccp