| name | cc-settings-api |
| description | Read and write CC Director app settings (screenshots location, gateway connection, any config.json key) by calling a running Director's Control API. Triggers on "/cc-settings-api", "set the gateway", "connect this director to the gateway", "set screenshots location", "configure cc-director settings". |
CC Director Settings API Skill
Configure CC Director's config.json programmatically through a running Director's
Control API. Writes are round-trip-preserving (only the keys you set change; every other
section is kept) and gateway changes apply live - the Director re-registers with the
gateway with no app restart.
Use this when the user asks to set the screenshots folder, connect a Director to a central
gateway, or change any cc-director setting from the agent side.
How it works
A running Director exposes GET /settings and PUT /settings on a loopback port. The
script configure_settings.py discovers the newest live Director from its instance files
at <config>/director/instances/*.json (reading ControlEndpoint + checking the Pid is
alive) and calls those endpoints.
<config> is %LOCALAPPDATA%\cc-director\config on Windows, ~/.local/share/cc-director/config
on macOS/Linux, or $CC_DIRECTOR_ROOT/config if that env var is set.- Auth is OFF by default (single-user trust boundary), so no token is needed. If a Director
has auth enabled, pass
--director-token or the script reads it from
<config>/director/gateway-token.txt.
Commands
Run from the repo root (the script needs no dependencies beyond the standard library):
# Read / write
python .claude/skills/cc-settings-api/configure_settings.py show
python .claude/skills/cc-settings-api/configure_settings.py get screenshots.source_directory
python .claude/skills/cc-settings-api/configure_settings.py set-screenshots "/Users/you/Desktop"
python .claude/skills/cc-settings-api/configure_settings.py set-gateway --url http://GATEWAY-HOST:7878 --advertised http://THIS-HOST:7879
python .claude/skills/cc-settings-api/configure_settings.py set <dotted.key> <value>
# Detect (add --apply to write the detected value straight into config.json)
python .claude/skills/cc-settings-api/configure_settings.py detect-gateway [--apply]
python .claude/skills/cc-settings-api/configure_settings.py detect-public-url [--apply]
python .claude/skills/cc-settings-api/configure_settings.py detect-screenshots [--apply]
# Test a gateway URL's reachability (/healthz)
python .claude/skills/cc-settings-api/configure_settings.py test-gateway --url http://GATEWAY-HOST:7878
The detect/test commands run the SAME logic as the Settings dialog buttons (via
POST /settings/detect/{gateway|public-url|screenshots} and POST /settings/test/gateway) -
so you never need to open the GUI to view, change, or auto-detect settings from a session.
Without --apply, detect commands only report the found value; the agent then decides whether
to write it. detect-gateway --apply is the one-shot "find and connect to the gateway".
Connecting a Director to a gateway (the main use case)
To make a Director on ANY network show up on a central gateway, set two things:
--url - the gateway's base URL, reachable from this machine (e.g. http://gw-host:7878).--advertised - THIS Director's own URL, reachable from the gateway's machine. This is
required whenever the gateway runs on a different machine. Without it the Director
advertises loopback (127.0.0.1), which the gateway cannot call back to. On a Mac this is
mandatory (the Tailscale auto-detection is Windows-only).
Example - connect a Mac Director (control port 7879) to a gateway on gw-host:
python .claude/skills/cc-settings-api/configure_settings.py set-gateway \
--url http://gw-host:7878 \
--advertised http://mac-host:7879
After this the Director re-registers immediately. Verify it appears in the gateway's
GET /directors, or re-run show to confirm the gateway block on disk.
Notes
- Do NOT hand-edit
config.json while a Director is running and also use this API - go
through the API so the live gateway re-apply happens. (cc-devthrottle settings is the
offline path and is also round-trip-preserving.)
- If no Director is running, the script fails loudly telling you to start CC Director. It
does not silently write the file - starting the Director is the fix.
- Output is ASCII-only.
