Open format · declared files · exact targets
.cctheme format: an inspectable theme package for Codex and WorkBuddy
Learn what a .cctheme archive contains, how targets and SHA-256 integrity work, which media are allowed and why the installer remains separate.
Specification reviewed
The required files
Every package starts with manifest.json and theme.json. The manifest records kind, target identity, adapters, declared files, sizes, media types and SHA-256 hashes. theme.json keeps the editable document without embedding binary media as Base64.
Compiled target configuration and media live below a target directory. Codex uses targets/macos/ and WorkBuddy uses targets/macos-workbuddy/. The embedded target is authoritative; the filename alone never decides where a package is applied.
- manifest.json — package, target, file list and integrity
- theme.json — editable local theme document
- targets/macos/theme.json — compiled Codex configuration
- targets/macos-workbuddy/theme.json — compiled WorkBuddy configuration
Allowed local media
The current adapters are media skins. A target contains a required PNG, JPEG or WebP background, or a generated solid fallback. An optional background.mp4 may be included up to 256 MiB. A Codex v2 package can optionally include an inseparable pet manifest and WebP spritesheet pair; WorkBuddy rejects pet data.
The full archive is limited to 550 MiB compressed and expanded, with no more than 20 entries. Media types, file signatures, dimensions or structure, expanded size and manifest hashes are checked during import.
- PNG, JPEG or WebP static background
- Optional MP4 background up to 256 MiB
- Optional Codex-only v2 pet pair
- No embedded player, remote URL or executable media handler
Rejected content
Paths must be relative, normalized and declared. Import rejects traversal paths, absolute paths, duplicate or unlisted entries and unsupported schema kinds. Renaming an arbitrary file to an allowed extension is not sufficient because the media signature is also checked.
Scripts, raw CSS, HTML and SVG are forbidden in a theme archive. Client selectors and version-specific patches belong to the fixed local adapter, not to a user-distributed theme.
- JavaScript, shell or PowerShell theme payloads
- Raw CSS, HTML and SVG
- Remote media URLs or embedded web players
- Traversal, absolute, duplicate or unlisted paths
Integrity is not identity
Every file except manifest.json has a SHA-256 value in manifest.integrity.files. The importer recalculates those hashes before loading the document or media. This detects accidental damage or substitution relative to the manifest.
A hash is not a digital signature and does not identify the author. For an installer or adapter release, compare the downloaded artifact with the checksum published on the project's GitHub Release and review the source and release notes separately.
- Hash mismatch rejects the package
- Target mismatch rejects the package
- Unknown adapter or client build must not be assumed compatible
- Installer trust is evaluated separately from theme-package integrity
.cctheme format FAQ
Is .cctheme just a renamed ZIP file?
It uses a ZIP container, but import requires the .cctheme extension, supported kinds, an exact manifest, declared paths, target identity and verified hashes.
Can I inspect a theme without installing the adapter?
Yes. The archive can be opened in CC Theme Studio and its JSON and declared assets can be inspected independently of the local adapter.
Can one package target both Codex and WorkBuddy?
No. The current user-facing package identifies one application, platform and client version. Separate packages prevent accidental cross-client application.
Does the package modify native Codex colors or fonts?
No. Current macOS packages control local media, media position, structural backdrop blur or saturation and system appearance mode. Native colors, typography, radii and layout remain locked.
Why is the installer not inside the theme?
Separating theme data from fixed adapter code prevents a theme author from shipping executable client-control logic inside an appearance package.
Specification and contract
The repository specification is the source of truth. Package limits and target versions can change only through a reviewed contract update.