<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/development/how-to/cloud-session-setup/">
  <id>https://docs.spec-kitty.ai/development/how-to/cloud-session-setup/</id>
  <title>Set Up a Claude Code Cloud Session</title>
  <updated>2026-11-20T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/development/how-to/cloud-session-setup/"/>
  <summary>Prepare a Claude Code cloud session so the Spec Kitty CLI, the test package and CodeGraph are ready before you run a Mission or an Op.</summary>
  <content type="html">&lt;span id=&quot;set-up-a-claude-code-cloud-session&quot;&gt;&lt;/span&gt;
&lt;p&gt;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
&lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt; CLI installed from your checkout, the test dependencies synced, and
the pinned packs in place, and a CodeGraph index ready to query.&lt;/p&gt;
&lt;p&gt;Setup has two layers:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;An &lt;strong&gt;environment setup script&lt;/strong&gt;. It lives in the cloud environment settings,
outside the repository, and runs when the container is built.&lt;/li&gt;
&lt;li&gt;A &lt;strong&gt;repository script&lt;/strong&gt;, &lt;code dir=&quot;auto&quot;&gt;scripts/dev/cloud-session-setup.sh&lt;/code&gt;. You run it
once per session from the repository root.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;step-1-add-the-environment-setup-script&quot;&gt;Step 1: Add the environment setup script&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;Open the environment menu in the session title bar.&lt;/li&gt;
&lt;li&gt;Choose &lt;strong&gt;Edit&lt;/strong&gt;, then &lt;strong&gt;Setup script&lt;/strong&gt;.&lt;/li&gt;
&lt;li&gt;Paste this script and save:&lt;/li&gt;
&lt;/ol&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;#!/bin/bash&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;set&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;-euo&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;pipefail&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;npm&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;install&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;-g&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;@colbymchenry/codegraph@1.6.2&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;codegraph&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;install&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--yes&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--target&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;claude&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--location&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;global&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;||&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;true&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;command&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;-v&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;uv&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;&gt;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;/dev/null&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;||&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;curl&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;-LsSf&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;https://astral.sh/uv/install.sh&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;|&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;sh&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;The script installs CodeGraph, registers it with Claude Code, and installs &lt;code dir=&quot;auto&quot;&gt;uv&lt;/code&gt;
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
&lt;a href=&quot;#optional-run-the-repository-script-from-the-environment-setup-script&quot;&gt;Optional: run the repository script from the environment setup script&lt;/a&gt;.&lt;/p&gt;
&lt;p&gt;The &lt;code dir=&quot;auto&quot;&gt;codegraph install&lt;/code&gt; line has not been tested end to end, so it ends in
&lt;code dir=&quot;auto&quot;&gt;|| true&lt;/code&gt;: a failure there does not stop the container build. If the CodeGraph
tools are missing later, see &lt;a href=&quot;#troubleshooting&quot;&gt;Troubleshooting&lt;/a&gt;.&lt;/p&gt;
&lt;h3 id=&quot;the-full-environment-setup-script&quot;&gt;The full environment setup script&lt;/h3&gt;
&lt;p&gt;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 &lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt; CLI from source, including for sessions that have no
core checkout. That script, its network hosts and a step-by-step explanation
are on &lt;a href=&quot;/development/how-to/cloud-environment-setup/&quot;&gt;Set up a Claude Code cloud environment&lt;/a&gt;.&lt;/p&gt;
&lt;h3 id=&quot;optional-environment-variables&quot;&gt;Optional: environment variables&lt;/h3&gt;
&lt;p&gt;In the same environment settings, under &lt;strong&gt;Environment variables&lt;/strong&gt;, you can set:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;plaintext&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;PWHEADLESS=1&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;CODEGRAPH_TELEMETRY=0&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;SPEC_KITTY_NO_NAG=1&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#d6deeb;--1:#403f53&quot;&gt;SPEC_KITTY_NO_UPGRADE_CHECK=1&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;PWHEADLESS=1&lt;/code&gt; runs Playwright tests headless.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;CODEGRAPH_TELEMETRY=0&lt;/code&gt; turns off CodeGraph usage reporting.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_NO_NAG=1&lt;/code&gt; hides the “newer version on PyPI” banner. The CLI
comes from your checkout, so the banner does not apply.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_NO_UPGRADE_CHECK=1&lt;/code&gt; skips the PyPI version check and its network
call.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The repository script also sets the first two for each session. Setting them
here makes them hold even when nobody runs the script.&lt;/p&gt;
&lt;p&gt;Do not set these:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_SKIP_PRE_REVIEW_GATE&lt;/code&gt;: it bypasses a governance gate.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_RUN_P0_REPRO&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_RUN_QUARANTINE&lt;/code&gt;: they add test
suites that are expected to fail.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_ENABLE_SAAS_SYNC&lt;/code&gt;: it is left over from the retired sync
transport and does nothing.&lt;/li&gt;
&lt;/ul&gt;
&lt;h4 id=&quot;what-spec_kitty_non_interactive-does&quot;&gt;What &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_NON_INTERACTIVE&lt;/code&gt; does&lt;/h4&gt;
&lt;p&gt;This page does not recommend a value for &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_NON_INTERACTIVE&lt;/code&gt;. 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
(&lt;code dir=&quot;auto&quot;&gt;is_interactive()&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/core/env.py&lt;/code&gt;):&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_FORCE_INTERACTIVE&lt;/code&gt; set to a true value: prompts are allowed.&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_NON_INTERACTIVE&lt;/code&gt; set to a true value: prompts are skipped.&lt;/li&gt;
&lt;li&gt;Otherwise, prompts are allowed only when stdin is a terminal.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Setting &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_NON_INTERACTIVE=0&lt;/code&gt; 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 &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_FORCE_INTERACTIVE=1&lt;/code&gt; in an agent
session can make a command wait forever, because nobody can type an answer.&lt;/p&gt;
&lt;h2 id=&quot;step-2-run-the-repository-script-in-each-session&quot;&gt;Step 2: Run the repository script in each session&lt;/h2&gt;
&lt;p&gt;From the repository root:&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;bash&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;scripts/dev/cloud-session-setup.sh&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;The script does nothing unless &lt;code dir=&quot;auto&quot;&gt;CLAUDE_CODE_REMOTE=true&lt;/code&gt;, so it is safe to run
on a local machine. In a cloud session it:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;runs &lt;code dir=&quot;auto&quot;&gt;uv sync --frozen --all-extras&lt;/code&gt;, which installs the test extras and
&lt;code dir=&quot;auto&quot;&gt;pytest-xdist&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;syncs the pinned packs, as &lt;code dir=&quot;auto&quot;&gt;make sync-packs&lt;/code&gt; does, so &lt;code dir=&quot;auto&quot;&gt;packs/built-in&lt;/code&gt; and
&lt;code dir=&quot;auto&quot;&gt;packs/internal&lt;/code&gt; are in place before any &lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt; command runs. Without
them a command fails with &lt;code dir=&quot;auto&quot;&gt;BuiltInPackMissing&lt;/code&gt; or 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;&lt;/li&gt;
&lt;li&gt;fetches the pinned service extras, as &lt;code dir=&quot;auto&quot;&gt;make sync-services ARGS=--extras-only&lt;/code&gt;
(part of &lt;code dir=&quot;auto&quot;&gt;make dev-setup&lt;/code&gt;) 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;&lt;/li&gt;
&lt;li&gt;installs &lt;code dir=&quot;auto&quot;&gt;build&lt;/code&gt;;&lt;/li&gt;
&lt;li&gt;runs &lt;code dir=&quot;auto&quot;&gt;uv pip install -e .&lt;/code&gt;, so the &lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt; CLI comes from your checkout.
Tests that start &lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt; as a subprocess need this;&lt;/li&gt;
&lt;li&gt;writes &lt;code dir=&quot;auto&quot;&gt;PWHEADLESS=1&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;CODEGRAPH_TELEMETRY=0&lt;/code&gt; to &lt;code dir=&quot;auto&quot;&gt;CLAUDE_ENV_FILE&lt;/code&gt;, when
that file exists;&lt;/li&gt;
&lt;li&gt;adds &lt;code dir=&quot;auto&quot;&gt;.codegraph/&lt;/code&gt; to &lt;code dir=&quot;auto&quot;&gt;.git/info/exclude&lt;/code&gt;. An untracked index would make the
working tree dirty, and a dirty tree trips the &lt;code dir=&quot;auto&quot;&gt;WRITE_CHECKOUT_DIRTY&lt;/code&gt; and
dirty-worktree guards;&lt;/li&gt;
&lt;li&gt;starts &lt;code dir=&quot;auto&quot;&gt;codegraph init&lt;/code&gt; in the background when &lt;code dir=&quot;auto&quot;&gt;codegraph&lt;/code&gt; is on &lt;code dir=&quot;auto&quot;&gt;PATH&lt;/code&gt; and no
index exists yet. This takes about 2 minutes and about 440 MB. The log is at
&lt;code dir=&quot;auto&quot;&gt;/tmp/codegraph-init.log&lt;/code&gt;. The CodeGraph MCP server picks up the index as soon
as it is written; you do not need to restart.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;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).&lt;/p&gt;
&lt;h3 id=&quot;optional-run-the-repository-script-from-the-environment-setup-script&quot;&gt;Optional: run the repository script from the environment setup script&lt;/h3&gt;
&lt;p&gt;If your cloud environment clones the repository &lt;em&gt;before&lt;/em&gt; 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):&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;repo&lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;=&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;${&lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;CLAUDE_PROJECT_DIR&lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;:-&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;}&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;if&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; [ &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;-n&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;$repo&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; ] &amp;#x26;&amp;#x26; [ &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;-d&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;$repo&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;/.git&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; ]; &lt;/span&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;then&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;  &lt;/span&gt;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;(&lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;cd&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;$repo&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&quot;&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &amp;#x26;&amp;#x26; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;bash&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;scripts/dev/cloud-session-setup.sh&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;) &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#096E72&quot;&gt;||&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#C5E478;--1:#3B61B0&quot;&gt;true&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#C792EA;--1:#8844AE&quot;&gt;fi&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;This 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 &lt;em&gt;is&lt;/em&gt; present, it runs the repository script for you. The
trailing &lt;code dir=&quot;auto&quot;&gt;|| true&lt;/code&gt; keeps a failure from breaking the container build.&lt;/p&gt;
&lt;p&gt;The repository script is itself idempotent and gated on &lt;code dir=&quot;auto&quot;&gt;CLAUDE_CODE_REMOTE&lt;/code&gt;, so
appending this line never does harm — the worst case is that it no-ops.&lt;/p&gt;
&lt;h3 id=&quot;why-this-is-not-a-committed-sessionstart-hook&quot;&gt;Why this is not a committed SessionStart hook&lt;/h3&gt;
&lt;p&gt;Spec Kitty writes its own hooks into &lt;code dir=&quot;auto&quot;&gt;.claude/settings.json&lt;/code&gt;. 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.&lt;/p&gt;
&lt;h2 id=&quot;step-3-check-the-result&quot;&gt;Step 3: Check the result&lt;/h2&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame is-terminal not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;span class=&quot;title&quot;&gt;&lt;/span&gt;&lt;span class=&quot;sr-only&quot;&gt;Terminal window&lt;/span&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;bash&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;.venv/bin/spec-kitty&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--version&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;   &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# CLI installed from the checkout&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;uv&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;run&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--frozen&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;python&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;scripts/sync_packs.py&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;--check&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;   &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# packs in place: &quot;built-in: ok&quot;, &quot;internal: ok&quot;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;make&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;test-fast&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;                   &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# test package and pytest-xdist work&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;codegraph&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;status&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;                 &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# index state&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;tail&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt; &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;/tmp/codegraph-init.log&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;     &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# progress of a background index build&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;h2 id=&quot;troubleshooting&quot;&gt;Troubleshooting&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;CodeGraph tools are missing in a new session.&lt;/strong&gt; Run
&lt;code dir=&quot;auto&quot;&gt;codegraph install --print-config claude&lt;/code&gt; and add the printed configuration
by hand.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Imports fail for a package that is declared and pinned.&lt;/strong&gt; The virtual
environment is stale. Run &lt;code dir=&quot;auto&quot;&gt;uv sync --frozen --all-extras&lt;/code&gt; again.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;The environment setup script fails.&lt;/strong&gt; Fix it in the environment settings
(Step 1). New sessions use the fixed script.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;see-also&quot;&gt;See also&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/development/contributing/&quot;&gt;Contributing to Spec Kitty&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/development/how-to/local-overrides/&quot;&gt;Local overrides for cross-package development&lt;/a&gt;&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/development/how-to/&quot;&gt;How-to index&lt;/a&gt;&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
