subcortex 0.3.0__py3-none-any.whl

subcortex/installers/goose.py

@@ -0,0 +1,186 @@
+"""Goose: register ``subcortex mcp`` as a stdio extension in ``config.yaml``.
+
+Goose (>= v1.34) hooks are observation-only for everything but PreToolUse/Stop
+(which can block, so we never register them), PostToolUse payloads carry no
+output, and there is no compaction event — so Goose's seam is an MCP
+extension. The stdlib has no YAML writer, so the entry is inserted line-wise
+under the top-level ``extensions:`` mapping between marker comments, and
+removed the same way; when PyYAML is importable the result is also parsed and
+checked. Anything we can't edit unambiguously is refused.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+from pathlib import Path
+from typing import List, Optional, Tuple
+
+from .base import InstallError, Installer, Target
+
+BEGIN = "# >>> subcortex (managed; remove with: subcortex uninstall goose)"
+END = "# <<< subcortex"
+_TOP_KEY = re.compile(r"^extensions:\s*(?P<rest>.*?)\s*(#.*)?$")
+
+
+def goose_config() -> Path:
+    root = os.environ.get("GOOSE_PATH_ROOT", "").strip()
+    if root and os.path.isabs(root):
+        return Path(root) / "config" / "config.yaml"
+    xdg = os.environ.get("XDG_CONFIG_HOME", "").strip()
+    return (Path(xdg) if xdg else Path.home() / ".config") / "goose" / "config.yaml"
+
+
+def _entry_lines(argv: List[str], indent: str) -> List[str]:
+    q = json.dumps  # JSON strings are valid YAML flow scalars
+    inner = indent * 2
+    return [
+        f"{indent}{BEGIN}",
+        f"{indent}subcortex:",
+        f"{inner}enabled: true",
+        f"{inner}type: stdio",
+        f"{inner}name: subcortex",
+        f"{inner}description: {q('subcortex: local millisecond decisions (prompt triage, output judging)')}",
+        f"{inner}cmd: {q(argv[0])}",
+        f"{inner}args: [{', '.join(q(a) for a in argv[1:])}]",
+        f"{inner}envs: {{}}",
+        f"{inner}timeout: 300",
+        f"{inner}bundled: false",
+        f"{indent}{END}",
+    ]
+
+
+def _unmarked_entry(text: str) -> Optional[Tuple[int, int]]:
+    """Line range of an ``extensions.subcortex`` entry without our markers.
+
+    Goose rewrites config.yaml with serde_yaml (plugin discovery, ``goose
+    configure``, toggling an extension), which drops comments, so an entry we
+    wrote can outlive its markers. A second ``subcortex:`` key next to it would
+    make the file invalid for Goose, which then starts from an empty config.
+    """
+    lines = text.splitlines()
+    in_extensions = False
+    for i, line in enumerate(lines):
+        if line.strip() and not line[0].isspace() and not line.startswith("#"):
+            in_extensions = line.split(":", 1)[0].strip() == "extensions"
+            continue
+        match = re.match(r"^([ \t]+)subcortex:\s*(#.*)?$", line)
+        if in_extensions and match:
+            indent = len(match.group(1))
+            end = i + 1
+            while end < len(lines) and (not lines[end].strip()
+                                        or len(lines[end]) - len(lines[end].lstrip()) > indent):
+                end += 1
+            # Ours if it runs subcortex: in `cmd`, an inline `args: [...]`, or a
+            # block list item (serde_yaml writes `args:` then `- subcortex`).
+            if any(re.match(r"^\s+(?:cmd|args):.*\bsubcortex\b", l)
+                   or re.match(r"""^\s+-\s+['"]?subcortex['"]?\s*$""", l) for l in lines[i + 1:end]):
+                return i, end
+    return None
+
+
+def strip_entry(text: str) -> str:
+    unmarked = _unmarked_entry(text) if "# >>> subcortex" not in text else None
+    if unmarked:
+        lines = text.splitlines(keepends=True)
+        text = "".join(lines[:unmarked[0]] + lines[unmarked[1]:])
+    lines_in = text.splitlines()
+    begins = [i for i, l in enumerate(lines_in) if l.strip().startswith("# >>> subcortex")]
+    if begins and not any(l.strip().startswith(END) for l in lines_in[begins[0] + 1:]):
+        # Removing "to the end of the file" could delete the user's own settings.
+        raise InstallError(f"the subcortex block in the goose config has no end marker ({END}); "
+                           "remove it by hand, then retry")
+    out, inside = [], False
+    for line in text.splitlines(keepends=True):
+        stripped = line.strip()
+        if stripped.startswith("# >>> subcortex"):
+            inside = True
+            continue
+        if inside and stripped.startswith(END):
+            inside = False
+            continue
+        if not inside:
+            out.append(line)
+    lines = out
+    # An `extensions:` key we left without children becomes an empty mapping.
+    for i, line in enumerate(lines):
+        if line.rstrip("\n") == "extensions:":
+            nxt = next((l for l in lines[i + 1:] if l.strip() and not l.lstrip().startswith("#")), "")
+            if not nxt.startswith((" ", "\t")):
+                lines[i] = "extensions: {}\n"
+    return "".join(lines)
+
+
+def insert_entry(text: str, argv: List[str]) -> str:
+    text = strip_entry(text)
+    lines = text.splitlines(keepends=True)
+    if lines and not lines[-1].endswith("\n"):
+        lines[-1] += "\n"
+    for i, line in enumerate(lines):
+        match = _TOP_KEY.match(line.rstrip("\n"))
+        if not match:
+            continue
+        rest = match.group("rest")
+        if rest in ("{}", "null", "~", ""):
+            indent = "  "
+            for later in lines[i + 1:]:
+                if later.strip() and not later.lstrip().startswith("#"):
+                    lead = later[:len(later) - len(later.lstrip())]
+                    if lead and rest == "":
+                        indent = lead
+                    break
+            new = ["extensions:\n"] + [l + "\n" for l in _entry_lines(argv, indent)]
+            return "".join(lines[:i] + new + lines[i + 1:])
+        raise InstallError(f"{goose_config()}: `extensions:` uses inline syntax ({rest!r}); "
+                           "add the entry shown by --dry-run by hand")
+    # No `extensions:` key yet: the key itself goes inside our markers so
+    # uninstall restores the original bytes.
+    entry = _entry_lines(argv, "  ")
+    block = [BEGIN + "\n", "extensions:\n"] + [l + "\n" for l in entry[1:-1]] + [END + "\n"]
+    return "".join(lines + block)
+
+
+def _validate(text: str, expect_ours: bool) -> str:
+    try:
+        import yaml  # type: ignore
+    except ImportError:
+        return text
+    try:
+        data = yaml.safe_load(text) or {}
+    except yaml.YAMLError as exc:
+        raise InstallError(f"{goose_config()}: result would not be valid YAML ({exc})") from exc
+    has = isinstance(data, dict) and isinstance(data.get("extensions"), dict) \
+        and "subcortex" in data["extensions"]
+    if has != expect_ours:
+        raise InstallError(f"{goose_config()}: could not edit `extensions` unambiguously; "
+                           "add the entry shown by --dry-run by hand")
+    return text
+
+
+class GooseInstaller(Installer):
+    name = "goose"
+    display_name = "Goose"
+    seam = "mcp"
+    binaries = ("goose",)
+    docs = "https://block.github.io/goose/docs/getting-started/using-extensions"
+    min_version = "1.34.0"
+    post_install = "applies to new goose sessions (tools appear as subcortex__*)"
+
+    def targets(self) -> List[Target]:
+        argv = self.mcp_command()
+
+        def merge(text: str) -> str:
+            if text.strip():
+                _validate(strip_entry(text), expect_ours=False)
+            return _validate(insert_entry(text, argv), expect_ours=True)
+
+        def unmerge(text: str) -> str:
+            if not installed(text):
+                return text
+            return _validate(strip_entry(text), expect_ours=False)
+
+        def installed(text: str) -> bool:
+            return "# >>> subcortex" in text or _unmarked_entry(text) is not None
+
+        return [Target(goose_config(), merge, unmerge, installed)]

