config-claude-code-cloud

Bootstrap config for Phoenix's Claude Code on the web (cloud) environments — the cloud counterpart to the config-leash repo, which covers the local Leash/Docker setup instead. Cloud environments only take a single Setup script and a single .env snippet, pasted into a UI dialog with no version history — so the actual content lives here instead, and the dialog just points at it.

Structure

• cloud/pointer.sh — paste verbatim into the environment's Setup script field. Fetches and runs cloud/setup.sh below.
• cloud/setup.sh — the real logic: installs gh, lefthook, hadolint, trufflehog, extra Python versions, and semgrep; writes cloud/gh-config.yml and cloud/CLAUDE.md (below); syncs the phx, superpowers, and elements-of-style plugins into ~/.claude/skills/<name>/ (see "Plugins" below).
• cloud/CLAUDE.md — personal user-level instructions. Cloud sessions don't carry over ~/.claude/CLAUDE.md from a local machine (only repo-committed CLAUDE.md files do), so this is the only way to get it into cloud sessions at all. Generated by cloud/generate-claude-md.sh, run automatically by .github/workflows/generate-claude-md.yml after every push to main (and by todofixthis/config-claude's own workflow, when the shared content it publishes changes) — see cloud/CLAUDE.cloud-only.md for how to edit and preview it.
• cloud/CLAUDE.cloud-only.md — the cloud-specific personal instructions, plus how to maintain and regenerate cloud/CLAUDE.md. There's no cloud/CLAUDE.shared.md file in this repo at all — that content is canonical in, and only ever checked into, todofixthis/config-claude; this repo fetches it live instead of keeping a copy.
• cloud/generate-claude-md.sh — concatenates cloud/CLAUDE.cloud-only.md with todofixthis/config-claude's CLAUDE.shared.md (fetched live via gh api) into cloud/CLAUDE.md.
• .github/workflows/generate-claude-md.yml — runs the above automatically on a push to main that touches cloud/CLAUDE.cloud-only.md, using the CONFIG_CLAUDE_READ_TOKEN secret below to authenticate the fetch, and pushes the regenerated cloud/CLAUDE.md as the CLAUDE_MD_BOT_APP_ID app (also below) — a bypass actor on this repo's own branch-protection ruleset, since neither the default GITHUB_TOKEN nor a plain PAT can push straight to main here.
• cloud/gh-config.yml — gh CLI preferences. Note git_protocol: https, not ssh — cloud sessions have no SSH client, so gh needs HTTPS to have any credential to use.
• cloud/environment.env — paste verbatim into the environment's Environment variables field.

One-time environment setup

