diff --git a/AGENTS.md b/AGENTS.md
index 54a75059e7..e9299c8c04 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -11,7 +11,7 @@ Kilo CLI is an open source AI coding agent that generates code from natural lang
 
 - **Dev**: `bun run dev` (runs from root) or `bun run --cwd packages/opencode --conditions=browser src/index.ts`
 - **Dev with params**: `bun dev -- help`
-- **Extension**: `bun run extension` (build + launch VS Code with the extension in dev mode). Pass `--no-build` to skip the build.
+- **Extension**: `bun run extension` (build + launch VS Code with the extension in dev mode). Pass `--no-build` to skip the build. When asked to run an isolated VS Code/Kilo environment, use the CLI scripts instead of interactive launch configs: `bun run extension:isolated` reuses `.kilo-dev/`, and `bun run extension:isolated:clean` clears `.kilo-dev/` first. Pass an optional workspace path after `--`, for example `bun run extension:isolated -- ../sample-project`.
 - **Typecheck**: `bun turbo typecheck` (uses `tsgo`, not `tsc`). Includes the JetBrains plugin and requires Java 21; do not run `java -version` as a routine preflight. Only check Java when a Gradle/Java command fails with a Java-version or missing-Java error. If missing, install via SDKMAN: `sdk install java 21-tem && sdk use java 21-tem`. If SDKMAN is not installed, see https://sdkman.io/install.
 - **Test**: `bun test` from `packages/opencode/` (NOT from root -- root blocks tests)
 - **Single test**: `bun test ./test/tool/tool-define.test.ts` from `packages/opencode/`
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d78e6dd9e4..d1132f9a28 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -114,10 +114,19 @@ For manual docs validation, run the docs site locally, preview the affected page
 Build and launch the extension in an isolated VS Code instance:
 
 ```bash
-bun run extension        # Build + launch in dev mode
+bun run extension                  # Build + launch in dev mode
+bun run extension:isolated         # Build + launch with persistent isolated IDE + Kilo state
+bun run extension:isolated:clean   # Clear isolated state, then build + launch
 ```
 
-This auto-detects VS Code on macOS, Linux, and Windows. Override with `--app-path PATH` or `VSCODE_EXEC_PATH`. Use `--insiders` to prefer Insiders, `--workspace PATH` to open a specific folder, or `--clean` to reset cached state.
+This auto-detects VS Code on macOS, Linux, and Windows. Override with `--app-path PATH` or `VSCODE_EXEC_PATH`. Use `--insiders` to prefer Insiders, pass a directory argument to open a specific folder, or use `--workspace PATH` for the same behavior.
+
+The isolated modes are for testing the extension without touching your primary VS Code profile or real Kilo config. `extension:isolated` reuses `.kilo-dev/` on each run, so installed extensions, VS Code settings, Kilo auth, sessions, config, state, and cache persist across launches. `extension:isolated:clean` deletes `.kilo-dev/` before launching, which simulates a fresh install while still keeping all state inside this repo checkout.
+
+```bash
+bun run extension:isolated -- ../sample-project
+bun run extension:isolated:clean -- ../sample-project
+```
 
 ### Developing the JetBrains Plugin
 
diff --git a/packages/kilo-docs/pages/contributing/development-environment.md b/packages/kilo-docs/pages/contributing/development-environment.md
index d8c9922bf0..a6471d5e42 100644
--- a/packages/kilo-docs/pages/contributing/development-environment.md
+++ b/packages/kilo-docs/pages/contributing/development-environment.md
@@ -109,6 +109,17 @@ bun run extension
 
 This will build and launch the extension in an isolated VS Code instance.
 
+For a fully isolated development environment, use one of the isolated scripts:
+
+```bash
+bun run extension:isolated
+bun run extension:isolated:clean
+```
+
+`extension:isolated` launches a separate VS Code process with user data and extensions under `.kilo-dev/vscode/`, and points Kilo at isolated XDG storage under `.kilo-dev/{data,config,state,cache}`. Re-running it keeps the same isolated environment, so installed extensions, VS Code settings, Kilo auth, sessions, config, state, and cache persist.
+
+`extension:isolated:clean` deletes `.kilo-dev/` before launch. Use it to simulate a fresh VS Code + Kilo install without affecting your main VS Code profile or real Kilo config.
+
 The command auto-detects VS Code on macOS, Linux, and Windows. Use these options when the default launch target is not the one you need:
 
 | Option | Use |
@@ -118,12 +129,15 @@ The command auto-detects VS Code on macOS, Linux, and Windows. Use these options
 | `VSCODE_EXEC_PATH` | Set the VS Code executable through the current shell environment |
 | `--insiders` | Prefer VS Code Insiders |
 | `--workspace <path>` | Open a specific workspace folder |
+| `<path>` | Open a specific workspace folder when passed as the final positional argument |
 | `--clean` | Reset cached extension state before launch |
 
 For example, to test the extension against a sample workspace:
 
 ```bash
 bun run extension --workspace ../sample-project
+bun run extension:isolated -- ../sample-project
+bun run extension:isolated:clean -- ../sample-project
 ```
 
 To set the executable through an environment variable, use the syntax for your shell:
diff --git a/packages/kilo-vscode/AGENTS.md b/packages/kilo-vscode/AGENTS.md
index 842cb9ba4c..15fac1d6be 100644
--- a/packages/kilo-vscode/AGENTS.md
+++ b/packages/kilo-vscode/AGENTS.md
@@ -56,15 +56,17 @@ Every client spawns or connects to a `kilo serve` process and communicates via H
 ## Commands
 
 ```bash
-bun run extension        # Build + launch VS Code with the extension in dev mode
-bun run compile          # Type-check + lint + build
-bun run watch            # Watch mode (esbuild + tsc)
-bun run test             # Run tests (requires pretest compilation)
-bun run lint             # ESLint on src/
-bun run format           # Run formatter (do this before committing to avoid styling-only changes in commits)
+bun run extension                  # Build + launch VS Code with the extension in dev mode
+bun run extension:isolated         # Build + launch with persistent isolated IDE + Kilo state
+bun run extension:isolated:clean   # Clear isolated state, then build + launch
+bun run compile                    # Type-check + lint + build
+bun run watch                      # Watch mode (esbuild + tsc)
+bun run test                       # Run tests (requires pretest compilation)
+bun run lint                       # ESLint on src/
+bun run format                     # Run formatter (do this before committing to avoid styling-only changes in commits)
 ```
 
-The `extension` commands also work from the repo root. Pass `--insiders` to prefer VS Code Insiders, `--workspace PATH` to open a different folder, `--clean` to wipe cached state, or `--wait` to block until VS Code closes. VS Code is auto-detected on macOS, Linux, and Windows; override with `--app-path` or `VSCODE_EXEC_PATH`.
+The `extension` commands also work from the repo root. When a user asks to run an isolated VS Code/Kilo environment, prefer the CLI scripts: `bun run extension:isolated` reuses `.kilo-dev/`, while `bun run extension:isolated:clean` clears `.kilo-dev/` before launching. Pass an optional workspace path after `--`, for example `bun run extension:isolated -- ../sample-project`. Pass `--insiders` to prefer VS Code Insiders, `--workspace PATH` to open a different folder, `--clean` to wipe cached state, or `--wait` to block until VS Code closes. VS Code is auto-detected on macOS, Linux, and Windows; override with `--app-path` or `VSCODE_EXEC_PATH`.
 
 Single test: `bun run test -- --grep "test name"`