subcortex/installers/kimi_code.py

@@ -0,0 +1,71 @@
+"""Kimi Code CLI: ``[[hooks]]`` in ``$KIMI_CODE_HOME/config.toml`` (+ optional ``mcp.json``).
+
+Kimi validates hook entries with a strict schema — one unknown key or bad
+event name silently drops the *whole* hooks section, the user's own hooks
+included — so each entry carries exactly ``event``/``command``/``timeout``.
+Hooks load at startup: restart kimi after installing.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Dict, List, Optional
+
+from ..adapters.kimi_code import kimi_home
+from .base import Installer, Target, mcp_json_target, toml_block_target, toml_str
+
+EVENTS = {"UserPromptSubmit": 5, "PreCompact": 10, "PostCompact": 5}
+
+SESSION = "session_4f0c2a8e-9b1d-4c3e-8a77-2f5d0e6b1c90"
+
+
+class KimiCodeInstaller(Installer):
+    name = "kimi-code"
+    display_name = "Kimi Code CLI"
+    seam = "hooks"
+    binaries = ("kimi",)
+    docs = "https://www.kimi.com/code/docs/en/kimi-code-cli/customization/hooks.html"
+    min_version = "0.33.0"
+    supports_mcp = True
+    post_install = "restart kimi so it loads the new hooks"
+
+    def version_problem(self, version_output: str) -> Optional[str]:
+        # "kimi-cli <v>" is the dist-info of the legacy Python CLI (installed_version).
+        if version_output.strip().lower().replace("_", "-").startswith(("kimi, version", "kimi-cli ")):
+            return ("this `kimi` is the legacy Python kimi-cli (~/.kimi), not Kimi Code CLI; "
+                    "install @moonshot-ai/kimi-code")
+        return super().version_problem(version_output)
+
+    def _body(self) -> str:
+        tables = []
+        for event, timeout in EVENTS.items():
+            tables.append("\n".join([
+                "[[hooks]]",
+                f"event = {toml_str(event)}",
+                f"command = {toml_str(self.command(event))}",
+                f"timeout = {timeout}",
+            ]))
+        return "\n\n".join(tables) + "\n"
+
+    def targets(self) -> List[Target]:
+        home = kimi_home()
+        targets = [toml_block_target(home / "config.toml", self._body(), self.name)]
+        if self.mcp:
+            targets.append(mcp_json_target(home / "mcp.json", self.mcp_command(),
+                                           extra={"startupTimeoutMs": 10000}))
+        return targets
+
+    def hook_events(self) -> List[str]:
+        return list(EVENTS)
+
+    def sample_payload(self, event: str) -> Dict[str, Any]:
+        common = {"hook_event_name": event, "session_id": SESSION, "cwd": "/tmp",
+                  "client_type": "kimi_code_cli"}
+        if event == "UserPromptSubmit":
+            return {**common, "prompt": [{"type": "text", "text": "what does ls -la do?"}],
+                    "is_steer": False}
+        if event == "PreCompact":
+            return {**common, "trigger": "auto", "token_count": 241337}
+        return {**common, "trigger": "auto", "estimated_token_count": 18422}
+
+    def expects_output(self, event: str) -> bool:
+        return event == "UserPromptSubmit"

subcortex/installers/mcp_only.py

@@ -0,0 +1,111 @@
+"""MCP-only integrations: TUIs whose extension seam is an MCP server entry.
+
+None of these offers a hook that can inject context or replace tool output,
+so subcortex registers ``subcortex mcp`` (on-demand decision tools). Every
+target file is plain JSON; files with comments are refused, never rewritten.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from typing import Any, Dict, List
+
+from .base import Installer, Target, json_target, mcp_json_target
+
+
+class _McpInstaller(Installer):
+    seam = "mcp"
+    extra: Dict[str, Any] = {}
+
+    def mcp_path(self) -> Path:
+        raise NotImplementedError
+
+    def targets(self) -> List[Target]:
+        return [mcp_json_target(self.mcp_path(), self.mcp_command(), extra=dict(self.extra))]
+
+
+class WarpInstaller(_McpInstaller):
+    name = "warp"
+    display_name = "Warp"
+    binaries = ("warp", "warp-terminal")
+    docs = "https://docs.warp.dev/agents/capabilities/mcp"
+    post_install = "global MCP servers start automatically in Warp's agent"
+
+    def mcp_path(self) -> Path:
+        return Path.home() / ".warp" / ".mcp.json"
+
+
+class AuggieInstaller(_McpInstaller):
+    name = "auggie"
+    display_name = "Augment Auggie CLI"
+    binaries = ("auggie",)
+    docs = "https://docs.augmentcode.com/cli/integrations"
+
+    def mcp_path(self) -> Path:
+        return Path.home() / ".augment" / "settings.json"
+
+
+def cline_mcp_path() -> Path:
+    explicit = os.environ.get("CLINE_MCP_SETTINGS_PATH", "").strip()
+    if explicit:
+        return Path(explicit)
+    data = os.environ.get("CLINE_DATA_DIR", "").strip()
+    if data:
+        return Path(data) / "settings" / "cline_mcp_settings.json"
+    return cline_dir() / "data" / "settings" / "cline_mcp_settings.json"
+
+
+def cline_dir() -> Path:
+    base = os.environ.get("CLINE_DIR", "").strip()
+    return Path(base) if base else Path.home() / ".cline"
+
+
+class KiroInstaller(_McpInstaller):
+    name = "kiro"
+    display_name = "Kiro CLI"
+    binaries = ("kiro-cli",)
+    docs = "https://kiro.dev/docs/mcp/configuration"
+    extra = {"disabled": False}
+    post_install = "custom Kiro agents only see it with \"includeMcpJson\": true"
+
+    def mcp_path(self) -> Path:
+        home = os.environ.get("KIRO_HOME", "").strip()
+        return (Path(home) if home else Path.home() / ".kiro") / "settings" / "mcp.json"
+
+
+class ZedInstaller(Installer):
+    """Zed's settings.json is JSONC; its sibling global_settings.json (merged
+    under user settings, never written by Zed) holds our entry instead."""
+
+    name = "zed"
+    display_name = "Zed (agent panel)"
+    seam = "mcp"
+    binaries = ("zed",)
+    docs = "https://zed.dev/docs/ai/mcp"
+    post_install = "Zed asks for confirmation the first time a subcortex tool runs"
+
+    def config_dir(self) -> Path:
+        if sys.platform.startswith("linux"):
+            xdg = os.environ.get("XDG_CONFIG_HOME", "").strip()
+            return (Path(xdg) if xdg else Path.home() / ".config") / "zed"
+        return Path.home() / ".config" / "zed"
+
+    def targets(self) -> List[Target]:
+        argv = self.mcp_command()
+
+        def add(data: Dict[str, Any]) -> None:
+            servers = data.get("context_servers")
+            if not isinstance(servers, dict):
+                servers = data["context_servers"] = {}
+            servers["subcortex"] = {"command": argv[0], "args": argv[1:], "env": {}}
+
+        def remove(data: Dict[str, Any]) -> None:
+            servers = data.get("context_servers")
+            if isinstance(servers, dict) and servers.pop("subcortex", None) is not None and not servers:
+                del data["context_servers"]
+
+        return [json_target(self.config_dir() / "global_settings.json", add, remove,
+                            lambda d: isinstance(d.get("context_servers"), dict)
+                            and "subcortex" in d["context_servers"])]

