Dev: Set up / re-apply the Web Environment
Web sessions boot with the shared profile via two loaders:
| Loader |
When it runs |
Coverage |
Env Setup script (--env-script, default) |
pre-launch, per-account environment |
every session, including multi-repo — the primary loader |
Committed hook (--committed) |
SessionStart, per-repo |
single-repo sessions only — a redundancy fallback (fetches the mirror's default branch; skips when the env script already installed), never the only loader |
This skill runs on the local terminal; the download and install happen
later, inside the web container. When neither flag is passed, apply
--env-script — it is safe everywhere.
Never put positional parameters (dollar sign + digit) anywhere in this
file — skill argument substitution replaces them with invocation args and
corrupts embedded snippets. That is why the hook template lives in assets/
and the env script is read from disk instead of being embedded here.
Step 1: Env setup script (--env-script, default)
Read $HOME/.claude/web/env-setup-script.sh (the canonical copy; the
mirror ships it to the web container too) and print its contents verbatim
for the user to paste into claude.ai/code → Environment → Setup script.
Tell the user to also fill the environment's Environment variables
field:
CLAUDE_WEB_PROFILE_OPT_IN=1
DROPBOX_CCLOGS_DIR=/tmp/cclogs
DROPBOX_SCREENSHOTS_DIR=/tmp/screenshots
The DROPBOX_* stubs are needed because $CLAUDE_ENV_FILE (which
setup-web.sh would otherwise write them to) may not exist pre-launch;
the opt-in var feeds committed self-only hooks.
First-run check: the environment's setup output shows which tier worked —
claude-profile: cloned claude-settings (tier 1, private clone) or
claude-profile: fetched claude-resources tarball (fallback) — followed by
web profile installed into ....
Step 2: Committed hook (--committed, optional top-up)
!! Team-repo safety !! A committed .claude/settings.json affects
everyone in the repo: on a teammate's web session it would overwrite
their ~/.claude and disable their permission prompts (web settings run in
auto mode). Solo repos only, or get the owner's agreement — and prefer
--self-only.
Single-repo sessions only. Multi-repo web sessions never register
repo-level settings hooks — this hook silently does nothing there. It is a
top-up alongside Step 1, never the only loader.
Copy assets/web-bootstrap.template.sh (bundled in this skill's directory)
to <project>/.claude/web-bootstrap.sh and chmod +x it.
If --self-only was passed: uncomment the CLAUDE_WEB_PROFILE_OPT_IN gate
inside the copy, and tell the user to set CLAUDE_WEB_PROFILE_OPT_IN=1
in their per-account web environment variables (already included in the
Step 1 block) — without it the gate skips every session. The gate keys on a
per-account env var — never on a committed email/identity (breaks on
account switch; the harness email var is unreliable on web).
Register the hook in <project>/.claude/settings.json — merge into an
existing file rather than overwriting:
{
"$schema": "https://json.schemastore.org/claude-code-settings.json",
"hooks": {
"SessionStart": [
{
"hooks": [
{
"type": "command",
"command": "/bin/bash \"$CLAUDE_PROJECT_DIR/.claude/web-bootstrap.sh\""
}
]
}
]
}
}
Commit both files (use /co) and push. In the report, always mention
the single-repo-sessions-only limitation so a silent multi-repo skip is not
mistaken for breakage.
Prerequisites
- The public mirror must carry the web profile (
web/ +
scripts/setup-web.sh) — publish with /claude-resources-share.
- Network policy must allow plain HTTPS egress to
github.com (and its
redirect target codeload.github.com) for the tarball tier.
- Tier 1 clone:
Takazudo/claude-settings should be within the GitHub app's
allowed repo scope. Optional — the tarball fallback covers a rejected clone.
Gotchas (hard-won; do not re-litigate)
- Multi-repo sessions never register repo-level settings hooks (verified
in-container): project dir is
/home/user, repos are subdirectories;
CLAUDE.md and skills load, hooks don't. Launcher-level hooks still fire, so
"hooks work" is not evidence the repo hook ran. Only the env setup script
covers these sessions.
CLAUDE_CODE_REMOTE is not guaranteed pre-launch: setup-web.sh exits 0
without it. The env script exports it explicitly — without that, the download
succeeds and the install silently no-ops ("fetched fine, nothing installed").
- Sentinel interplay: the env script writes
~/.claude/.web-profile-source
after a successful install; the hook template skips when it is present, so a
tier-1 private-clone profile is never clobbered by the hook's public-mirror
tarball.
- Scoped git proxy history (mechanism:
gitConfigInjection — the rewrite
arrives via injected git config; git config -l in the container reveals
it): out-of-scope git clone used to 403
unconditionally; containers observed 2026-07 clone the user's own repos —
but only post-boot (SessionStart context) was observed, and behavior has
shifted once already. Every path keeps the tarball fallback. Verify from a
web session with
git ls-remote --exit-code https://github.com/Takazudo/claude-settings HEAD
(expect a hash, not 403).
- The Setup script result is cached as an environment snapshot (docs:
cached when it finishes in
5 min). Sessions then boot the frozen
`/.claude— a skill deleted/renamed upstream (e.g. old/pr-complete) lingers. Two guards: setup-web.shprunes non-symlink skills/agents/commands missing from the source, and the user-level SessionStart hook inweb/settings.web.jsonrunsscripts/web-refresh-profile.sheach session (pull~/.claude-srcor re-fetch the mirror, re-runsetup-web.shwithCLAUDE_WEB_SKIP_WISDOM=1). To rebuild the snapshot itself, bump the loader-rev` line and re-paste the script.
- Cloud sessions never read the Mac's
~/.claude — only claude.ai
account-enabled skills, the repo's .claude/skills/, and whatever the Setup
script installs into the container's ~/.claude. A skill appearing on web
that no source has is either a stale snapshot or an account-level skill
(claude.ai → Settings → Capabilities).
settings.local.json is not an option — git-ignored, never reaches the
web container.
setup-web.sh sources from its own location, so it installs the downloaded
profile's config, not the consumer project's.
1---2name: dev-setup-webenv3description: "(Re)apply the Claude Code on the web profile setup. Use when: (1) User says '/dev-setup-webenv', 'set up web env', 'enable my skills on web', (2) A web session boots without the profile, (3) A new web environment or account needs the Setup script re-applied. Runs LOCALLY (Mac/terminal) — prints the canonical env setup script (PRIMARY: per-account, pre-launch, covers multi-repo sessions) and/or commits a single-repo SessionStart top-up hook from the bundled template."4argument-hint: "[--committed] [--env-script] [--self-only]"5metadata:6 source: https://skillmd.com/skills/takazudo/dev-setup-webenv7---89# Dev: Set up / re-apply the Web Environment1011Web sessions boot with the shared profile via two loaders:1213| Loader | When it runs | Coverage |14|---|---|---|15| **Env Setup script** (`--env-script`, default) | pre-launch, per-account environment | every session, including multi-repo — the primary loader |16| **Committed hook** (`--committed`) | SessionStart, per-repo | single-repo sessions only — a redundancy fallback (fetches the mirror's default branch; skips when the env script already installed), never the only loader |1718This skill runs on the **local terminal**; the download and install happen19later, inside the web container. When neither flag is passed, apply20`--env-script` — it is safe everywhere.2122**Never put positional parameters (dollar sign + digit) anywhere in this23file** — skill argument substitution replaces them with invocation args and24corrupts embedded snippets. That is why the hook template lives in `assets/`25and the env script is read from disk instead of being embedded here.2627## Step 1: Env setup script (`--env-script`, default)28291. Read `$HOME/.claude/web/env-setup-script.sh` (the canonical copy; the30 mirror ships it to the web container too) and print its contents verbatim31 for the user to paste into **claude.ai/code → Environment → Setup script**.32332. Tell the user to also fill the environment's **Environment variables**3435 field:3637 ```38 CLAUDE_WEB_PROFILE_OPT_IN=139 DROPBOX_CCLOGS_DIR=/tmp/cclogs40 DROPBOX_SCREENSHOTS_DIR=/tmp/screenshots41 ```4243 The `DROPBOX_*` stubs are needed because `$CLAUDE_ENV_FILE` (which44 `setup-web.sh` would otherwise write them to) may not exist pre-launch;45 the opt-in var feeds committed self-only hooks.46473. First-run check: the environment's setup output shows which tier worked —48 `claude-profile: cloned claude-settings` (tier 1, private clone) or49 `claude-profile: fetched claude-resources tarball` (fallback) — followed by50 `web profile installed into ...`.5152## Step 2: Committed hook (`--committed`, optional top-up)5354> **!! Team-repo safety !!** A committed `.claude/settings.json` affects55> **everyone** in the repo: on a teammate's web session it would overwrite56> their `~/.claude` and disable their permission prompts (web settings run in57> auto mode). Solo repos only, or get the owner's agreement — and prefer58> `--self-only`.5960> **Single-repo sessions only.** Multi-repo web sessions never register61> repo-level settings hooks — this hook silently does nothing there. It is a62> top-up alongside Step 1, never the only loader.63641. Copy `assets/web-bootstrap.template.sh` (bundled in this skill's directory)65 to `<project>/.claude/web-bootstrap.sh` and `chmod +x` it.66672. If `--self-only` was passed: uncomment the `CLAUDE_WEB_PROFILE_OPT_IN` gate68 inside the copy, and **tell the user to set `CLAUDE_WEB_PROFILE_OPT_IN=1`69 in their per-account web environment variables** (already included in the70 Step 1 block) — without it the gate skips every session. The gate keys on a71 per-account env var — never on a committed email/identity (breaks on72 account switch; the harness email var is unreliable on web).73743. Register the hook in `<project>/.claude/settings.json` — **merge** into an7576 existing file rather than overwriting:7778 ```json79 {80 "$schema": "https://json.schemastore.org/claude-code-settings.json",81 "hooks": {82 "SessionStart": [83 {84 "hooks": [85 {86 "type": "command",87 "command": "/bin/bash \"$CLAUDE_PROJECT_DIR/.claude/web-bootstrap.sh\""88 }89 ]90 }91 ]92 }93 }94 ```95964. Commit both files (use `/co`) and push. In the report, always mention97 the single-repo-sessions-only limitation so a silent multi-repo skip is not98 mistaken for breakage.99100## Prerequisites101102- The public mirror must carry the web profile (`web/` +103 `scripts/setup-web.sh`) — publish with `/claude-resources-share`.104- Network policy must allow plain HTTPS egress to `github.com` (and its105 redirect target `codeload.github.com`) for the tarball tier.106- Tier 1 clone: `Takazudo/claude-settings` should be within the GitHub app's107 allowed repo scope. Optional — the tarball fallback covers a rejected clone.108109## Gotchas (hard-won; do not re-litigate)110111- **Multi-repo sessions never register repo-level settings hooks** (verified112 in-container): project dir is `/home/user`, repos are subdirectories;113 CLAUDE.md and skills load, hooks don't. Launcher-level hooks still fire, so114 "hooks work" is not evidence the repo hook ran. Only the env setup script115 covers these sessions.116- **`CLAUDE_CODE_REMOTE` is not guaranteed pre-launch**: `setup-web.sh` exits 0117 without it. The env script exports it explicitly — without that, the download118 succeeds and the install silently no-ops ("fetched fine, nothing installed").119- **Sentinel interplay**: the env script writes `~/.claude/.web-profile-source`120 after a successful install; the hook template skips when it is present, so a121 tier-1 private-clone profile is never clobbered by the hook's public-mirror122 tarball.123- **Scoped git proxy history** (mechanism: `gitConfigInjection` — the rewrite124 arrives via injected git config; `git config -l` in the container reveals125 it): out-of-scope `git clone` used to 403126 unconditionally; containers observed 2026-07 clone the user's own repos —127 but only post-boot (SessionStart context) was observed, and behavior has128 shifted once already. Every path keeps the tarball fallback. Verify from a129 web session with130 `git ls-remote --exit-code https://github.com/Takazudo/claude-settings HEAD`131 (expect a hash, not 403).132- **The Setup script result is cached as an environment snapshot** (docs:133 cached when it finishes in ~5 min). Sessions then boot the frozen134 `~/.claude` — a skill deleted/renamed upstream (e.g. old `/pr-complete`)135 lingers. Two guards: `setup-web.sh` prunes non-symlink skills/agents/commands136 missing from the source, and the user-level SessionStart hook in137 `web/settings.web.json` runs `scripts/web-refresh-profile.sh` each session138 (pull `~/.claude-src` or re-fetch the mirror, re-run `setup-web.sh` with139 `CLAUDE_WEB_SKIP_WISDOM=1`). To rebuild the snapshot itself, bump the140 `loader-rev` line and re-paste the script.141- **Cloud sessions never read the Mac's `~/.claude`** — only claude.ai142 account-enabled skills, the repo's `.claude/skills/`, and whatever the Setup143 script installs into the container's `~/.claude`. A skill appearing on web144 that no source has is either a stale snapshot or an account-level skill145 (claude.ai → Settings → Capabilities).146- `settings.local.json` is **not** an option — git-ignored, never reaches the147 web container.148- `setup-web.sh` sources from its own location, so it installs the downloaded149 profile's config, not the consumer project's.