firekeep-client 1.2.0__tar.gz → 1.3.0__tar.gz

{firekeep_client-1.2.0/firekeep_client.egg-info → firekeep_client-1.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: firekeep-client
-Version: 1.2.0
+Version: 1.3.0
 Summary: Client for Firekeep, the self-hosted operating layer for connected AI agents.
 License-Expression: LicenseRef-Firekeep-BUSL-1.1
 Project-URL: Homepage, https://firekeep.ai

{firekeep_client-1.2.0 → firekeep_client-1.3.0}/firekeep_client/__init__.py

@@ -9,4 +9,4 @@ versions without a verdict (`_check_versions`) and judges staleness against the
 release manifest instead (`_check_client_version`).
 """
 
-__version__ = "1.2.0"
+__version__ = "1.3.0"

{firekeep_client-1.2.0 → firekeep_client-1.3.0}/firekeep_client/adapters/__init__.py

@@ -19,6 +19,9 @@ def get_adapter(name: str) -> Adapter:
     if name == "opencode":
         from firekeep_client.adapters.opencode import OpencodeAdapter
         return OpencodeAdapter()
+    if name == "claude-desktop":
+        from firekeep_client.adapters.claude_desktop import ClaudeDesktopAdapter
+        return ClaudeDesktopAdapter()
     if name == "generic":
         # The target file (if any) lives in the kit config, not in the render
         # loop's signature — resolver, never cli: adapters -> cli would be a cycle.
@@ -26,4 +29,4 @@ def get_adapter(name: str) -> Adapter:
         from firekeep_client.resolver import generic_agents_md
         return GenericAdapter(agents_md=generic_agents_md())
     raise ValueError(
-        f"unknown adapter: {name!r} (expected claude|codex|kiro|opencode|generic)")
+        f"unknown adapter: {name!r} (expected claude|codex|kiro|opencode|claude-desktop|generic)")

{firekeep_client-1.2.0 → firekeep_client-1.3.0}/firekeep_client/adapters/base.py

@@ -374,6 +374,11 @@ the session.
 - Operational or repeated-failure task → also `skill_recall(task)`. The
   session-start briefing only ever matched your ORIGINAL goal, never what the user
   asked on turn 7.
+- About to BUILD something substantial (a feature, a module, a big function) →
+  check prior art first: `memory_recall` for what the team already built, and
+  `get_similar_symbols`/`search_symbols` for code that already does it. Ten
+  seconds of checking beats a day of parallel reinvention; `ctx_start_session`'s
+  `prior_art` block is the same check done for you at the moment you declare a goal.
 - Your own earlier plan or decisions missing from context (after compaction) →
   `ctx_get_shadow` before asking the user to repeat themselves. Pass
   `since=<shadow_cursor>` ONLY if the earlier shadow is still visible in your

firekeep_client-1.3.0/firekeep_client/adapters/claude_desktop.py

@@ -0,0 +1,159 @@
+"""Claude Desktop adapter: the `firekeep` entry in `claude_desktop_config.json`.
+
+Claude Desktop is the first NON-CODING host the kit ships a bespoke adapter for
+— the consumer chat app, not an agentic IDE. It runs local stdio MCP servers
+from one JSON config file, so this adapter delivers exactly the generic tier
+with the friction removed: the same gateway entry the generic adapter PRINTS
+for pasting is WRITTEN here, because unlike a client we know nothing about,
+Claude Desktop's config path is documented and stable per platform.
+
+What it deliberately does NOT do:
+- No hooks. Claude Desktop exposes no hook surface — no session lifecycle, no
+  prompt interception, no pre-edit gate. Its column in contract/matrix.py is
+  the generic floor, and claiming more would be the lie the matrix exists to
+  prevent.
+- No instruction file. Claude Desktop reads no rules file the kit could safely
+  own; the cognitive protocol arrives through the MCP `initialize` handshake
+  (GATEWAY_INSTRUCTIONS), the same second channel every runtime gets.
+
+The config is JSON, which has no comments and no partial-edit syntax, so the
+file is parsed and re-serialized rather than marker-blocked. Only the
+`mcpServers.firekeep` key is ever set or removed; every other key — other
+servers, app settings — survives byte-for-byte at the VALUE level (formatting
+is normalized to indent=2, which Claude Desktop itself also does on save).
+A file that does not parse is REFUSED loudly and left exactly as it is:
+clobbering a consumer app's config because we could not read it would be the
+worst possible outcome of an install, and the render loop has no per-runtime
+catch — so the refusal must not raise.
+"""
+from __future__ import annotations
+
+import json
+import os
+import sys
+from pathlib import Path
+
+from firekeep_client.adapters.base import Adapter, shim_servers, write_text_if_changed
+
+_CONFIG_NAME = "claude_desktop_config.json"
+
+
+def _config_dir() -> Path:
+    """Claude Desktop's config directory for the current platform.
+
+    Resolved on every call, never cached — tests steer it via APPDATA /
+    XDG_CONFIG_HOME / HOME, and the opencode adapter set the precedent that
+    an env-following path must follow the env at call time."""
+    if sys.platform == "win32":
+        appdata = os.environ.get("APPDATA")
+        base = Path(appdata) if appdata else Path.home() / "AppData" / "Roaming"
+        return base / "Claude"
+    if sys.platform == "darwin":
+        return Path.home() / "Library" / "Application Support" / "Claude"
+    xdg = os.environ.get("XDG_CONFIG_HOME")
+    return (Path(xdg) if xdg else Path.home() / ".config") / "Claude"
+
+
+def config_path() -> Path:
+    return _config_dir() / _CONFIG_NAME
+
+
+def app_present() -> bool:
+    """Whether Claude Desktop appears installed on this machine.
+
+    The config directory is the evidence: the app creates it on first run.
+    This is the auto-render gate — `firekeep install` (no --runtime) mounts
+    the gateway here only when the app exists, because writing another
+    vendor's consumer-app config onto machines that never ran the app would
+    scatter orphan files for zero benefit. Explicit
+    `--runtime claude-desktop` bypasses the gate (creating the directory),
+    for a user installing Firekeep ahead of the app."""
+    return _config_dir().is_dir()
+
+
+def _expected_entry(venv_bin: Path) -> dict:
+    command, args = shim_servers(venv_bin, ClaudeDesktopAdapter.name)["firekeep"]
+    return {"command": command, "args": list(args)}
+
+
+def _load(path: Path) -> dict | None:
+    """Parse the config, or None when it cannot be safely rewritten.
+
+    Missing file -> {} (we will create it). Unreadable or unparseable or
+    non-object -> None, and the caller warns and leaves the file alone."""
+    try:
+        raw = path.read_text(encoding="utf-8")
+    except FileNotFoundError:
+        return {}
+    except (OSError, UnicodeError):
+        return None
+    if not raw.strip():
+        return {}
+    try:
+        parsed = json.loads(raw)
+    except json.JSONDecodeError:
+        return None
+    return parsed if isinstance(parsed, dict) else None
+
+
+def mcp_entry_is_current(text: str, venv_bin: Path) -> bool:
+    """Whether `text` carries the exact gateway entry this adapter would render."""
+    try:
+        parsed = json.loads(text)
+    except json.JSONDecodeError:
+        return False
+    if not isinstance(parsed, dict):
+        return False
+    servers = parsed.get("mcpServers")
+    if not isinstance(servers, dict):
+        return False
+    return servers.get("firekeep") == _expected_entry(venv_bin)
+
+
+class ClaudeDesktopAdapter(Adapter):
+    name = "claude-desktop"
+
+    def render(self, *, venv_bin: Path) -> None:
+        path = config_path()
+        data = _load(path)
+        if data is None:
+            print(
+                f"firekeep: WARNING — {path} exists but is not valid JSON; "
+                "left untouched. Fix the file, then run "
+                "`firekeep install --runtime claude-desktop`.",
+                file=sys.stderr,
+            )
+            return
+        servers = data.setdefault("mcpServers", {})
+        if not isinstance(servers, dict):
+            print(
+                f"firekeep: WARNING — {path} has a non-object mcpServers; "
+                "left untouched.",
+                file=sys.stderr,
+            )
+            return
+        servers["firekeep"] = _expected_entry(venv_bin)
+        if write_text_if_changed(path, json.dumps(data, indent=2) + "\n"):
+            # Only on a real change: this render re-runs on every
+            # `firekeep update`, and a restart nag for a byte-identical
+            # config would train users to ignore it.
+            print("firekeep: Claude Desktop configured — restart the app to load Firekeep.")
+
+    def unrender(self) -> None:
+        path = config_path()
+        if not path.exists():
+            return
+        data = _load(path)
+        if data is None:
+            print(
+                f"firekeep: WARNING — could not parse {path}; remove the "
+                "'firekeep' entry from mcpServers yourself.",
+                file=sys.stderr,
+            )
+            return
+        servers = data.get("mcpServers")
+        if not isinstance(servers, dict) or "firekeep" not in servers:
+            return
+        del servers["firekeep"]
+        # The file itself stays — it belongs to Claude Desktop, not to us.
+        write_text_if_changed(path, json.dumps(data, indent=2) + "\n")

{firekeep_client-1.2.0 → firekeep_client-1.3.0}/firekeep_client/cli.py

@@ -291,14 +291,30 @@ def _generic_is_configured() -> bool:
     return resolver.generic_agents_md() is not None
 
 
-def _selected_runtimes(runtime: str, *, include_generic: bool = False) -> list[str]:
+def _claude_desktop_present() -> bool:
+    """Whether Claude Desktop appears installed (its config dir exists).
+
+    Gates the "all" fan-out for install AND uninstall: install must not write
+    another vendor's consumer-app config onto machines that never ran the app,
+    and uninstall has nothing to clean where nothing was written. Lazy import —
+    cli must stay importable without every adapter module."""
+    from firekeep_client.adapters.claude_desktop import app_present
+    return app_present()
+
+
+def _selected_runtimes(runtime: str, *, include_generic: bool = False,
+                       include_claude_desktop: bool = False) -> list[str]:
     """PURE: a function of its arguments only, never of the config on disk.
 
     `generic` joins the "all" fan-out only when the caller says so, so an
     unconfigured user gets exactly the four — the invariant test_cli_install and
-    test_cli_uninstall pin by count."""
+    test_cli_uninstall pin by count. `claude-desktop` likewise: its flag is
+    computed at the call site from claude_desktop.app_present(), so a machine
+    that never ran Claude Desktop gets no config written for it."""
     if runtime == "all":
-        return ["claude", "codex", "kiro", "opencode"] + (["generic"] if include_generic else [])
+        return (["claude", "codex", "kiro", "opencode"]
+                + (["claude-desktop"] if include_claude_desktop else [])
+                + (["generic"] if include_generic else []))
     return [runtime]
 
 
@@ -523,7 +539,9 @@ def cmd_install(args) -> int:
         # embedded paths stay literally identical across flips) and keeps
         # runtime configs from pinning a venv that GC will remove.
         venv_bin = _venv_bin(_venv_root(home))
-        for name in _selected_runtimes(args.runtime, include_generic=_generic_is_configured()):
+        for name in _selected_runtimes(args.runtime,
+                                       include_generic=_generic_is_configured(),
+                                       include_claude_desktop=_claude_desktop_present()):
             step = f"render {name} adapter"
             get_adapter(name).render(venv_bin=venv_bin)
 
@@ -747,7 +765,8 @@ def cmd_uninstall(args) -> int:
     # config we could not parse leaves the block stranded with no way to find it.
     generic_target = resolver.generic_agents_md()
     generic_orphan = _generic_orphan_warning(home) if generic_target is None else None
-    runtimes = _selected_runtimes("all", include_generic=generic_target is not None)
+    runtimes = _selected_runtimes("all", include_generic=generic_target is not None,
+                                  include_claude_desktop=_claude_desktop_present())
 
     # Say exactly what will be removed BEFORE touching anything.
     print("firekeep uninstall will remove:")
@@ -1361,9 +1380,36 @@ def _check_codex_adapter(venv: Path) -> list[tuple[str, str, str]]:
     return [("codex-mcp", "ok", str(config))]
 
 
+def _check_claude_desktop_adapter(venv: Path) -> list[tuple[str, str, str]]:
+    """claude-desktop-mcp: silent unless the app's config exists AND mentions us.
+
+    Mirrors _check_codex_adapter's philosophy — doctor must not warn a user
+    about a runtime they never installed. A present-but-unmanaged config is a
+    user who chose not to mount Firekeep there; also silence. No instructions
+    row exists for this runtime: Claude Desktop reads no rules file, so the
+    protocol's only channel is the gateway handshake."""
+    from firekeep_client.adapters.claude_desktop import config_path, mcp_entry_is_current
+    config = config_path()
+    if not config.exists():
+        return []
+    try:
+        text = config.read_text(encoding="utf-8")
+    except OSError as exc:
+        return [("claude-desktop-mcp", "fail", f"cannot read {config}: {exc}")]
+    if '"firekeep"' not in text:
+        return []
+    repair = "run `firekeep install --runtime claude-desktop`"
+    if not mcp_entry_is_current(text, _venv_bin(venv)):
+        return [("claude-desktop-mcp", "fail",
+                 f"stale Firekeep gateway entry in {config}; {repair}")]
+    return [("claude-desktop-mcp", "ok", str(config))]
+
+
 # The shipped runtimes, in adapter order (`_selected_runtimes("all")`), plus
 # generic — which contributes a row ONLY when the user configured it, so an
-# unconfigured user's doctor output is unchanged.
+# unconfigured user's doctor output is unchanged. claude-desktop is absent on
+# purpose: it renders no instruction file (rendered_instructions_path returns
+# None for it), so there is no block to hash-check.
 _INSTRUCTION_RUNTIMES = ("claude", "codex", "kiro", "opencode", "generic")
 
 
@@ -1639,6 +1685,7 @@ def run_doctor(cfg=None) -> list[tuple[str, str, str]]:
     results.append(_check_venv_scripts(_venv_root()))
     results.extend(_check_dexes())
     results.extend(_check_codex_adapter(_venv_root()))
+    results.extend(_check_claude_desktop_adapter(_venv_root()))
     results.extend(_check_instructions())
     results.append(_check_config_perms(_config_path()))
     ca = _check_ca_expiry(cfg)
@@ -2686,7 +2733,7 @@ def _build_parser() -> argparse.ArgumentParser:
     # bootstrap's FIREKEEP_RUNTIME) remains available for a targeted re-render.
     inst.add_argument(
         "--runtime",
-        choices=["claude", "codex", "kiro", "opencode", "generic", "all"],
+        choices=["claude", "codex", "kiro", "opencode", "claude-desktop", "generic", "all"],
         default=None,
     )
     # `generic` is any MCP client the kit ships no bespoke adapter for: it prints

{firekeep_client-1.2.0 → firekeep_client-1.3.0}/firekeep_client/contract/matrix.py

@@ -45,7 +45,13 @@ from firekeep_client.adapters.claude import CLAUDE_HOOKS
 # and the instruction protocol, and nothing that rides a hook — a client we know
 # nothing about exposes no hook surface to wire. It is listed last because it is
 # what a runtime degrades TO, not a peer of the four.
-RUNTIMES = ("claude", "kiro", "codex", "opencode", "generic")
+#
+# `claude-desktop` (the consumer chat app, not Claude Code) sits AT that floor
+# on purpose: it has a bespoke adapter only because its config path is known —
+# every capability cell is the generic value, because the app exposes no hook
+# surface. If a cell here ever claims more than generic's, either Claude
+# Desktop grew hooks or the cell is lying.
+RUNTIMES = ("claude", "kiro", "codex", "opencode", "claude-desktop", "generic")
 
 
 def _precompact_claude(hooks: tuple[tuple[str, str, str | None, int], ...]) -> str:
@@ -77,6 +83,7 @@ def _precompact_claude(hooks: tuple[tuple[str, str, str | None, int], ...]) -> s
 MATRIX: dict[str, dict[str, str]] = {
     "briefing": {"claude": "hook", "kiro": "agentSpawn hook", "codex": "manual/memory_recall",
                  "opencode": "plugin (first event, console log only)",
+                 "claude-desktop": "none (MCP only)",
                  "generic": "none (MCP only)"},
     # Proactive recall (firekeep_client.promptrecall): fires only where the runtime
     # hands the prompt TEXT to a hook, because there is nothing to embed otherwise.
@@ -90,14 +97,17 @@ MATRIX: dict[str, dict[str, str]] = {
     # briefing remains the only push.
     "proactive_recall": {"claude": "per-prompt push", "kiro": "per-prompt push",
                          "codex": "none (no hooks)", "opencode": "none (no prompt text)",
+                         "claude-desktop": "none (no hooks)",
                          "generic": "none (no hooks)"},
     "presence": {"claude": "hook", "kiro": "hook", "codex": "sidecar (manual today)",
-                 "opencode": "plugin hooks", "generic": "sidecar (manual today)"},
+                 "opencode": "plugin hooks", "claude-desktop": "sidecar (manual today)",
+                 "generic": "sidecar (manual today)"},
     # kiro (validated 2.12.1): the fs_write pre-edit hook FIRES (the agent-gateway before-call
     # runs + records), but kiro does not enforce its own exit-2 block — so it is advisory, not
     # a hard gate. See firekeep_client/adapters/kiro.py + docs/KIRO-VALIDATION.md.
     "pre_edit_block": {"claude": "guaranteed", "kiro": "advisory (fires, non-blocking on 2.12.1)", "codex": "none",
                        "opencode": "guaranteed (plugin throw, validated 1.14.22)",
+                       "claude-desktop": "none",
                        "generic": "none"},
     # Only Claude exposes a compaction event; the other three runtimes have no
     # such lifecycle hook to wire, so this degrades honestly rather than silently.
@@ -105,9 +115,11 @@ MATRIX: dict[str, dict[str, str]] = {
     # _precompact_claude) so it cannot claim a hook the kit does not render; the
     # other three are hand-authored because there is nothing to derive them from.
     "precompact": {"claude": _precompact_claude(CLAUDE_HOOKS), "kiro": "none",
-                   "codex": "none", "opencode": "none", "generic": "none"},
+                   "codex": "none", "opencode": "none", "claude-desktop": "none",
+                   "generic": "none"},
     "reconcile": {"claude": "hooks", "kiro": "kiro pre/post hooks", "codex": "self-reported",
-                  "opencode": "plugin pre/post hooks", "generic": "self-reported"},
+                  "opencode": "plugin pre/post hooks", "claude-desktop": "self-reported",
+                  "generic": "self-reported"},
     # Personal / bypass mode: the is_bypassed() gate (marker + FIREKEEP_BYPASS) works on
     # every runtime; only the /personal slash command is claude-specific. kiro/codex
     # toggle via the `firekeep personal` CLI (or `! firekeep personal`), or FIREKEEP_BYPASS at launch.
@@ -116,6 +128,7 @@ MATRIX: dict[str, dict[str, str]] = {
         "kiro": "firekeep personal CLI + FIREKEEP_BYPASS (no /personal command)",
         "codex": "firekeep personal CLI + FIREKEEP_BYPASS (sidecar honors the gate)",
         "opencode": "firekeep personal CLI + FIREKEEP_BYPASS (no /personal command)",
+        "claude-desktop": "firekeep personal CLI + FIREKEEP_BYPASS (no /personal command)",
         "generic": "firekeep personal CLI + FIREKEEP_BYPASS (no /personal command)",
     },
 }

{firekeep_client-1.2.0 → firekeep_client-1.3.0/firekeep_client.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: firekeep-client
-Version: 1.2.0
+Version: 1.3.0
 Summary: Client for Firekeep, the self-hosted operating layer for connected AI agents.
 License-Expression: LicenseRef-Firekeep-BUSL-1.1
 Project-URL: Homepage, https://firekeep.ai

{firekeep_client-1.2.0 → firekeep_client-1.3.0}/firekeep_client.egg-info/SOURCES.txt

@@ -40,6 +40,7 @@ firekeep_client.egg-info/top_level.txt
 firekeep_client/adapters/__init__.py
 firekeep_client/adapters/base.py
 firekeep_client/adapters/claude.py
+firekeep_client/adapters/claude_desktop.py
 firekeep_client/adapters/codex.py
 firekeep_client/adapters/generic.py
 firekeep_client/adapters/kiro.py

{firekeep_client-1.2.0 → firekeep_client-1.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "firekeep-client"
-version = "1.2.0"
+version = "1.3.0"
 description = "Client for Firekeep, the self-hosted operating layer for connected AI agents."
 readme = "README.md"
 requires-python = ">=3.10"

{firekeep_client-1.2.0 → firekeep_client-1.3.0}/tests/test_package.py

@@ -7,7 +7,7 @@ from pathlib import Path
 def test_package_imports_and_exposes_frozen_version():
     import firekeep_client
 
-    assert firekeep_client.__version__ == "1.2.0"
+    assert firekeep_client.__version__ == "1.3.0"
 
 
 def test_frozen_module_layout_is_present():