<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/development/getting-started/isolated-dev-environments/">
  <id>https://docs.spec-kitty.ai/development/getting-started/isolated-dev-environments/</id>
  <title>Isolated Dev Environments (Shadow Clones)</title>
  <updated>2026-10-13T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/development/getting-started/isolated-dev-environments/"/>
  <summary>Run several standalone spec-kitty checkouts on one machine without cross-mission pollution: a clone-local venv plus a clone-local runtime-state root, machine-global CLI intact.</summary>
  <content type="html">&lt;span id=&quot;isolated-dev-environments-shadow-clones&quot;&gt;&lt;/span&gt;
&lt;p&gt;Working on spec-kitty often means running the CLI &lt;strong&gt;against a checkout while you
are editing that same checkout’s source&lt;/strong&gt;. When you keep more than one checkout
on a machine — a stable primary plus one or more experiment branches — two of
them can quietly interfere with each other. This guide sets up a &lt;strong&gt;Shadow
Clone&lt;/strong&gt;: a standalone spec-kitty checkout whose CLI &lt;em&gt;and&lt;/em&gt; runtime state are
pinned to itself, so nothing it does leaks into the machine-global install or
into sibling clones.&lt;/p&gt;
&lt;p&gt;This is the non-containerised option. It is chosen deliberately for speed and
low overhead; a container gives stronger isolation but costs startup time and
disk on every invocation. If you need hard OS-level isolation, containerise
instead — this guide is for the fast, everyday case.&lt;/p&gt;
&lt;h2 id=&quot;the-two-things-that-actually-leak&quot;&gt;The two things that actually leak&lt;/h2&gt;
&lt;p&gt;Isolation has exactly two axes. Miss either one and the clones are still
entangled.&lt;/p&gt;




















&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Axis&lt;/th&gt;&lt;th&gt;What leaks if unisolated&lt;/th&gt;&lt;th&gt;The lever&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;Code&lt;/strong&gt; — which &lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt; runs&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt; on your &lt;code dir=&quot;auto&quot;&gt;PATH&lt;/code&gt; resolves to the &lt;em&gt;machine-global&lt;/em&gt; binary, so it runs global code against the clone’s files. Edits to the clone’s &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt; have no effect until the global install is rebuilt.&lt;/td&gt;&lt;td&gt;A clone-local &lt;code dir=&quot;auto&quot;&gt;.venv&lt;/code&gt; (editable install) placed &lt;strong&gt;first&lt;/strong&gt; on &lt;code dir=&quot;auto&quot;&gt;PATH&lt;/code&gt;.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;strong&gt;State&lt;/strong&gt; — where the CLI reads/writes&lt;/td&gt;&lt;td&gt;With &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_HOME&lt;/code&gt; unset, every clone shares one runtime-state root at &lt;code dir=&quot;auto&quot;&gt;~/.spec-kitty&lt;/code&gt; — auth tokens (&lt;code dir=&quot;auto&quot;&gt;auth/&lt;/code&gt;), &lt;code dir=&quot;auto&quot;&gt;config.toml&lt;/code&gt;, tracker credentials and stores, and the pre-review gate locks (&lt;code dir=&quot;auto&quot;&gt;gate-locks/&lt;/code&gt;). One clone’s gate lock or tracker state then affects another clone’s work.&lt;/td&gt;&lt;td&gt;Point &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_HOME&lt;/code&gt; at a clone-local directory.&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_HOME&lt;/code&gt; is the single environment variable that redirects the runtime
state. When set, it is used &lt;strong&gt;verbatim&lt;/strong&gt; as the state root (it is &lt;em&gt;not&lt;/em&gt; suffixed
with &lt;code dir=&quot;auto&quot;&gt;.spec-kitty&lt;/code&gt;), and it redirects both resolvers the codebase relies on —
&lt;code dir=&quot;auto&quot;&gt;get_runtime_root()&lt;/code&gt; (runtime state) and &lt;code dir=&quot;auto&quot;&gt;get_kittify_home()&lt;/code&gt; (asset home). See
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/src/kernel/paths.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;src/kernel/paths.py&lt;/code&gt;&lt;/a&gt; and
&lt;a href=&quot;https://github.com/spec-kitty/spec-kitty/blob/main/src/specify_cli/paths/windows_paths.py&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/paths/windows_paths.py&lt;/code&gt;&lt;/a&gt;.&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;The parallel test suite isolates itself the same way — each &lt;code dir=&quot;auto&quot;&gt;pytest-xdist&lt;/code&gt;
worker gets its own &lt;code dir=&quot;auto&quot;&gt;HOME&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_HOME&lt;/code&gt; so a run never touches the real
&lt;code dir=&quot;auto&quot;&gt;~/.spec-kitty&lt;/code&gt;. A Shadow Clone applies that discipline to interactive
sessions.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;h2 id=&quot;mental-model-primary-vs-shadow&quot;&gt;Mental model: primary vs. shadow&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Primary checkout&lt;/strong&gt; — your stable clone. Its build backs the
&lt;strong&gt;machine-global&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt; you use everywhere &lt;em&gt;outside&lt;/em&gt; a Shadow Clone.
When no Shadow Clone is active, the machine-global CLI is what runs.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Shadow Clone&lt;/strong&gt; — any additional isolated checkout. Inside its session, a
clone-local &lt;code dir=&quot;auto&quot;&gt;.venv&lt;/code&gt; and a clone-local state root take over; outside, nothing
changed.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;A Git worktree can use the same isolation: create its own &lt;code dir=&quot;auto&quot;&gt;.venv&lt;/code&gt;, then
activate from inside that worktree. If its older branch lacks the helper,
source the helper from a checkout that has it by absolute path — it still
binds the current worktree.&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;Do not activate inside a spec-kitty-managed worktree under &lt;code dir=&quot;auto&quot;&gt;.worktrees/&lt;/code&gt; (a
lane, coord, or mission tree). The runtime creates and force-removes those
itself during &lt;code dir=&quot;auto&quot;&gt;consolidate&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;context cleanup&lt;/code&gt;; because the clone-local
&lt;code dir=&quot;auto&quot;&gt;.spec-kitty-home/&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;.venv/&lt;/code&gt; are git-ignored, teardown deletes them along
with the worktree and leaves your shell pointing at a &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_HOME&lt;/code&gt; and a
&lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt; CLI that no longer exist. Use a worktree you create yourself,
outside &lt;code dir=&quot;auto&quot;&gt;.worktrees/&lt;/code&gt;.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;Activation isolates your dev-env state root, not a Mission’s write target.&lt;/strong&gt;
Sourcing the helper inside a worktree binds &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_HOME&lt;/code&gt; — and with it
your auth session, gate-locks, and tracker bindings under &lt;code dir=&quot;auto&quot;&gt;.spec-kitty-home/&lt;/code&gt;
— to that worktree. The product’s own write-side root resolver does the
opposite: &lt;code dir=&quot;auto&quot;&gt;locate_project_root&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;get_main_repo_root&lt;/code&gt; re-anchor a linked
worktree back to the &lt;strong&gt;repository-root checkout&lt;/strong&gt; (the PRIMARY-partition root
a Mission’s writes land in — &lt;em&gt;not&lt;/em&gt; the Primary Branch &lt;code dir=&quot;auto&quot;&gt;main&lt;/code&gt;), so a worktree
is not a distinct write target to it. The two resolvers therefore disagree
about “where you are”: drive one Mission partly from a repository-root-checkout
shell and partly from a worktree-activated shell, and its gate-locks and
ledger split across two state roots and stop coordinating. Shadow Clone
activation is a dev-env convenience for running the CLI and tests against a
checkout — it is &lt;strong&gt;not&lt;/strong&gt; a way to own a Mission from a worktree.
Mission-mutating commands fail closed when run from a checkout the Mission
does not own; to give a Mission its own linked-worktree checkout — isolating
runtime state &lt;em&gt;and&lt;/em&gt; mission/ref writes together — use the product’s explicit
owned-checkout scope (&lt;code dir=&quot;auto&quot;&gt;--owned-checkout&lt;/code&gt;), not a Shadow Clone shell.
Background: ADR &lt;a href=&quot;/adr/4.x/2026-10-10-1-scoped-shadow-workspace-write-boundary-layers-onto-the-partition/&quot;&gt;scoped shadow workspace write boundary&lt;/a&gt;.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;The rest of this guide keeps those two intact at the same time: the global CLI
stays the default everywhere, and each Shadow Clone overrides it only for the
shell session you activate.&lt;/p&gt;
&lt;h2 id=&quot;one-time-machine-setup-the-global-cli&quot;&gt;One-time machine setup (the global CLI)&lt;/h2&gt;
&lt;p&gt;Do this once, from your &lt;strong&gt;primary&lt;/strong&gt; checkout, so that &lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt; works from
any directory that is &lt;em&gt;not&lt;/em&gt; an activated Shadow Clone. Two supported shapes:&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;A. Snapshot from source (recommended default).&lt;/strong&gt; Install the primary
checkout’s build into an isolated app environment with
&lt;a href=&quot;https://pipx.pypa.io/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;pipx&lt;/code&gt;&lt;/a&gt;. This gives you a global &lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt; that is
your fork’s code rather than the published PyPI release, without putting the
primary checkout’s &lt;code dir=&quot;auto&quot;&gt;.venv&lt;/code&gt; on your &lt;code dir=&quot;auto&quot;&gt;PATH&lt;/code&gt;:&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:#919F9F;--1:#5F636F&quot;&gt;# from the primary checkout root&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;pipx&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;--force&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;.&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Re-run that command whenever you want the global CLI to pick up new primary-
checkout changes. It is a &lt;strong&gt;snapshot&lt;/strong&gt;, not a live link: editing the primary
checkout’s source does not change the global CLI until you reinstall.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;B. Live editable link.&lt;/strong&gt; If you want the global CLI to always track the
primary checkout’s working tree, install it editable into a dedicated
environment instead:&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:#919F9F;--1:#5F636F&quot;&gt;# from the primary checkout root&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;pipx&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;--force&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;--editable&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;.&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Either way, confirm the global resolves as expected from a neutral directory:&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;cd&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;~&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;# anywhere that is not a Shadow Clone&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;spec-kitty&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;# -&gt; ~/.local/bin/spec-kitty (the pipx shim)&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;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;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;blockquote&gt;
&lt;p&gt;Keep the primary checkout’s own &lt;code dir=&quot;auto&quot;&gt;.venv&lt;/code&gt; for running its tests, but do &lt;strong&gt;not&lt;/strong&gt;
add it to your shell’s default &lt;code dir=&quot;auto&quot;&gt;PATH&lt;/code&gt;. The global shim is the machine default;
the primary &lt;code dir=&quot;auto&quot;&gt;.venv&lt;/code&gt; is just how you test the primary checkout.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;h2 id=&quot;per-clone-setup-each-shadow-clone&quot;&gt;Per-clone setup (each Shadow Clone)&lt;/h2&gt;
&lt;p&gt;For every additional checkout you want to isolate:&lt;/p&gt;
&lt;h3 id=&quot;1-create-the-clone-local-virtualenv-editable-install--dev-extras&quot;&gt;1. Create the clone-local virtualenv (editable install + dev extras)&lt;/h3&gt;
&lt;p&gt;Use the project’s canonical install — the same command
&lt;a href=&quot;/development/contributing/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;contributing.md&lt;/code&gt;&lt;/a&gt; prescribes. From the clone root it creates
&lt;code dir=&quot;auto&quot;&gt;.venv&lt;/code&gt;, installs the clone &lt;strong&gt;editable&lt;/strong&gt; (so the CLI always runs the clone’s live
&lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt;), and pulls in the dev extras — the &lt;code dir=&quot;auto&quot;&gt;test&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;lint&lt;/code&gt; optional-dependency
groups (&lt;code dir=&quot;auto&quot;&gt;pytest&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;pytest-xdist&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;ruff&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;mypy&lt;/code&gt;, …) plus the &lt;code dir=&quot;auto&quot;&gt;dev&lt;/code&gt; dependency
group — resolved from the committed &lt;code dir=&quot;auto&quot;&gt;uv.lock&lt;/code&gt;:&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:#919F9F;--1:#5F636F&quot;&gt;# from the Shadow Clone root&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;sync&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:#82AAFF;--1:#3B61B0&quot;&gt;--all-extras&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Do &lt;strong&gt;not&lt;/strong&gt; skip the dev extras: a Shadow Clone you cannot run the test suite,
&lt;code dir=&quot;auto&quot;&gt;ruff&lt;/code&gt;, or &lt;code dir=&quot;auto&quot;&gt;mypy&lt;/code&gt; in is a half-isolated clone that still forces you back to
another checkout to validate a change. &lt;code dir=&quot;auto&quot;&gt;uv sync&lt;/code&gt; installs them by default here,
so a correctly set-up clone is self-sufficient.&lt;/p&gt;
&lt;blockquote&gt;
&lt;p&gt;&lt;strong&gt;No &lt;code dir=&quot;auto&quot;&gt;uv&lt;/code&gt;?&lt;/strong&gt; Install it (&lt;a href=&quot;https://docs.astral.sh/uv/&quot;&gt;https://docs.astral.sh/uv/&lt;/a&gt;), or fall back to the
stdlib path — but install the extras explicitly so the clone stays
self-sufficient:&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;python3.11&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;-m&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;venv&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;.venv&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;# match the project&apos;s supported Python (3.11+)&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;.venv/bin/python&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;-m&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;pip&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;-e&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;&apos;&lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#984E4D&quot;&gt;.[test,lint]&lt;/span&gt;&lt;span style=&quot;--0:#D9F5DD;--1:#111111&quot;&gt;&apos;&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Playwright’s browser (for &lt;code dir=&quot;auto&quot;&gt;tests/ui/&lt;/code&gt;) is never committed; install it once per
clone when you need the UI e2e tests: &lt;code dir=&quot;auto&quot;&gt;.venv/bin/playwright install chromium&lt;/code&gt;.&lt;/p&gt;
&lt;/blockquote&gt;
&lt;p&gt;Verify the clone-local CLI and dev tools run the clone’s code:&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;.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;/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;.venv/bin/pytest&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; &amp;#x26;&amp;#x26; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;.venv/bin/ruff&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; &amp;#x26;&amp;#x26; &lt;/span&gt;&lt;span style=&quot;--0:#82AAFF;--1:#3B61B0&quot;&gt;.venv/bin/mypy&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;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;.venv/&lt;/code&gt; is already git-ignored, so this never becomes a committed artefact.&lt;/p&gt;
&lt;h3 id=&quot;2-activate-the-isolated-environment-for-your-session&quot;&gt;2. Activate the isolated environment for your session&lt;/h3&gt;
&lt;p&gt;A committed helper does both axes at once for the Git checkout you are in —
prepends that checkout’s &lt;code dir=&quot;auto&quot;&gt;.venv/bin&lt;/code&gt; to &lt;code dir=&quot;auto&quot;&gt;PATH&lt;/code&gt; and points &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_HOME&lt;/code&gt; at a
clone-local state root.
&lt;strong&gt;Source&lt;/strong&gt; it (do not execute it); it works from both &lt;code dir=&quot;auto&quot;&gt;bash&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;zsh&lt;/code&gt;:&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:#919F9F;--1:#5F636F&quot;&gt;# from the Shadow Clone root&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;source&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/activate-isolated-env.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;It prints what it bound and how to undo it:&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;spec-kitty isolated env ACTIVE&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;clone : &amp;#x3C;clone-root&gt;&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;venv  : &amp;#x3C;clone-root&gt;/.venv&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;state : &amp;#x3C;clone-root&gt;/.spec-kitty-home&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;cli   : &amp;#x3C;clone-root&gt;/.venv/bin/spec-kitty&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;undo  : deactivate_spec_kitty&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 helper derives the root from the current Git checkout, falling back to its
own location outside Git. The clone-local state root
(&lt;code dir=&quot;auto&quot;&gt;.spec-kitty-home/&lt;/code&gt;) is git-ignored.&lt;/p&gt;
&lt;p&gt;If an isolated environment for another checkout is already active (for example
you activated in worktree A, then &lt;code dir=&quot;auto&quot;&gt;cd&lt;/code&gt; into worktree B and source the helper
again), the helper first deactivates A, then binds B. A single
&lt;code dir=&quot;auto&quot;&gt;deactivate_spec_kitty&lt;/code&gt; afterwards restores the shell as it was before A.
Sourcing it again in the checkout that is already active changes nothing.&lt;/p&gt;
&lt;p&gt;To restore the shell to the machine-global CLI and unset the overrides:&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;deactivate_spec_kitty&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;h3 id=&quot;3-verify-the-isolation&quot;&gt;3. Verify the isolation&lt;/h3&gt;
&lt;p&gt;With the environment active:&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;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;spec-kitty&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;# -&gt; &amp;#x3C;clone-root&gt;/.venv/bin/spec-kitty&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;echo&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;$SPEC_KITTY_HOME&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:#919F9F;--1:#5F636F&quot;&gt;# -&gt; &amp;#x3C;clone-root&gt;/.spec-kitty-home&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;spec-kitty&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;agent&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;tasks&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;# any command now writes only under .spec-kitty-home/&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;ls&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;.spec-kitty-home&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;# clone-local runtime state (auth/, gate-locks/, ...) appears here&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;Confirm the machine-global root is untouched — nothing new should appear under
&lt;code dir=&quot;auto&quot;&gt;~/.spec-kitty&lt;/code&gt; as a result of commands run inside the Shadow Clone.
The isolated state root starts without a login session, so a tracker or hosted
call that needs authentication finds no credentials until you authenticate
inside the activated Shadow Clone.&lt;/p&gt;
&lt;h2 id=&quot;optional-auto-activate-with-direnv&quot;&gt;Optional: auto-activate with direnv&lt;/h2&gt;
&lt;p&gt;Sourcing by hand is reliable but easy to forget. If you use
&lt;a href=&quot;https://direnv.net/&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;direnv&lt;/code&gt;&lt;/a&gt;, drop an &lt;code dir=&quot;auto&quot;&gt;.envrc&lt;/code&gt; at each clone root so the
environment activates on &lt;code dir=&quot;auto&quot;&gt;cd&lt;/code&gt; and deactivates when you leave:&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:#919F9F;--1:#5F636F&quot;&gt;# &amp;#x3C;clone-root&gt;/.envrc&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;source&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/activate-isolated-env.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;Then &lt;code dir=&quot;auto&quot;&gt;direnv allow&lt;/code&gt; once per clone. &lt;code dir=&quot;auto&quot;&gt;direnv&lt;/code&gt; is optional and is &lt;strong&gt;not&lt;/strong&gt; a
project dependency; the sourced helper remains the baseline that needs nothing
installed. If you commit an &lt;code dir=&quot;auto&quot;&gt;.envrc&lt;/code&gt;, keep it path-agnostic (as above) so it
works in any clone.&lt;/p&gt;
&lt;h2 id=&quot;what-is-and-is-not-isolated&quot;&gt;What is (and is not) isolated&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Isolated per clone once activated:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Which &lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt; binary runs (clone &lt;code dir=&quot;auto&quot;&gt;.venv&lt;/code&gt;, editable → live &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;Runtime state under &lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_HOME&lt;/code&gt;: auth, config, tracker credentials
and stores, and gate-locks. (A &lt;code dir=&quot;auto&quot;&gt;queue.db&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;sync-daemon&lt;/code&gt; file under an old
&lt;code dir=&quot;auto&quot;&gt;~/.spec-kitty&lt;/code&gt; is inert residue from the retired sync transport.)&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Deliberately &lt;em&gt;not&lt;/em&gt; isolated:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;The machine-global &lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt; — it stays your default everywhere outside an
activated Shadow Clone. Setting up a Shadow Clone never rewrites it.&lt;/li&gt;
&lt;li&gt;Anything a command reaches over the network (a hosted Team Kitty or tracker backend is
shared infrastructure regardless of local state). Isolation here is about
&lt;em&gt;local&lt;/em&gt; runtime state, not remote services.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;troubleshooting&quot;&gt;Troubleshooting&lt;/h2&gt;













































&lt;table&gt;&lt;thead&gt;&lt;tr&gt;&lt;th&gt;Symptom&lt;/th&gt;&lt;th&gt;Cause&lt;/th&gt;&lt;th&gt;Fix&lt;/th&gt;&lt;/tr&gt;&lt;/thead&gt;&lt;tbody&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;spec-kitty&lt;/code&gt; still resolves to &lt;code dir=&quot;auto&quot;&gt;~/.local/bin/...&lt;/code&gt; after activating&lt;/td&gt;&lt;td&gt;The helper was executed, not sourced, so the exports never reached your shell.&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;source scripts/dev/activate-isolated-env.sh&lt;/code&gt; (note the leading &lt;code dir=&quot;auto&quot;&gt;source&lt;/code&gt;).&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;no .venv found at &amp;#x3C;root&gt;&lt;/code&gt;&lt;/td&gt;&lt;td&gt;The clone-local virtualenv was not created yet.&lt;/td&gt;&lt;td&gt;Run step 1 (create &lt;code dir=&quot;auto&quot;&gt;.venv&lt;/code&gt; + &lt;code dir=&quot;auto&quot;&gt;pip install -e .&lt;/code&gt;).&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;no executable spec-kitty CLI found at &amp;#x3C;root&gt;/.venv/bin/spec-kitty&lt;/code&gt;&lt;/td&gt;&lt;td&gt;The checkout’s &lt;code dir=&quot;auto&quot;&gt;.venv&lt;/code&gt; does not contain the Spec Kitty CLI.&lt;/td&gt;&lt;td&gt;Install this checkout with step 1, then activate again.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;A tracker or hosted call that needs authentication says &lt;code dir=&quot;auto&quot;&gt;Not authenticated&lt;/code&gt;&lt;/td&gt;&lt;td&gt;This Shadow Clone has its own empty auth store.&lt;/td&gt;&lt;td&gt;Authenticate again inside the activated Shadow Clone.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;Edits to the clone’s &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt; have no effect&lt;/td&gt;&lt;td&gt;The active CLI is the machine-global one, or the &lt;code dir=&quot;auto&quot;&gt;.venv&lt;/code&gt; install is not editable.&lt;/td&gt;&lt;td&gt;Activate the env; reinstall with &lt;code dir=&quot;auto&quot;&gt;pip install -e .&lt;/code&gt;.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;A gate lock, tracker binding, or login seems to come from another clone&lt;/td&gt;&lt;td&gt;&lt;code dir=&quot;auto&quot;&gt;SPEC_KITTY_HOME&lt;/code&gt; was unset, so the shared &lt;code dir=&quot;auto&quot;&gt;~/.spec-kitty&lt;/code&gt; was in play.&lt;/td&gt;&lt;td&gt;Activate the env; confirm &lt;code dir=&quot;auto&quot;&gt;echo &quot;$SPEC_KITTY_HOME&quot;&lt;/code&gt; points inside the clone.&lt;/td&gt;&lt;/tr&gt;&lt;tr&gt;&lt;td&gt;State appeared under &lt;code dir=&quot;auto&quot;&gt;~/.spec-kitty&lt;/code&gt; while working in a clone&lt;/td&gt;&lt;td&gt;A command ran before activation.&lt;/td&gt;&lt;td&gt;Deactivate/reactivate; run clone commands only inside an activated session.&lt;/td&gt;&lt;/tr&gt;&lt;/tbody&gt;&lt;/table&gt;
&lt;h2 id=&quot;related&quot;&gt;Related&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;a href=&quot;/development/how-to/local-overrides/&quot;&gt;Local overrides for cross-package development&lt;/a&gt; — editable
installs of sibling packages (&lt;code dir=&quot;auto&quot;&gt;-events&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;-tracker&lt;/code&gt;) and why committed
&lt;code dir=&quot;auto&quot;&gt;[tool.uv.sources]&lt;/code&gt; path overrides are prohibited.&lt;/li&gt;
&lt;li&gt;&lt;a href=&quot;/development/contributing/&quot;&gt;Contributing to Spec Kitty&lt;/a&gt; — developer setup and the test
workflow.&lt;/li&gt;
&lt;li&gt;Glossary: &lt;strong&gt;Shadow Clone (Isolated Dev Environment)&lt;/strong&gt; in
&lt;a href=&quot;/context/execution/#shadow-clone-isolated-dev-environment&quot;&gt;&lt;code dir=&quot;auto&quot;&gt;docs/context/execution.md&lt;/code&gt;&lt;/a&gt;.&lt;/li&gt;
&lt;/ul&gt;</content>
</entry>
