# UCC folders

UCC is one directory. Everything the installer put on your machine — every Claude Code home, the shared skills, the launchers, the daemon's data — lives under `$UCC_HOME`, which defaults to `~/.local/share/ucc`. Every `ucc-*` command starts there. Print yours:

```
echo "$UCC_HOME"
```

This page tells you which folder holds what, which files are yours to edit, and which the installer rewrites on every update.

## The tree

```mermaid
flowchart LR
  H["$UCC_HOME"] --> P["profiles/"]
  H --> S["shared/"]
  H --> B["bin/"]
  H --> C["config/"]
  H --> D["data/"]
  H --> W["work/"]
  H --> CA["cache/"]
  H --> SR["sessions/"]
  H --> U["user-env.sh"]
  S --> SK["skills/"]
  S --> SA["agents/"]
  S --> SP["projects/"]
  S --> SC["CLAUDE.md"]
  P --> PN["<name>/"]
  PN -.-> SK
  PN -.-> SA
  PN -.-> SC
  X["~/.codex/skills/ucc"] -.-> SK
```

Dotted lines are symlinks: each profile's `skills`, `agents` and `CLAUDE.md` point into `shared/`, and `~/.codex/skills/ucc` points at the same `shared/skills/` tree, so Codex reads the skills Claude Code reads.

## Folder by folder

| Path | What it holds | Who writes it |
|---|---|---|
| `profiles/<name>/` | One complete Claude Code home per profile: `.claude.json`, `.credentials.json`, `settings.json`, and symlinks `skills`, `agents`, `CLAUDE.md`, `projects` into `shared/`. `ls "$UCC_HOME/profiles"` lists the names; each has a launcher `ucc-<name>` in `bin/`. | The installer creates it; Claude Code writes its own state into it. |
| `shared/skills/` | The one skills tree — one directory per skill, each with a `SKILL.md` (`ccc-base`, `ccc-work`, `llm-wiki`, …). Every profile's `skills` and `~/.codex/skills/ucc` point here. | The installer. A skill you write for yourself goes in your own repo and is linked in; a hand edit here is lost on the next update. |
| `shared/agents/` | Subagent definitions. Every profile's `agents` points here. | The installer. |
| `shared/projects/` | Claude Code's transcripts: one folder per project directory, one `<session-uuid>.jsonl` per session. The folder name is the project path with every character that is not a letter or digit replaced by `-`, so `/Users/you/repo` is `-Users-you-repo`. | Claude Code itself. Read it; never edit it. |
| `shared/CLAUDE.md` | Your global instructions. Every profile's `CLAUDE.md` is a symlink to this one file, so an edit here reaches every profile. | You. |
| `bin/` | The launchers: `ucc-<profile>` for each profile, `ucc-auto` (picks a profile for you), `ucc-cli` (the maintenance tool), `ucc-codexd` (the local proxy behind the `ucc-codex` launchers), `ucc-source-<profile>` (prints one profile's environment for a shell to source), and `skills-bin/` (commands that skills put on your `PATH`). `ls "$UCC_HOME"/bin/ucc-*` lists them; ignore the `*-cli`, `*-ip` and `ucc-source-*` entries. | The installer. |
| `config/` | The launch plane — what every `ucc-*` launch gets as system prompt, model, tools and MCP servers. `launch/*.md` is one agent definition per launch kind (the page body is the system prompt), `mcp/*.md` one MCP server each, `fleet.md` the fleet-wide tool deny list. `GUIDE.md` in this folder is the human-facing authority. | The installer, unless the folder is a git checkout (`config/.git` exists) — then the checkout wins. `ucc-cli config update` refreshes it alone. |
| `data/` | State the daemons keep: `ccc-pages/` (published pages, keys), `ccc-telegram/`. | The daemons. Never edit by hand. |
| `cache/` | Working state the daemons rebuild: `ccc-status/` holds the `ccc-statusd` daemon's state and log. | The daemons. Never edit by hand. |
| `sessions/` | The sessions root a fresh install seeds here, unless `CCC_SESSIONS_ROOT` points elsewhere — the records your agents write. See [Sessions & wiki](#sessions-wiki). | Your agents, through the daemon. |
| `work/<short-id>/` | Each agent's private working folder — checkouts, builds, captures. The agent's join brief names it. | Each agent, for itself. |
| `user-env.sh` | Your user-scope environment, sourced by every launcher and by `ccc-statusd start`. The installer writes `UCC_AUTH_TOKEN`, `UCC_USERNAME` and `UCC_R2_BASE_URL` here; you add `ENCRYPTION_PASSWORD` and the sync settings yourself. | The installer, then you. |
| `ucc-init.sh` | The shell setup your shell's startup file sources: puts `bin/` and `bin/skills-bin/` on your `PATH` and defines the `ucc-*` shell functions. | The installer. |
| `default-env.sh`, `user-override.sh` | The installer's base environment, and a last override layer. A launcher sources `default-env.sh`, then `user-env.sh`, then `user-override.sh`, in that order. | Installer / you. |

Two things a reader expects here that work differently:

- **There is no `hooks.toml` in `$UCC_HOME`.** Hooks live on the sessions root's `HOOKS.md`; see [Hooks](#what-you-have/chapter.hooks). `ccc-statusd hooks show` prints what is armed.
- **The sessions root is its own tree.** A fresh install seeds it at `$UCC_HOME/sessions` with its own git history; `CCC_SESSIONS_ROOT` can place it anywhere. The rest of `$UCC_HOME` holds the tooling, the sessions root holds the records.

## What you may edit

Yours, and safe across updates:

- `user-env.sh` — environment variables and secrets for every launch.
- `user-override.sh` — the last word when you need to override something the installer set.
- `shared/CLAUDE.md` — your global instructions.
- `work/<short-id>/` — your agents' working folders.

Read, but do not edit by hand: `shared/skills/`, `shared/agents/`, `bin/`, `config/`, `default-env.sh`, `profiles/<name>/settings.json`, and everything under `data/` and `shared/projects/`. The installer rewrites these; `ucc-cli update` (needs `ENCRYPTION_PASSWORD` in your environment) re-runs the installer and brings the whole tree to the latest release, `ucc-cli config update` refreshes `config/` alone, and `ucc-cli repair` checks and fixes the profile symlinks.

If something looks wrong after an update, the check with zero writes is:

```
"$UCC_HOME/shared/cc-continuity/install.sh" --check
```

It writes nothing. A healthy tree prints one line starting `cc-continuity OK:` with the skill and agent counts; a broken one prints one `FAIL` line per broken surface.

## Where the detail lives

- `config/GUIDE.md` — how the launch plane composes a system prompt, and the two refusals that fail a launch (`--launch NAME` with no page; an explicit `--model` that differs from a profile's pinned model).
- Skill `ccc-base`, file `setup.md` — install, the preflight checks, and `--fix`.
- `ucc-cli --help` — every maintenance command; `ucc-cli <command> --help` for one.