Skip to content

Use Claude Code, Codex, VSCode, Pi, and OpenCode (and 6 other harnesses) for free (1.3B+ free tokens) from your terminal, app, IDE, or phone, and now from the browser with native browser sessions (multi-harness + multi-model) like OpenClaw (voice supported + ToS friendly)

Python

Complete Claude onboarding from the VS Code integration (#1757)

Ali Khokhar3f57da1d98e1
diff --git a/e2e/conftest.py b/e2e/conftest.py
index 551bbec1..0cb03ebf 100644
--- a/e2e/conftest.py
+++ b/e2e/conftest.py
@@ -129,6 +129,7 @@ def admin_base_url(
"""Serve one fully isolated Admin application on an OS-assigned port."""
config_dir = tmp_path / ".fcc"
+ monkeypatch.setattr(vscode, "claude_state_path", lambda: tmp_path / ".claude.json")
monkeypatch.setattr(
vscode, "settings_path", lambda: tmp_path / "vscode" / "settings.json"
)
diff --git a/e2e/test_admin_integrations.py b/e2e/test_admin_integrations.py
index dcd5d71d..ff262a0e 100644
--- a/e2e/test_admin_integrations.py
+++ b/e2e/test_admin_integrations.py
@@ -31,6 +31,8 @@ def test_connect_disconnect_and_modal_dismissal(page, admin_base_url, tmp_path):
expect(page.locator("#claudeIntegrationStatus")).to_have_text("Connected")
expect(page.locator("#claudeIntegrationMessage")).to_contain_text("Reload VS Code")
assert json.loads(path.read_text())["claudeCode.disableLoginPrompt"] is True
+ state_path = tmp_path / ".claude.json"
+ assert json.loads(state_path.read_text())["hasCompletedOnboarding"] is True
page.reload()
expect(card_button).to_have_text("Disconnect")
card_button.click()
@@ -42,16 +44,28 @@ def test_connect_disconnect_and_modal_dismissal(page, admin_base_url, tmp_path):
action.click()
expect(card_button).to_have_text("Connect")
assert json.loads(path.read_text()) == {}
+ assert json.loads(state_path.read_text())["hasCompletedOnboarding"] is True
def test_manual_setup_and_revisit_read_the_file(page, admin_base_url, tmp_path):
path = tmp_path / "vscode" / "settings.json"
status = page.request.get(f"{admin_base_url}/admin/api/status").json()
vscode.configure(
- path, f"http://localhost:{status['port']}/", "e2e-proxy-token", True
+ path,
+ tmp_path / ".claude.json",
+ f"http://localhost:{status['port']}/",
+ "e2e-proxy-token",
+ True,
)
page.goto(f"{admin_base_url}/admin/integrations")
expect(page.locator("#openClaudeIntegration")).to_have_text("Disconnect")
+ (tmp_path / ".claude.json").unlink()
+ page.reload()
+ expect(page.locator("#openClaudeIntegration")).to_have_text("Connect")
+ page.locator("#openClaudeIntegration").click()
+ expect(page.locator("#claudeIntegrationDescription")).to_contain_text("onboarding")
+ page.locator("#confirmClaudeIntegration").click()
+ expect(page.locator("#openClaudeIntegration")).to_have_text("Disconnect")
page.get_by_role("button", name="Providers", exact=True).click()
path.write_text("{}")
page.get_by_role("button", name="Integrations", exact=True).click()
diff --git a/pyproject.toml b/pyproject.toml
index f99cc939..17624063 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "6.2.5"
+version = "6.2.6"
description = "Local proxy connecting coding agents to OpenAI-compatible AI providers"
readme = "README.md"
requires-python = ">=3.14.0"
diff --git a/src/free_claude_code/api/admin_static/admin.js b/src/free_claude_code/api/admin_static/admin.js
index b8de65a4..a34b32ba 100644
--- a/src/free_claude_code/api/admin_static/admin.js
+++ b/src/free_claude_code/api/admin_static/admin.js
@@ -1268,8 +1268,8 @@ function renderClaudeIntegration() {
: (connected ? "Connected" : "Not connected");
status.className = `status-pill ${connected ? "ok" : "neutral"}`;
byId("claudeIntegrationDescription").textContent = connected
- ? "Remove FCC's settings from VS Code. Other settings will stay."
- : "Will set FCC's URL and token in VS Code settings, enable model discovery, and skip the login prompt.";
+ ? "Remove FCC's VS Code settings. Claude onboarding stays completed."
+ : "Will set FCC's URL and token, enable model discovery, skip VS Code login, and complete Claude onboarding.";
}
async function refreshClaudeIntegration() {
diff --git a/src/free_claude_code/api/admin_static/index.html b/src/free_claude_code/api/admin_static/index.html
index 0561001f..4614da67 100644
--- a/src/free_claude_code/api/admin_static/index.html
+++ b/src/free_claude_code/api/admin_static/index.html
@@ -99,7 +99,7 @@
<h3 id="claudeIntegrationTitle">Claude Code in VS Code</h3>
<button id="closeClaudeIntegration" class="ghost-button" type="button" aria-label="Close" autofocus>×</button>
</div>
- <p id="claudeIntegrationDescription">Will set FCC's URL and token in VS Code settings, enable model discovery, and skip the login prompt.</p>
+ <p id="claudeIntegrationDescription">Will set FCC's URL and token, enable model discovery, skip VS Code login, and complete Claude onboarding.</p>
<button id="confirmClaudeIntegration" class="primary-button" type="button">Connect</button>
<p id="claudeIntegrationDialogMessage" class="message-area error" role="alert" hidden></p>
</dialog>
diff --git a/src/free_claude_code/cli/vscode.py b/src/free_claude_code/cli/vscode.py
index 03ad5ae0..a478e9cb 100644
--- a/src/free_claude_code/cli/vscode.py
+++ b/src/free_claude_code/cli/vscode.py
@@ -16,6 +16,7 @@ from free_claude_code.core.json_types import JsonObject
_ENV = "claudeCode.environmentVariables"
_LOGIN = "claudeCode.disableLoginPrompt"
+_ONBOARDING = "hasCompletedOnboarding"
def settings_path() -> Path:
@@ -32,16 +33,25 @@ def settings_path() -> Path:
return root / "Code/User/settings.json"
-def _read(path: Path, names: set[str]) -> tuple[JsonObject, list[JsonObject]]:
+def claude_state_path() -> Path:
+ return Path.home() / ".claude.json"
+
+
+def _read_object(path: Path) -> JsonObject:
try:
source = path.read_text(encoding="utf-8-sig")
except FileNotFoundError:
- return {}, []
+ return {}
document = json5.loads(source, allow_duplicate_keys=False)
if not isinstance(document, dict):
raise ValueError("Settings must be an object")
# Also reject non-finite JSON5 numbers before any operation or status result.
json.dumps(document, allow_nan=False)
+ return cast(JsonObject, document)
+
+
+def _read(path: Path, names: set[str]) -> tuple[JsonObject, list[JsonObject]]:
+ document = _read_object(path)
entries = document.get(_ENV, [])
if not isinstance(entries, list):
raise ValueError("Environment settings must be an array")
@@ -57,7 +67,7 @@ def _read(path: Path, names: set[str]) -> tuple[JsonObject, list[JsonObject]]:
if name in names and name in seen:
raise ValueError("Duplicate integration environment entry")
seen.add(name)
- return cast(JsonObject, document), cast(list[JsonObject], entries)
+ return document, cast(list[JsonObject], entries)
def _same_url(value: object, expected: str) -> bool:
@@ -122,6 +132,7 @@ def _write(path: Path, content: str) -> None:
def configure(
path: Path,
+ state_path: Path,
proxy_root_url: str,
auth_token: str,
connected: bool | None = None,
@@ -130,6 +141,10 @@ def configure(
path = path.resolve()
values = claude_proxy_values(proxy_root_url, auth_token)
document, entries = _read(path, set(values))
+ onboarding: JsonObject = {}
+ if connected is not False:
+ state_path = state_path.resolve()
+ onboarding = _read_object(state_path)
if connected is not None:
before = json.dumps(document, allow_nan=False)
if connected:
@@ -151,10 +166,17 @@ def configure(
document[_ENV] = retained
else:
document.pop(_ENV, None)
- if json.dumps(document, allow_nan=False) != before:
- _write(
- path,
- json.dumps(document, indent=2, allow_nan=False) + "\n",
- )
+ settings_changed = json.dumps(document, allow_nan=False) != before
+ settings_content = json.dumps(document, indent=2, allow_nan=False) + "\n"
+ if connected and onboarding.get(_ONBOARDING) is not True:
+ onboarding[_ONBOARDING] = True
+ _write(state_path, json.dumps(onboarding, indent=2, allow_nan=False) + "\n")
+ if settings_changed:
+ _write(path, settings_content)
document, entries = _read(path, set(values))
- return {"connected": _connected(document, entries, values)}
+ if connected:
+ onboarding = _read_object(state_path)
+ return {
+ "connected": _connected(document, entries, values)
+ and onboarding.get(_ONBOARDING) is True,
+ }
diff --git a/src/free_claude_code/runtime/application.py b/src/free_claude_code/runtime/application.py
index 44e9414b..88a781e3 100644
--- a/src/free_claude_code/runtime/application.py
+++ b/src/free_claude_code/runtime/application.py
@@ -373,6 +373,7 @@ class ApplicationRuntime:
to_thread.run_sync(
vscode.configure,
vscode.settings_path(),
+ vscode.claude_state_path(),
local_proxy_root_url(settings),
settings.proxy_auth_token,
connected,
@@ -381,11 +382,11 @@ class ApplicationRuntime:
)
except ValueError, UnicodeError:
raise InvalidRequestError(
- "Could not read VS Code settings. Check the JSON and environment entries."
+ "Could not read Claude integration settings. Check the JSON in VS Code settings.json and .claude.json."
) from None
except OSError:
raise ApplicationUnavailableError(
- "Could not access VS Code settings. Check file permissions and try again."
+ "Could not access VS Code settings.json or .claude.json. Check file permissions and try again."
) from None
async def admin_status(self) -> JsonObject:
diff --git a/tests/api/test_vscode_integration.py b/tests/api/test_vscode_integration.py
index 071c5aaa..3637538f 100644
--- a/tests/api/test_vscode_integration.py
+++ b/tests/api/test_vscode_integration.py
@@ -14,6 +14,7 @@ ROOT = "/admin/api/integrations/claude-vscode"
def integration(tmp_path, monkeypatch):
path = tmp_path / "settings.json"
monkeypatch.setattr(vscode, "settings_path", lambda: path)
+ monkeypatch.setattr(vscode, "claude_state_path", lambda: tmp_path / ".claude.json")
app = create_test_app(
Settings(host="0.0.0.0", port=4321, proxy_auth_token="integration-secret")
)
@@ -39,21 +40,32 @@ def test_routes_read_actual_file_connect_and_disconnect(integration):
assert environment["ANTHROPIC_AUTH_TOKEN"] == "integration-secret"
assert "integration-secret" not in response.text
assert client.get(ROOT).json() == {"connected": True}
+ state_path = path.parent / ".claude.json"
+ assert json.loads(state_path.read_text())["hasCompletedOnboarding"] is True
+ state_path.write_text('{"hasCompletedOnboarding":false}')
+ assert client.get(ROOT).json() == {"connected": False}
+ assert client.post(f"{ROOT}/connect").json() == {"connected": True}
path.write_text("{}")
assert client.get(ROOT).json() == {"connected": False}
assert client.post(f"{ROOT}/disconnect").json() == {"connected": False}
+ assert json.loads(state_path.read_text())["hasCompletedOnboarding"] is True
@pytest.mark.parametrize("action", ["", "/connect", "/disconnect"])
-def test_invalid_file_returns_safe_uncached_error(integration, action):
[email protected]("target", ["settings", "state"])
+def test_invalid_file_returns_safe_uncached_error(integration, action, target):
client, path, _ = integration
source = '{"integration-secret": malformed}'
+ if target == "state":
+ path = path.parent / ".claude.json"
path.write_text(source)
response = client.request("GET" if not action else "POST", ROOT + action)
- assert response.status_code == 400
+ expected_error = target == "settings" or action != "/disconnect"
+ assert response.status_code == (400 if expected_error else 200)
assert response.headers["cache-control"] == "no-store"
assert "integration-secret" not in response.text
- assert response.json()["detail"]
+ if expected_error:
+ assert response.json()["detail"]
assert path.read_text() == source
diff --git a/tests/cli/test_vscode.py b/tests/cli/test_vscode.py
index 2e5a2859..153926c7 100644
--- a/tests/cli/test_vscode.py
+++ b/tests/cli/test_vscode.py
@@ -12,7 +12,122 @@ LOGIN = "claudeCode.disableLoginPrompt"
def operate(path, connected=None):
- return vscode.configure(path, URL, TOKEN, connected)
+ return vscode.configure(path, path.parent / ".claude.json", URL, TOKEN, connected)
+
+
+def test_connect_completes_onboarding_and_disconnect_preserves_state(tmp_path):
+ path = tmp_path / "settings.json"
+ state_path = tmp_path / ".claude.json"
+ state_path.write_text('{"theme":"dark","hasCompletedOnboarding":false}')
+ assert operate(path, True) == {"connected": True}
+ assert json.loads(state_path.read_text()) == {
+ "theme": "dark",
+ "hasCompletedOnboarding": True,
+ }
+ saved = state_path.read_bytes()
+ modified = state_path.stat().st_mtime_ns
+ operate(path, True)
+ assert state_path.stat().st_mtime_ns == modified
+ assert operate(path, False) == {"connected": False}
+ assert state_path.read_bytes() == saved
+
+
[email protected]("flag", [None, False, 1, "true"])
+def test_connected_requires_completed_onboarding(tmp_path, flag):
+ path = tmp_path / "settings.json"
+ state_path = tmp_path / ".claude.json"
+ operate(path, True)
+ state_path.write_text(json.dumps({"hasCompletedOnboarding": flag}))
+ assert operate(path) == {"connected": False}
+ operate(path, True)
+ assert json.loads(state_path.read_text())["hasCompletedOnboarding"] is True
+ assert operate(path) == {"connected": True}
+
+
+def test_missing_onboarding_state_is_read_only_until_connect(tmp_path):
+ path = tmp_path / "settings.json"
+ state_path = tmp_path / ".claude.json"
+ operate(path, True)
+ state_path.unlink()
+ assert operate(path) == {"connected": False}
+ assert not state_path.exists()
+ assert operate(path, False) == {"connected": False}
+ assert not state_path.exists()
+ operate(path, True)
+ assert json.loads(state_path.read_text()) == {"hasCompletedOnboarding": True}
+
+
[email protected]("source", ["{invalid", "[]", '{"a":1,"a":2}', '{"a":NaN}'])
+def test_invalid_state_blocks_connect_but_not_disconnect(tmp_path, source):
+ path = tmp_path / "settings.json"
+ state_path = tmp_path / ".claude.json"
+ operate(path, True)
+ settings_before = path.read_bytes()
+ state_path.write_text(source)
+ for action in (None, True):
+ with pytest.raises(ValueError):
+ operate(path, action)
+ assert path.read_bytes() == settings_before
+ assert state_path.read_text() == source
+ assert operate(path, False) == {"connected": False}
+ assert json.loads(path.read_text()) == {}
+ assert state_path.read_text() == source
+
+
+def test_invalid_vscode_settings_do_not_update_onboarding(tmp_path):
+ path = tmp_path / "settings.json"
+ state_path = tmp_path / ".claude.json"
+ path.write_text('{"claudeCode.environmentVariables":{}}')
+ state_path.write_text('{"hasCompletedOnboarding":false}')
+ with pytest.raises(ValueError):
+ operate(path, True)
+ assert state_path.read_text() == '{"hasCompletedOnboarding":false}'
+
+
[email protected]("failed_file", ["state", "settings"])
+def test_save_failure_preserves_completed_steps_and_retry_completes(
+ tmp_path, monkeypatch, failed_file
+):
+ path = tmp_path / "settings.json"
+ state_path = tmp_path / ".claude.json"
+ path.write_text('{"keep":true}')
+ original_replace = Path.replace
+
+ def fail_replace(self, target):
+ if target == (state_path if failed_file == "state" else path):
+ raise PermissionError("test failure")
+ return original_replace(self, target)
+
+ with monkeypatch.context() as patch:
+ patch.setattr(Path, "replace", fail_replace)
+ with pytest.raises(OSError):
+ operate(path, True)
+ if failed_file == "state":
+ assert not state_path.exists()
+ else:
+ assert json.loads(state_path.read_text())["hasCompletedOnboarding"] is True
+ assert path.read_text() == '{"keep":true}'
+ assert operate(path) == {"connected": False}
+ assert operate(path, True) == {"connected": True}
+
+
+def test_onboarding_symlink_and_escaped_unicode_are_preserved(tmp_path):
+ path = tmp_path / "settings.json"
+ state_path = tmp_path / ".claude.json"
+ target = tmp_path / "state.json"
+ target.write_text(json.dumps({"keep": "\U0001f600"}))
+ try:
+ state_path.symlink_to(Path("state.json"))
+ except OSError as exc:
+ if getattr(exc, "winerror", None) == 1314:
+ pytest.skip("Windows symlink creation requires Developer Mode or privilege")
+ raise
+ assert operate(path, True) == {"connected": True}
+ assert state_path.is_symlink()
+ assert json.loads(target.read_text()) == {
+ "keep": "\U0001f600",
+ "hasCompletedOnboarding": True,
+ }
def test_connect_merges_jsonc_and_disconnect_preserves_unrelated_values(tmp_path):
@@ -115,6 +230,7 @@ def test_settings_symlink_is_preserved(tmp_path, connected, target_exists):
@pytest.mark.parametrize("url", ["http://localhost:8000/", URL, "http://[::1]:8000"])
def test_manual_setup_only_requires_connection_fields(tmp_path, url):
path = tmp_path / "settings.json"
+ (tmp_path / ".claude.json").write_text('{"hasCompletedOnboarding":true}')
path.write_text(
json.dumps(
{
@@ -184,6 +300,8 @@ def test_failed_replace_preserves_original_and_removes_tempfile(
tmp_path, monkeypatch, readonly
):
path = tmp_path / "settings.json"
+ state_path = tmp_path / ".claude.json"
+ state_path.write_text('{"hasCompletedOnboarding":true}')
path.write_text('{"keep": true}')
if readonly:
path.chmod(0o444)
@@ -196,7 +314,7 @@ def test_failed_replace_preserves_original_and_removes_tempfile(
with pytest.raises(OSError):
operate(path, True)
assert path.read_text() == '{"keep": true}'
- assert list(tmp_path.iterdir()) == [path]
+ assert set(tmp_path.iterdir()) == {path, state_path}
finally:
for item in tmp_path.iterdir():
item.chmod(0o600)
diff --git a/uv.lock b/uv.lock
index bd03487a..7fd9c863 100644
--- a/uv.lock
+++ b/uv.lock
@@ -598,7 +598,7 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "6.2.5"
+version = "6.2.6"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },