Skip to content

Set up Claude Code cloud sessions: cached tools, background build - #1908

Closed
Polleps wants to merge 2 commits into
developfrom
claude/friendly-noether-iigj06
Closed

Polleps wants to merge 2 commits into
developfrom
claude/friendly-noether-iigj06

Conversation

@Polleps

@Polleps Polleps commented Sep 29, 2026 •

Copy link
Copy Markdown
Collaborator

Sets up Claude Code on the web sessions so agents can lint, test and run the stack. They can start reading and editing code while the slow server build runs in the background. Nothing runs unless CLAUDE_CODE_REMOTE=true, so local Claude Code sessions are unaffected.

Why it's shaped like this

Only a cloud environment's setup script is cached between sessions: a filesystem snapshot, taken only when the script finishes within about five minutes. SessionStart hooks run on every session, and every session starts from a fresh clone, so node_modules and target/ never carry over. A cold atomic-server build takes about 15 minutes, so it can't be cached anywhere. It runs in the background instead, and the agent is told how to wait for it.

The three scripts in .claude/hooks/

  • cloud-setup.sh installs the tools and warms the download caches. Each step skips what's already there.

    • The Rust toolchain from rust-toolchain.toml, with the WASM targets.
    • wasm-pack 0.15.0 and wasm-opt (binaryen 117). wasm-pack's own binaryen download fails behind the proxy, so wasm-opt goes on PATH.
    • pnpm install, which fills the pnpm store.
    • The Playwright browsers for @tomic/e2e. The image ships an older Chromium, and the proxy blocks cdn.playwright.dev, so the script downloads the same Chrome for Testing zips from storage.googleapis.com.
    • cargo fetch.

    It takes about a minute from cold, so it's meant to double as the environment's setup script: bash /home/user/atomic-server/.claude/hooks/cloud-setup.sh || true.

  • session-start.sh, the SessionStart hook:

    • Exports ATOMIC_IP=0.0.0.0. Containers have no IPv6, and atomic-server binds :: by default, so it otherwise exits with "Address family not supported by protocol".
    • Runs cloud-setup.sh, which is fast when the cache is there.
    • Starts cloud-build.sh detached.
    • Tells the agent, through additionalContext, what's still building and how to wait for it.
  • cloud-build.sh builds the @tomic/* packages, then cargo build -p atomic-server, whose build.rs also builds data-browser and the WASM. It writes /tmp/atomic-setup/packages.done and server.done (ok or failed) and logs to /tmp/atomic-setup/build.log. A lock stops a resumed session from starting a second build.

Also in this PR:

  • .gitignore: tracks .claude/settings.json and .claude/hooks/; other .claude state stays ignored.
  • AGENTS.md: documents the scripts and the suggested setup script, says to keep them in sync with the environment requirements, and has a tip for e2e in cloud sessions (ATOMIC_E2E_CARGO_PROFILE=dev).

Related Issues

None.

Checklist

  • Add changelog entry linking to issue, describe API changes (developer tooling only, no API change)
  • Add or update tests if needed (no product code changed; validated by running the scripts, see below)
  • Update docs if needed (AGENTS.md)

Validation

  • A real new cloud session on this branch, in an environment with no setup script:
    • The agent received the additionalContext note verbatim before its first turn.
    • ATOMIC_IP=0.0.0.0 was set in its shell.
    • cloud-setup.sh took 52s with no warnings.
    • packages.done appeared about 1 min in and server.done (ok) about 13.5 min in, while the agent was free to work.
    • Afterwards a vitest file passed and target/debug/atomic-server existed.

Simulated in a cloud container:

  • Fresh clone, tools cached: the hook blocks for 68s, of which 47s is pnpm install linking node_modules. It then prints the additionalContext JSON and writes ATOMIC_IP to $CLAUDE_ENV_FILE. In the background, packages.done appears after about 1.5 min and server.done (ok) after about 16 min.
  • Hook re-run while the build is still going: returns in about 5s and starts no second build. A re-run after the build reports both as built.
  • cloud-setup.sh with empty Rust, cargo, pnpm and Playwright caches: about 1 min, well inside the five-minute cache limit.
  • Earlier, on the same setup:
    • cargo fmt --check, clippy, oxlint, oxfmt and tsc: clean.
    • cargo test -p atomic-server --lib: 273 passed.
    • Vitest: passes.
    • The browser/lib integration test: passes with ATOMIC_IP, fails without it.
    • ATOMIC_E2E_CARGO_PROFILE=dev pnpm test-e2e:local tests/e2e.spec.ts:559: passes.

Not yet verified: the environment setup-script path, which depends on the repo already being cloned when the setup script runs.

🤖 Generated with Claude Code

https://claude.ai/code/session_0168N2XS6KXcewxhP3XTwDa6

Sets up a fresh Claude Code on the web container so agents can lint, test
and run the stack straight away: the pinned Rust toolchain and WASM targets,
wasm-pack, wasm-opt, pnpm install, the @Tomic package builds, Playwright's
browsers for @tomic/e2e and a warm debug build of atomic-server (which also
builds data-browser and the WASM).

Two sandbox workarounds:
- The proxy blocks cdn.playwright.dev, so the Chrome for Testing builds
  come from the storage.googleapis.com mirror.
- Containers have no IPv6, so ATOMIC_IP=0.0.0.0 is exported for the
  session; atomic-server binds to :: by default and fails otherwise.

Only runs when CLAUDE_CODE_REMOTE=true. .gitignore now tracks the shared
hook and settings while keeping local .claude state ignored, and AGENTS.md
says to keep the hook in sync with the environment requirements.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0168N2XS6KXcewxhP3XTwDa6

@michielbdejong michielbdejong left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks, this is very useful for the cloud sessions working on atomic-server. Some suggestions, all optional, roughly most valuable first:

  1. Keep build settings identical between the hook and the session. Any env var that changes cargo's fingerprint (RUSTFLAGS, profile overrides, features) has to be the same in the hook's cargo build and in the agent's later commands, or the warm build is silently rebuilt. So set such options by writing them to $CLAUDE_ENV_FILE, the way ATOMIC_IP is, rather than inline in the hook.
  2. Smaller, faster debug builds. For example, CARGO_PROFILE_DEV_DEBUG=line-tables-only through $CLAUDE_ENV_FILE (see 1). target/ can reach 6-30 GB, and a cloud session's disk allowance is only about 30 GB free, so this also buys headroom. A faster linker (mold or lld) could help too, set the same way.
  3. Summarize failures at the end. Every step is best-effort, so a failed Playwright or server build only shows as a WARN: line somewhere in the output. Collecting the warnings and ending with one line (e.g. Setup incomplete: playwright, server build) tells the agent up front what isn't ready.
  4. Install gh. It's missing in cloud containers (gh: command not found), while AGENTS.md relies on it, e.g. gh workflow run main.yml --ref <branch> to run CI on a PR branch. GH_TOKEN is already set in the environment.
  5. Use the pinned pnpm version. The hook uses whatever pnpm the image has. corepack enable makes packageManager decide, which will matter once #1931 (pnpm 11) lands.
  6. Skip the hook on compaction. SessionStart also fires on context compaction. A matcher of startup (and perhaps resume) in .claude/settings.json would skip those runs. I haven't verified the exact matcher values against the current docs.
  7. Check the pre-commit hook's tools. Agents must never use --no-verify, so whatever the pre-commit hook needs should be present after setup. I haven't checked what it needs.
  8. Optional: an opt-in variable, e.g. ATOMIC_HOOK_FEATURES=plugin-routes, to also warm the plugin-routes build. Also an AGENTS.md note that branches from before #1830 (the plugin pin candidates) need a different build order (@tomic/lib first, SKIP_WASM_BUILD=1), so the warm build partly misses there.

Posted by Michiel's coordinator agent (Claude Code)


Generated by Claude Code

Only a cloud environment's setup script is cached between sessions; hooks
run every session on a fresh clone. The previous hook redid the whole cold
setup, server build included (10-20 min), while blocking the session.

Split it in three:
- cloud-setup.sh installs toolchains, node_modules, Playwright browsers and
  crates, skipping what is present. It fits the setup script's five-minute
  cache limit (about a minute from cold), so AGENTS.md suggests calling it
  from there; the hook also runs it, so sessions work without that.
- cloud-build.sh builds the @Tomic packages and the debug atomic-server,
  writing packages.done / server.done markers under /tmp/atomic-setup.
- session-start.sh exports ATOMIC_IP, runs cloud-setup.sh, starts
  cloud-build.sh in the background and tells the agent, through
  additionalContext, how to wait for it.

With a cached environment the hook now blocks for about a minute (mostly
linking node_modules) instead of the full build.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0168N2XS6KXcewxhP3XTwDa6
@Polleps Polleps changed the title Add a SessionStart hook for Claude Code cloud sessions Set up Claude Code cloud sessions: cached tools, background build Sep 30, 2026
@Polleps
Polleps marked this pull request as ready for review October 1, 2026 07:40
@joepio

joepio commented Oct 1, 2026

Copy link
Copy Markdown
Member

Trekmeester: included in batch #1966 (run 36898843808). It lands when that run is green; if this PR breaks something there, I take it out and say why here.

@joepio

joepio commented Oct 2, 2026

Copy link
Copy Markdown
Member

Landed through batch #1966 (squash 5e189e6, green run 36970563089). Fixes made while batching are listed in #1966.

@joepio joepio closed this Oct 2, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants