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

Fix cross-drive messaging startup with native Claude plan storage (#1085)

Ali Khokhar12621477c916
diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md
index fff88baa..acf3690f 100644
--- a/ARCHITECTURE.md
+++ b/ARCHITECTURE.md
@@ -300,7 +300,7 @@ source detection for startup warnings also belongs to `src/free_claude_code/conf
- config directory: `~/.fcc`;
- managed env file: `~/.fcc/.env`;
- generated Codex model catalog: `~/.fcc/codex-model-catalog.json`;
-- agent workspace: `~/.fcc/agent_workspace`;
+- messaging state directory: `~/.fcc/agent_workspace`;
- server log: `~/.fcc/logs/server.log`.
Model routing configuration is tiered:
@@ -808,11 +808,14 @@ the proxy instead of stopping at its login gate.
[cli/managed/](src/free_claude_code/cli/managed/) owns managed Claude Code subprocesses used by
Discord and Telegram messaging. Managed task invocations extend the same proxy
environment only with non-interactive terminal settings, optional `--resume`,
-optional `--fork-session`, `--model opus`, and `--output-format stream-json`. Messaging
-pins this Claude tier alias so phone sessions route through `MODEL_OPUS` or the
-`MODEL` fallback instead of inheriting a user's interactive `/model` picker
-state. The managed session parser extracts persistent Claude session IDs and
-yields Claude stream-json events to the messaging event parser. Managed Claude
+optional `--fork-session`, `--model opus`, and `--output-format stream-json`.
+Messaging pins this Claude tier alias so phone sessions route through
+`MODEL_OPUS` or the `MODEL` fallback instead of inheriting a user's interactive
+`/model` picker state. Managed execution does not override Claude's
+`plansDirectory`; plan files use Claude's native user-level location so the
+project workspace may reside on any filesystem volume. The managed session
+parser extracts persistent Claude session IDs and yields Claude stream-json
+events to the messaging event parser. Managed Claude
also owns subprocess stderr diagnostic classification so known benign Claude
Code notices do not become messaging task errors, while unknown stderr remains
fatal. Before subprocess stop, the manager marks the session closing so new
@@ -1066,7 +1069,7 @@ reported and skipped because assigning it to an inferred chat would violate the
same ownership boundary.
[messaging/session/](src/free_claude_code/messaging/session/) persists typed conversation snapshots
-and message IDs to a JSON file under the managed agent workspace.
+and message IDs to a JSON file under the managed messaging state directory.
`SessionStore` reads existing `sessions.json` files but exposes typed snapshot
APIs to runtime code and deep-copies snapshot ingress and egress so no caller
shares mutable persisted state. Debounced atomic writes live in
diff --git a/pyproject.toml b/pyproject.toml
index 13dba229..c0d54b72 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
[project]
name = "free-claude-code"
-version = "3.5.16"
+version = "3.5.17"
description = "Local proxy connecting Claude Code and Codex to OpenAI-compatible AI providers"
readme = "README.md"
requires-python = ">=3.14.0"
diff --git a/src/free_claude_code/cli/managed/claude.py b/src/free_claude_code/cli/managed/claude.py
index bf68965e..bdd6934e 100644
--- a/src/free_claude_code/cli/managed/claude.py
+++ b/src/free_claude_code/cli/managed/claude.py
@@ -41,7 +41,6 @@ class ManagedClaudeConfig:
workspace_path: str
proxy_root_url: str
allowed_dirs: list[str] = field(default_factory=list)
- plans_directory: str | None = None
claude_bin: str = CLAUDE_BINARY_NAME
auth_token: str = ""
@@ -68,7 +67,6 @@ def build_managed_claude_invocation(
session_id=request.session_id,
fork_session=request.fork_session,
allowed_dirs=config.allowed_dirs,
- plans_directory=config.plans_directory,
)
resume_session_id = (
request.session_id
@@ -121,7 +119,6 @@ def build_managed_claude_command(
session_id: str | None,
fork_session: bool,
allowed_dirs: list[str],
- plans_directory: str | None,
) -> list[str]:
"""Return the Claude Code stream-json command for a managed task."""
@@ -159,9 +156,6 @@ def build_managed_claude_command(
for directory in allowed_dirs:
cmd.extend(["--add-dir", directory])
- if plans_directory is not None:
- cmd.extend(["--settings", json.dumps({"plansDirectory": plans_directory})])
-
return cmd
diff --git a/src/free_claude_code/cli/managed/manager.py b/src/free_claude_code/cli/managed/manager.py
index 894ff07f..30bd603b 100644
--- a/src/free_claude_code/cli/managed/manager.py
+++ b/src/free_claude_code/cli/managed/manager.py
@@ -23,7 +23,6 @@ class ManagedClaudeSessionManager:
workspace_path: str,
proxy_root_url: str,
allowed_dirs: list[str] | None = None,
- plans_directory: str | None = None,
claude_bin: str = CLAUDE_BINARY_NAME,
auth_token: str = "",
*,
@@ -37,12 +36,10 @@ class ManagedClaudeSessionManager:
workspace_path: Working directory for CLI processes
proxy_root_url: Root URL for the local proxy
allowed_dirs: Directories the CLI is allowed to access
- plans_directory: Directory for Claude Code CLI plan files (passed via --settings)
"""
self.workspace = workspace_path
self.proxy_root_url = proxy_root_url
self.allowed_dirs = allowed_dirs or []
- self.plans_directory = plans_directory
self.claude_bin = claude_bin
self.auth_token = auth_token
self._log_raw_cli_diagnostics = log_raw_cli_diagnostics
@@ -112,7 +109,6 @@ class ManagedClaudeSessionManager:
workspace_path=self.workspace,
proxy_root_url=self.proxy_root_url,
allowed_dirs=self.allowed_dirs,
- plans_directory=self.plans_directory,
claude_bin=self.claude_bin,
auth_token=self.auth_token,
log_raw_cli_diagnostics=self._log_raw_cli_diagnostics,
diff --git a/src/free_claude_code/cli/managed/session.py b/src/free_claude_code/cli/managed/session.py
index 0f1bcff2..af0016e5 100644
--- a/src/free_claude_code/cli/managed/session.py
+++ b/src/free_claude_code/cli/managed/session.py
@@ -34,7 +34,6 @@ class ManagedClaudeSession:
workspace_path: str,
proxy_root_url: str,
allowed_dirs: list[str] | None = None,
- plans_directory: str | None = None,
claude_bin: str = "claude",
auth_token: str = "",
*,
@@ -44,14 +43,12 @@ class ManagedClaudeSession:
workspace_path=os.path.normpath(os.path.abspath(workspace_path)),
proxy_root_url=proxy_root_url,
allowed_dirs=[os.path.normpath(d) for d in (allowed_dirs or [])],
- plans_directory=plans_directory,
claude_bin=claude_bin,
auth_token=auth_token,
)
self.workspace = self.config.workspace_path
self.proxy_root_url = self.config.proxy_root_url
self.allowed_dirs = self.config.allowed_dirs
- self.plans_directory = self.config.plans_directory
self.claude_bin = self.config.claude_bin
self.auth_token = self.config.auth_token
self._log_raw_cli_diagnostics = log_raw_cli_diagnostics
diff --git a/src/free_claude_code/config/paths.py b/src/free_claude_code/config/paths.py
index 02bb216c..980a4c02 100644
--- a/src/free_claude_code/config/paths.py
+++ b/src/free_claude_code/config/paths.py
@@ -6,7 +6,7 @@ FCC_CONFIG_DIRNAME = ".fcc"
FCC_ENV_FILENAME = ".env"
LEGACY_REPO_DIRNAME = "free-claude-code"
LEGACY_XDG_CONFIG_DIRNAME = ".config"
-CLAUDE_WORKSPACE_DIRNAME = "agent_workspace"
+MESSAGING_STATE_DIRNAME = "agent_workspace"
FCC_LOGS_DIRNAME = "logs"
SERVER_LOG_FILENAME = "server.log"
CODEX_MODEL_CATALOG_FILENAME = "codex-model-catalog.json"
@@ -34,10 +34,10 @@ def legacy_env_paths() -> tuple[Path, ...]:
)
-def default_claude_workspace_path() -> Path:
- """Return the default Claude workspace path."""
+def messaging_state_dir_path() -> Path:
+ """Return the managed messaging state directory."""
- return config_dir_path() / CLAUDE_WORKSPACE_DIRNAME
+ return config_dir_path() / MESSAGING_STATE_DIRNAME
def server_log_path() -> Path:
diff --git a/src/free_claude_code/runtime/application.py b/src/free_claude_code/runtime/application.py
index 26022a65..94a644fe 100644
--- a/src/free_claude_code/runtime/application.py
+++ b/src/free_claude_code/runtime/application.py
@@ -27,7 +27,7 @@ from free_claude_code.config.env_files import (
process_env_key_is_effective,
)
from free_claude_code.config.model_refs import parse_provider_type
-from free_claude_code.config.paths import default_claude_workspace_path
+from free_claude_code.config.paths import messaging_state_dir_path
from free_claude_code.config.server_urls import local_admin_url, local_proxy_root_url
from free_claude_code.config.settings import Settings, get_settings
from free_claude_code.messaging.platforms import factory as messaging_platform_factory
@@ -362,16 +362,14 @@ class ApplicationRuntime:
else os.getcwd()
)
os.makedirs(workspace, exist_ok=True)
- data_path = os.path.abspath(default_claude_workspace_path())
+ data_path = os.path.abspath(messaging_state_dir_path())
os.makedirs(data_path, exist_ok=True)
allowed_dirs = [workspace] if settings.allowed_dir else []
- plans_dir_abs = os.path.abspath(os.path.join(data_path, "plans"))
self._cli_manager = cli_managed.ManagedClaudeSessionManager(
workspace_path=workspace,
proxy_root_url=local_proxy_root_url(settings),
allowed_dirs=allowed_dirs,
- plans_directory=os.path.relpath(plans_dir_abs, workspace),
auth_token=settings.anthropic_auth_token,
log_raw_cli_diagnostics=settings.log_raw_cli_diagnostics,
log_messaging_error_details=settings.log_messaging_error_details,
diff --git a/tests/cli/test_cli.py b/tests/cli/test_cli.py
index bda296f1..8bcdb224 100644
--- a/tests/cli/test_cli.py
+++ b/tests/cli/test_cli.py
@@ -1,7 +1,6 @@
"""Tests for cli/ module."""
import asyncio
-import json
import os
from typing import cast
from unittest.mock import AsyncMock, MagicMock, patch
@@ -675,36 +674,6 @@ class TestManagedClaudeSession:
assert os.path.normpath("/dir1") in cmd
assert os.path.normpath("/dir2") in cmd
- @pytest.mark.asyncio
- async def test_start_task_plans_directory(self):
- """Test start_task includes --settings plansDirectory when plans_directory set."""
- from free_claude_code.cli.managed.session import ManagedClaudeSession
-
- session = ManagedClaudeSession(
- "/tmp",
- "http://localhost:8082",
- plans_directory="./agent_workspace/plans",
- )
-
- mock_process = AsyncMock()
- mock_process.stdout.read.side_effect = [b""]
- mock_process.stderr.read.return_value = b""
- mock_process.wait.return_value = 0
-
- with patch(
- "asyncio.create_subprocess_exec", new_callable=AsyncMock
- ) as mock_exec:
- mock_exec.return_value = mock_process
- async for _ in session.start_task("test"):
- pass
-
- cmd = mock_exec.call_args[0]
- assert "--settings" in cmd
- settings_idx = cmd.index("--settings")
- assert settings_idx + 1 < len(cmd)
- settings = json.loads(cmd[settings_idx + 1])
- assert settings["plansDirectory"] == "./agent_workspace/plans"
-
@pytest.mark.asyncio
async def test_start_task_json_error(self):
"""Test handling of non-JSON output from free_claude_code.cli."""
diff --git a/tests/cli/test_cli_ownership.py b/tests/cli/test_cli_ownership.py
index 61cdad44..03a099f6 100644
--- a/tests/cli/test_cli_ownership.py
+++ b/tests/cli/test_cli_ownership.py
@@ -8,12 +8,10 @@ def test_cli_session_owns_typed_runner_config(tmp_path: Path) -> None:
workspace_path=str(tmp_path),
proxy_root_url="http://127.0.0.1:8082",
allowed_dirs=[str(tmp_path)],
- plans_directory=".plans",
claude_bin="claude-test",
)
assert session.config.workspace_path == str(tmp_path)
assert session.config.proxy_root_url == "http://127.0.0.1:8082"
assert session.config.allowed_dirs == [str(tmp_path)]
- assert session.config.plans_directory == ".plans"
assert session.config.claude_bin == "claude-test"
diff --git a/tests/cli/test_managed_claude.py b/tests/cli/test_managed_claude.py
index 8239b5ef..409ce227 100644
--- a/tests/cli/test_managed_claude.py
+++ b/tests/cli/test_managed_claude.py
@@ -24,20 +24,17 @@ def _config(**overrides: object) -> ManagedClaudeConfig:
for directory in raw_allowed_dirs:
assert isinstance(directory, str)
allowed_dirs.append(directory)
- plans_directory = overrides.get("plans_directory")
claude_bin = overrides.get("claude_bin", "claude")
auth_token = overrides.get("auth_token", "proxy-token")
assert isinstance(workspace_path, str)
assert isinstance(proxy_root_url, str)
- assert plans_directory is None or isinstance(plans_directory, str)
assert isinstance(claude_bin, str)
assert isinstance(auth_token, str)
return ManagedClaudeConfig(
workspace_path=workspace_path,
proxy_root_url=proxy_root_url,
allowed_dirs=allowed_dirs,
- plans_directory=plans_directory,
claude_bin=claude_bin,
auth_token=auth_token,
)
@@ -45,10 +42,7 @@ def _config(**overrides: object) -> ManagedClaudeConfig:
def test_managed_claude_builds_new_task_command_and_env() -> None:
invocation = build_managed_claude_invocation(
- config=_config(
- allowed_dirs=[os.path.normpath("/tmp/extra")],
- plans_directory=".plans",
- ),
+ config=_config(allowed_dirs=[os.path.normpath("/tmp/extra")]),
request=ManagedClaudeTaskRequest(prompt="hello"),
base_env={"PATH": "keep", "ANTHROPIC_API_KEY": "official"},
)
@@ -64,7 +58,7 @@ def test_managed_claude_builds_new_task_command_and_env() -> None:
assert "stream-json" in invocation.argv
assert "--add-dir" in invocation.argv
assert os.path.normpath("/tmp/extra") in invocation.argv
- assert "--settings" in invocation.argv
+ assert "--settings" not in invocation.argv
assert invocation.env["PATH"] == "keep"
assert invocation.env["ANTHROPIC_BASE_URL"] == "http://localhost:8082"
assert invocation.env["ANTHROPIC_AUTH_TOKEN"] == "proxy-token"
@@ -113,6 +107,16 @@ def test_managed_claude_builds_resume_and_fork_commands() -> None:
assert "--fork-session" in fork.argv
+def test_managed_claude_uses_native_plan_storage() -> None:
+ invocation = build_managed_claude_invocation(
+ config=_config(),
+ request=ManagedClaudeTaskRequest(prompt="hello"),
+ base_env={},
+ )
+
+ assert "--settings" not in invocation.argv
+
+
def test_managed_claude_env_uses_sentinel_when_proxy_auth_blank() -> None:
env = build_managed_claude_env(
proxy_root_url="http://localhost:8082",
diff --git a/tests/config/test_config.py b/tests/config/test_config.py
index baeae07f..b848b5e1 100644
--- a/tests/config/test_config.py
+++ b/tests/config/test_config.py
@@ -19,7 +19,7 @@ from free_claude_code.config.model_refs import (
parse_provider_type,
)
from free_claude_code.config.nim import NimSettings
-from free_claude_code.config.paths import default_claude_workspace_path
+from free_claude_code.config.paths import messaging_state_dir_path
class TestSettings:
@@ -67,7 +67,7 @@ class TestSettings:
settings = Settings()
- assert default_claude_workspace_path() == tmp_path / ".fcc" / "agent_workspace"
+ assert messaging_state_dir_path() == tmp_path / ".fcc" / "agent_workspace"
assert not hasattr(settings, "claude_workspace")
def test_server_log_path_uses_fcc_home(self, monkeypatch, tmp_path):
@@ -112,7 +112,7 @@ class TestSettings:
settings = Settings()
- assert default_claude_workspace_path() == tmp_path / ".fcc" / "agent_workspace"
+ assert messaging_state_dir_path() == tmp_path / ".fcc" / "agent_workspace"
assert not hasattr(settings, "claude_workspace")
def test_explicit_claude_workspace_is_ignored(self, monkeypatch, tmp_path):
@@ -127,7 +127,7 @@ class TestSettings:
settings = Settings()
- assert default_claude_workspace_path() == tmp_path / ".fcc" / "agent_workspace"
+ assert messaging_state_dir_path() == tmp_path / ".fcc" / "agent_workspace"
assert not hasattr(settings, "claude_workspace")
def test_explicit_claude_cli_bin_is_ignored(self, monkeypatch):
@@ -160,7 +160,7 @@ class TestSettings:
)
)
- assert default_claude_workspace_path() == tmp_path / ".fcc" / "agent_workspace"
+ assert messaging_state_dir_path() == tmp_path / ".fcc" / "agent_workspace"
assert not hasattr(settings, "claude_workspace")
assert not hasattr(settings, "claude_cli_bin")
diff --git a/tests/runtime/test_application_runtime.py b/tests/runtime/test_application_runtime.py
index 26034b23..0113cf08 100644
--- a/tests/runtime/test_application_runtime.py
+++ b/tests/runtime/test_application_runtime.py
@@ -932,5 +932,6 @@ async def test_composition_publishes_startup_notice_after_runtime_and_repair() -
"http://127.0.0.1:8082"
)
assert "api_url" not in manager_constructor.call_args.kwargs
+ assert "plans_directory" not in manager_constructor.call_args.kwargs
assert await runtime.close() is True
diff --git a/uv.lock b/uv.lock
index 1f05b610..ead66fbf 100644
--- a/uv.lock
+++ b/uv.lock
@@ -561,7 +561,7 @@ wheels = [
[[package]]
name = "free-claude-code"
-version = "3.5.16"
+version = "3.5.17"
source = { editable = "." }
dependencies = [
{ name = "aiohttp" },