subcortex/installers/more_hooks.py

@@ -0,0 +1,184 @@
+"""Installers for Grok Build, Docker Agent, Letta Code and Mistral Vibe."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+from typing import Any, Dict, List, Optional
+
+from ..adapters.docker_agent import config_dir as docker_config_dir
+from ..adapters.grok import grok_home
+from .base import Installer, Target, owned_file_target, toml_block_target, toml_str
+from .claude_family import SESSION, ClaudeStyleInstaller
+
+
+class GrokBuildInstaller(Installer):
+    """``$GROK_HOME/hooks/subcortex.json`` — a Claude-format hooks file we own."""
+
+    name = "grok-build"
+    display_name = "Grok Build"
+    seam = "hooks"
+    binaries = ("grok",)
+    docs = "https://x.ai/cli"
+    supports_mcp = True
+    post_install = "start a new grok session (or /hooks → r) to load the hooks"
+    # UserPromptSubmit output is discarded by Grok; the hook only records the
+    # request, which the output judge needs as evidence.
+    EVENTS = {"UserPromptSubmit": (None, 5), "PostToolUse": ("Bash|bash", 10),
+              "PreCompact": (None, 10), "PostCompact": (None, 5)}
+
+    def _content(self) -> str:
+        hooks: Dict[str, Any] = {}
+        for event, (matcher, timeout) in self.EVENTS.items():
+            group: Dict[str, Any] = {"matcher": matcher} if matcher else {}
+            group["hooks"] = [{"type": "command", "command": self.command(event), "timeout": timeout}]
+            hooks[event] = [group]
+        return json.dumps({"_subcortex": {"managed": True, "schema": 1}, "hooks": hooks}, indent=2) + "\n"
+
+    def targets(self) -> List[Target]:
+        targets = [owned_file_target(grok_home() / "hooks" / "subcortex.json", self._content())]
+        if self.mcp:
+            argv = self.mcp_command()
+            body = "\n".join(["[mcp_servers.subcortex]", f"command = {toml_str(argv[0])}",
+                              f"args = [{', '.join(toml_str(a) for a in argv[1:])}]", "enabled = true"]) + "\n"
+            targets.append(toml_block_target(grok_home() / "config.toml", body, self.name))
+        return targets
+
+    def hook_events(self) -> List[str]:
+        return list(self.EVENTS)
+
+    def sample_payload(self, event: str) -> Dict[str, Any]:
+        common = {"hookEventName": event.lower(), "sessionId": SESSION, "cwd": "/tmp", "workspaceRoot": "/tmp",
+                  "transcriptPath": "{transcript}", "permissionMode": "default", "hook_event_name": event}
+        if event == "UserPromptSubmit":
+            return {**common, "hookEventName": "user_prompt_submit", "promptId": "p1",
+                    "prompt": "why does make build take so long?"}
+        if event == "PostToolUse":
+            return {**common, "toolName": "run_terminal_command", "toolUseId": "call_1",
+                    "toolInput": {"command": "make build"}, "toolInputTruncated": False,
+                    "toolResultTruncated": False,
+                    "toolResult": {"type": "Bash", "output": [], "output_for_prompt": "{big_output}",
+                                   "exit_code": 0, "command": "make build", "truncated": False, "signal": None,
+                                   "timed_out": False, "current_dir": "/tmp", "output_file": "", "total_bytes": 0}}
+        return {**common, "source": "manual"}
+
+    def expects_output(self, event: str) -> bool:
+        return event == "PostToolUse"
+
+
+class DockerAgentInstaller(Installer):
+    """``<config dir>/hooks.d/50-subcortex.yaml`` — a drop-in we own."""
+
+    name = "docker-agent"
+    display_name = "Docker Agent"
+    seam = "hooks"
+    binaries = ("docker-agent", "cagent")
+    docs = "https://github.com/docker/docker-agent/blob/main/docs/configuration/hooks/index.md"
+    min_version = "1.137.0"
+    post_install = "applies to new `docker-agent run` sessions"
+    EVENTS = {"user_prompt_submit": 5, "user_steering_messages_submit": 5, "user_followup_submit": 5,
+              "tool_response_transform": 10, "before_compaction": 10, "after_compaction": 5}
+
+    def _content(self) -> str:
+        q = json.dumps  # JSON strings are valid YAML double-quoted scalars
+        lines = ["# Managed by subcortex (subcortex install docker-agent). Do not edit.",
+                 "# Uninstall: subcortex uninstall docker-agent"]
+        for event, timeout in self.EVENTS.items():
+            hook = [f"name: {q('subcortex:' + event)}", "type: command",
+                    f"command: {q(self.command(event))}", f"timeout: {timeout}", "on_error: ignore"]
+            lines.append(f"{event}:")
+            if event == "tool_response_transform":
+                lines += ['  - matcher: "shell"', "    hooks:", f"      - {hook[0]}"]
+                lines += [f"        {h}" for h in hook[1:]]
+            else:
+                lines.append(f"  - {hook[0]}")
+                lines += [f"    {h}" for h in hook[1:]]
+        return "\n".join(lines) + "\n"
+
+    def targets(self) -> List[Target]:
+        return [owned_file_target(docker_config_dir() / "hooks.d" / "50-subcortex.yaml", self._content())]
+
+    def hook_events(self) -> List[str]:
+        return list(self.EVENTS)
+
+    def sample_payload(self, event: str) -> Dict[str, Any]:
+        common = {"session_id": SESSION, "cwd": "/tmp", "hook_event_name": event, "agent_name": "root"}
+        if event == "user_prompt_submit":
+            return {**common, "prompt": "what does ls -la do?"}
+        if event == "user_steering_messages_submit":
+            return {**common, "steering_messages": ["also, what does ls -a do?"]}
+        if event == "user_followup_submit":
+            return {**common, "prompt": "and ls -l?"}
+        if event == "tool_response_transform":
+            return {**common, "tool_category": "shell", "tool_name": "shell", "tool_use_id": "call_1",
+                    "tool_input": {"cmd": "make build"}, "tool_response": "{big_output}"}
+        return {**common, "compaction_reason": "manual", "input_tokens": 90000}
+
+    def expects_output(self, event: str) -> bool:
+        return event in ("user_prompt_submit", "user_steering_messages_submit", "user_followup_submit",
+                         "tool_response_transform")
+
+
+class LettaInstaller(ClaudeStyleInstaller):
+    """``~/.letta/settings.json`` → ``hooks`` (timeouts in ms, ``quiet`` so hints aren't echoed)."""
+
+    name = "letta"
+    display_name = "Letta Code"
+    binaries = ("letta",)
+    docs = "https://docs.letta.com/letta-code/hooks"
+    post_install = ("restart letta (and don't edit hooks via /hooks in a session started before this "
+                    "install); hints apply to interactive sessions (letta -p skips the prompt hook)")
+
+    def settings_path(self) -> Path:
+        return Path.home() / ".letta" / "settings.json"
+
+    def entry(self, event: str) -> Dict[str, Any]:
+        return {"type": "command", "command": self.command(event), "timeout": 5000, "quiet": True}
+
+    def matcher(self, event: str) -> Optional[str]:
+        return None
+
+    def sample_payload(self, event: str) -> Dict[str, Any]:
+        return {"event_type": "UserPromptSubmit", "working_directory": "/tmp", "prompt": "what does ls -la do?",
+                "is_command": False, "agent_id": "agent-1", "conversation_id": "conv-1"}
+
+
+class VibeInstaller(Installer):
+    """A marked ``[[hooks]]`` block in ``$VIBE_HOME/hooks.toml`` (Vibe never rewrites that file)."""
+
+    name = "vibe"
+    display_name = "Mistral Vibe"
+    seam = "hooks"
+    binaries = ("vibe",)
+    docs = "https://github.com/mistralai/mistral-vibe#hooks"
+    min_version = "2.25.5"
+    post_install = "restart vibe to load the hook"
+
+    def vibe_home(self) -> Path:
+        override = os.environ.get("VIBE_HOME", "").strip()
+        return Path(override).expanduser() if override else Path.home() / ".vibe"
+
+    def targets(self) -> List[Target]:
+        body = "\n".join([
+            "[[hooks]]",
+            'name = "subcortex-post-tool"',
+            'type = "post_tool"',
+            'match = "bash"',
+            f"command = {toml_str(self.command('post_tool'))}",
+            "timeout = 10.0",
+            'description = "subcortex: trim large, disposable shell output"',
+        ]) + "\n"
+        return [toml_block_target(self.vibe_home() / "hooks.toml", body, self.name)]
+
+    def hook_events(self) -> List[str]:
+        return ["post_tool"]
+
+    def sample_payload(self, event: str) -> Dict[str, Any]:
+        return {"session_id": SESSION, "transcript_path": "{transcript}", "cwd": "/tmp",
+                "hook_event_name": "post_tool", "tool_name": "bash", "tool_call_id": "call_1",
+                "tool_input": {"command": "make build"}, "tool_status": "success",
+                "tool_output_text": "{big_output}", "tool_error": None}
+
+    def expects_output(self, event: str) -> bool:
+        return True

subcortex/installers/opencode.py

@@ -0,0 +1,66 @@
+"""OpenCode and Kilo Code CLI: one Bun plugin file (+ optional MCP entry for OpenCode).
+
+Both load every ``*.ts`` in their global plugin directory at startup with no
+trust step; the file name is the tag, so uninstall deletes exactly our file.
+Kilo is an OpenCode fork with its own directories (it doesn't read OpenCode's).
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any, Dict, List
+
+from .base import Installer, Target, rendered_plugin, json_target, plugin_file_target
+
+
+def _config_home() -> Path:
+    xdg = os.environ.get("XDG_CONFIG_HOME", "").strip()
+    return Path(xdg) if xdg else Path.home() / ".config"
+
+
+class OpenCodeInstaller(Installer):
+    name = "opencode"
+    display_name = "OpenCode"
+    seam = "plugin"
+    binaries = ("opencode",)
+    docs = "https://opencode.ai/docs/plugins/"
+    min_version = "1.1.62"
+    supports_mcp = True
+    post_install = "restart opencode to load the plugin"
+    plugin_dir = ("opencode", "plugins")
+
+    def plugin_path(self) -> Path:
+        return _config_home().joinpath(*self.plugin_dir) / "subcortex.ts"
+
+    def targets(self) -> List[Target]:
+        content = rendered_plugin("opencode")
+        targets = [plugin_file_target(self.plugin_path(), content)]
+        if self.mcp:
+            argv = self.mcp_command()
+
+            def add(data: Dict[str, Any]) -> None:
+                servers = data.get("mcp")
+                if not isinstance(servers, dict):
+                    servers = data["mcp"] = {}
+                servers["subcortex"] = {"type": "local", "command": argv, "enabled": True}
+
+            def remove(data: Dict[str, Any]) -> None:
+                servers = data.get("mcp")
+                if isinstance(servers, dict) and servers.pop("subcortex", None) is not None and not servers:
+                    del data["mcp"]
+
+            targets.append(json_target(_config_home() / "opencode" / "opencode.json", add, remove,
+                                       lambda d: isinstance(d.get("mcp"), dict) and "subcortex" in d["mcp"]))
+        return targets
+
+
+class KiloInstaller(OpenCodeInstaller):
+    name = "kilo"
+    display_name = "Kilo Code CLI"
+    binaries = ("kilo",)
+    docs = "https://kilo.ai/docs/cli"
+    min_version = None
+    supports_mcp = False
+    post_install = "restart kilo to load the plugin"
+    plugin_dir = ("kilo", "plugin")