Set Up a Claude Code Cloud Session
Who is this for (1)
- Stakeholder Persona: Maintainer — Written for the Maintainer reader.
This page is for maintainers and contributors who run Spec Kitty Missions or
Ops in a Claude Code cloud session. When you finish, the session has the
spec-kitty CLI installed from your checkout, the test dependencies synced, and
the pinned packs in place, and a CodeGraph index ready to query.
Setup has two layers:
- An environment setup script. It lives in the cloud environment settings, outside the repository, and runs when the container is built.
- A repository script,
scripts/dev/cloud-session-setup.sh. You run it once per session from the repository root.
Step 1: Add the environment setup script
- Open the environment menu in the session title bar.
- Choose Edit, then Setup script.
- Paste this script and save:
#!/bin/bashset -euo pipefailcodegraph install --yes --target claude --location global || truecommand -v uv >/dev/null || curl -LsSf https://astral.sh/uv/install.sh | shThe script installs CodeGraph, registers it with Claude Code, and installs uv
if it is missing. New sessions pick up the change. If your environment clones the
repository before this script runs, you can also fold the per-session Step 2 work
in here — see
Optional: run the repository script from the environment setup script.
The codegraph install line has not been tested end to end, so it ends in
|| true: a failure there does not stop the container build. If the CodeGraph
tools are missing later, see Troubleshooting.
The full environment setup script
The script above is the minimum. The environment the core team uses also
installs a pinned Java 25, resolves Maven Central through a mirror for the
Gradle builds of the service repositories, warms up the core checkout, and
installs the spec-kitty CLI from source, including for sessions that have no
core checkout. That script, its network hosts and a step-by-step explanation
are on Set up a Claude Code cloud environment.
Optional: environment variables
In the same environment settings, under Environment variables, you can set:
PWHEADLESS=1CODEGRAPH_TELEMETRY=0SPEC_KITTY_NO_NAG=1SPEC_KITTY_NO_UPGRADE_CHECK=1PWHEADLESS=1runs Playwright tests headless.CODEGRAPH_TELEMETRY=0turns off CodeGraph usage reporting.SPEC_KITTY_NO_NAG=1hides the “newer version on PyPI” banner. The CLI comes from your checkout, so the banner does not apply.SPEC_KITTY_NO_UPGRADE_CHECK=1skips the PyPI version check and its network call.
The repository script also sets the first two for each session. Setting them here makes them hold even when nobody runs the script.
Do not set these:
SPEC_KITTY_SKIP_PRE_REVIEW_GATE: it bypasses a governance gate.SPEC_KITTY_RUN_P0_REPROorSPEC_KITTY_RUN_QUARANTINE: they add test suites that are expected to fail.SPEC_KITTY_ENABLE_SAAS_SYNC: it is left over from the retired sync transport and does nothing.
What SPEC_KITTY_NON_INTERACTIVE does
This page does not recommend a value for SPEC_KITTY_NON_INTERACTIVE. It
controls whether spec-kitty may stop and wait for a person to answer a prompt,
such as a confirmation or an interview question. The CLI decides in this order
(is_interactive() in src/specify_cli/core/env.py):
SPEC_KITTY_FORCE_INTERACTIVEset to a true value: prompts are allowed.SPEC_KITTY_NON_INTERACTIVEset to a true value: prompts are skipped.- Otherwise, prompts are allowed only when stdin is a terminal.
Setting SPEC_KITTY_NON_INTERACTIVE=0 is the same as leaving it unset, so the
CLI falls through to the terminal check. Commands an agent runs in a cloud
session usually have no terminal on stdin, so prompts are skipped there either
way. Forcing prompts on with SPEC_KITTY_FORCE_INTERACTIVE=1 in an agent
session can make a command wait forever, because nobody can type an answer.
Step 2: Run the repository script in each session
From the repository root:
bash scripts/dev/cloud-session-setup.shThe script does nothing unless CLAUDE_CODE_REMOTE=true, so it is safe to run
on a local machine. In a cloud session it:
- runs
uv sync --frozen --all-extras, which installs the test extras andpytest-xdist; - syncs the pinned packs, as
make sync-packsdoes, sopacks/built-inandpacks/internalare in place before anyspec-kittycommand runs. Without them a command fails withBuiltInPackMissingor reports a charter context error. It first checks the placed trees offline and fetches only when one is missing or stale. A failed fetch stops the script; - fetches the pinned service extras, as
make sync-services ARGS=--extras-only(part ofmake dev-setup) does. The contract and conformance tests read them and fail without them. The CLI does not need them, so a failure here prints a note and the script goes on; - installs
build; - runs
uv pip install -e ., so thespec-kittyCLI comes from your checkout. Tests that startspec-kittyas a subprocess need this; - writes
PWHEADLESS=1andCODEGRAPH_TELEMETRY=0toCLAUDE_ENV_FILE, when that file exists; - adds
.codegraph/to.git/info/exclude. An untracked index would make the working tree dirty, and a dirty tree trips theWRITE_CHECKOUT_DIRTYand dirty-worktree guards; - starts
codegraph initin the background whencodegraphis onPATHand no index exists yet. This takes about 2 minutes and about 440 MB. The log is at/tmp/codegraph-init.log. The CodeGraph MCP server picks up the index as soon as it is written; you do not need to restart.
When everything is already in place, the script finishes in a few seconds (about 3 seconds measured, with the pack check and the cached service extras).
Optional: run the repository script from the environment setup script
If your cloud environment clones the repository before the environment setup script runs, you can fold Step 2 into Step 1 and skip the per-session run. Append this to the environment setup script (Step 1):
repo="${CLAUDE_PROJECT_DIR:-}"if [ -n "$repo" ] && [ -d "$repo/.git" ]; then (cd "$repo" && bash scripts/dev/cloud-session-setup.sh) || truefiThis is clone-order safe: when the checkout is not present yet (the common case,
where the environment setup script runs at container-build time, before the repo
lands), the guard makes it a no-op and you keep running the script by hand each
session. When the clone is present, it runs the repository script for you. The
trailing || true keeps a failure from breaking the container build.
The repository script is itself idempotent and gated on CLAUDE_CODE_REMOTE, so
appending this line never does harm — the worst case is that it no-ops.
Why this is not a committed SessionStart hook
Spec Kitty writes its own hooks into .claude/settings.json. If that file were
tracked with a setup hook in it, every checkout would become dirty. Running the
script by hand (or wiring it in as above) keeps the tree clean.
Step 3: Check the result
.venv/bin/spec-kitty --version # CLI installed from the checkoutuv run --frozen python scripts/sync_packs.py --check # packs in place: "built-in: ok", "internal: ok"make test-fast # test package and pytest-xdist workcodegraph status # index statetail /tmp/codegraph-init.log # progress of a background index buildTroubleshooting
- CodeGraph tools are missing in a new session. Run
codegraph install --print-config claudeand add the printed configuration by hand. - Imports fail for a package that is declared and pinned. The virtual
environment is stale. Run
uv sync --frozen --all-extrasagain. - The environment setup script fails. Fix it in the environment settings (Step 1). New sessions use the fixed script.