1. At claude.ai/code, open the environment dialog (the cloud icon above the message box → settings gear on the environment you're configuring).
2. Set Network access to Custom, keep "also include default list of common package managers" checked, and add *.cloudsmith.io (needed for lefthook's package repo — everything else installs from domains already on the Trusted default list).
3. Paste cloud/pointer.sh's content into Setup script.
4. Paste cloud/environment.env's content into Environment variables.
5. Save. The setup script runs once, on the first session in this environment, and is cached (~7 days, or until the setup script text or allowed domains change) for every session after that.

One-time setup: the generation workflow

The workflow needs two credentials, for two unrelated reasons: a PAT to read todofixthis/config-claude (private), and a GitHub App to write back to this repo's own main past its branch-protection ruleset.

Reading todofixthis/config-claude

.github/workflows/generate-claude-md.yml fetches CLAUDE.shared.md from todofixthis/config-claude (private) — the default GITHUB_TOKEN a workflow run here gets is scoped to this repo only, and this repo never keeps its own copy of that file to fall back on. This is a GitHub Actions repository secret, not something the cloud session sandbox itself holds — it's unrelated to, and doesn't relax, the "no secrets store" rule under "What's deliberately not here" below, which is about that sandbox specifically. Set it up once:

1. At github.com/settings/personal-access-tokens/new, create a fine-grained personal access token.
2. Repository access: "Only select repositories" → todofixthis/config-claude.
3. Permissions: Repository permissions → Contents → Read-only. No other permission is needed.
4. Set an expiration you're comfortable renewing, or "No expiration" if you'd rather not think about it again — an expired token fails the workflow the same way a missing one does (loudly, not silently), so there's no safety cost either way beyond the renewal chore.
5. Generate the token and copy it.
6. In this repo's own Settings → Secrets and variables → Actions, add a New repository secret named CONFIG_CLAUDE_READ_TOKEN, and paste the token as its value.

Writing to this repo's own main

main's branch-protection ruleset requires every change to go through a pull request, with no bypass actor configured — so even this repo's own GITHUB_TOKEN gets rejected (GH013) on a plain push. Adding a GitHub App to the ruleset's bypass list fixes that for whichever token a workflow explicitly generates from it; todofixthis/config-claude's own workflow generates a token from the same App to push here across repos, so one App and one bypass-list entry cover both. Set it up once:

1. At github.com/settings/apps/new, register a new GitHub App — name doesn't matter (e.g. config-claude-md-bot). Under Webhook, uncheck Active; this App never receives events.
2. Permissions → Repository permissions → Contents → Read and write. No other permission is needed.
3. Where can this GitHub App be installed? → Only on this account.
4. Create the App, then generate and download a private key from its settings page.
5. From the App's settings page, Install App on todofixthis/config-claude-code-cloud only — it never needs todofixthis/config-claude itself.
6. In this repo's Settings → Rules → Rulesets → main, add the App to the Bypass list with bypass mode Always.
7. In this repo's own Settings → Secrets and variables → Actions, add two New repository secrets: CLAUDE_MD_BOT_APP_ID (the App ID, on its settings page) and CLAUDE_MD_BOT_APP_PRIVATE_KEY (the private key file downloaded in step 4, pasted whole).
8. Repeat step 7 in todofixthis/config-claude's own Settings → Secrets and variables → Actions — its workflow generates its own installation token from the same App to push here.

Once both are set up, any push to main that changes cloud/CLAUDE.cloud-only.md triggers this repo's workflow (as does a push to todofixthis/config-claude's main that changes CLAUDE.shared.md). You can also fire either manually from the Actions tab (workflow_dispatch) to confirm it's wired up — but only after merging the workflow file to main; workflow_dispatch isn't available for a workflow that only exists on a branch.

Plugins

phx, superpowers, and elements-of-style are skill libraries (superpowers also ships one SessionStart hook) — none of the three ship agents, commands, or MCP servers. setup.sh doesn't install them as plugins in the usual sense. It clones each plugin's own repo — not the shared superpowers-marketplace repo, which is just a pointer catalogue with no skill content of its own — and copies its .claude-plugin/, skills/, hooks/, agents/, commands/, and .mcp.json (whichever exist) straight into ~/.claude/skills/<name>/.

That's deliberate, not a shortcut: the marketplace path (extraKnownMarketplaces + claude plugin install) clones the plugin into ~/.claude/plugins/cache fine, but run non-interactively from a setup script it never persists the "installed" record — installed_plugins.json comes out empty and the skills never load, even though settings.json looks correct. Claude Code separately auto-loads any directory at ~/.claude/skills/<name>/ that carries a .claude-plugin/plugin.json, as <name>@skills-dir, with no marketplace or settings.json entry — confirmed to work, hook included, by testing it in a session. cloud/setup.sh uses that path for all three plugins instead.

One consequence: don't also enable these three via the marketplace path (extraKnownMarketplaces/enabledPlugins in settings.json) — an installed marketplace plugin takes precedence over a skills-dir plugin of the same name, so the skills-dir copy would silently stop loading.

Making changes

• Editing setup.sh or gh-config.yml: commit the change here, then bump the version comment at the top of cloud/pointer.sh and re-paste pointer.sh's content into the environment's Setup script field. This step is the whole reason pointer.sh exists: the environment only re-runs its setup script (and rebuilds the cached snapshot) when that field's own text changes — never when the file it fetches does. Skipping the re-paste means the change sits in this repo but never reaches a session.
• Editing CLAUDE.cloud-only.md: commit and push to main — .github/workflows/generate-claude-md.yml regenerates cloud/CLAUDE.md and pushes automatically; then follow the bump-and-re-paste step above (see cloud/CLAUDE.cloud-only.md for the full procedure).
• Editing shared content: not here — there's no CLAUDE.shared.md file in this repo to edit. Edit it in todofixthis/config-claude's CLAUDE.shared.md instead; that repo's own workflow pushes the regenerated cloud/CLAUDE.md into this repo automatically (see cloud/CLAUDE.cloud-only.md for the full procedure).
• Editing pointer.sh or environment.env itself: re-paste directly, no version bump needed (the text already changed).
• Adding a plugin: add a sync_skills_dir_plugin call for it in cloud/setup.sh (see "Plugins" above), then follow the bump-and-re-paste step above.
• A cloud session editing ~/.claude/CLAUDE.md in place (e.g. phx:reflection deciding to record a new pattern): that's the fetched copy, not this repo — the edit is invisible everywhere else and is gone at the next cache rebuild. cloud/CLAUDE.cloud-only.md carries this same warning (which flows into the generated cloud/CLAUDE.md, and so into the fetched copy), since that's what a session is reading right when it'd make this mistake.

Why this exists instead of one script pasted straight into the dialog

Two different things were living in one place: toolchain installs, which change rarely, and personal preferences (CLAUDE.md, in particular), which change often — and the dialog gives neither of them git history, diffs, or review. Splitting the real content into this repo fixes that; pointer.sh is the two-line adapter that makes the dialog agree to defer to it.

What's deliberately not here

• GPG commit signing. Cloud environments have no secrets store, and Anthropic's own docs say signing keys are kept out of the session sandbox entirely — there's no code path for a personal key to plug into, quite apart from nowhere safe to store one.
• PyPI publishing credentials. Same reasoning — no secrets store, so no token lives here. Publish from local Leash instead.
• SSH keys. Cloud sessions have no SSH client at all; all GitHub git operations go through Anthropic's own GitHub proxy with short-lived scoped credentials instead.