agent: str

kind: str # hook | plugin | native | screen

lifecycle: bool

session_restore: bool

Integration("claude", "hook", True, True), Integration("codex", "hook", True, True, "also reads its session logs without the hook"),

Integration("copilot", "hook", True, True), Integration("cursor", "hook", True, True),

Integration("opencode", "plugin", True, True), Integration("pi", "plugin", True, True),

Integration("omp", "plugin", True, True), Integration("devin", "hook", True, True),

Integration("droid", "hook", False, True, "session id only; state from the screen"),

Integration("kimi", "hook", True, True, "needs Kimi Code 0.14+"), Integration("kilo", "plugin", True, True),

Integration("hermes", "plugin", False, True, "session id only; state from the screen"), Integration("qodercli", "hook", False, True, "session id only; state from the screen"),

Integration("qwen", "hook", False, True, "session id only; state from the screen"), Integration("letta", "hook", False, True, "session id only; experimental upstream"),

Integration("mastracode", "hook", True, True), Integration("grok", "hook", False, True, "session id only; state from the screen"),

Integration("antigravity", "hook", False, True, "session id only; state from the screen"), Integration("amp", "screen", False, False),

Integration("kiro", "screen", False, False), Integration("maki", "screen", False, False),

Integration("gemini", "hook", True, True), Integration("cline", "screen", False, False),

Integration("command", "native", True, False), Integration("crush", "native", True, False),

Integration("muse", "native", True, False), Integration("prime", "native", True, False),

"""Serializable integration capabilities, optionally marked by installed CLI."""

installed = installed or set()

out = []

for item in sorted(INTEGRATIONS, key=lambda i: (i.agent not in PRIORITY, PRIORITY.index(i.agent) if i.agent in PRIORITY else 0)):

st = status(item.agent, item.agent in installed) if item.agent in INSTALLERS else {"status": "unsupported"}

out.append({**asdict(item), "tier": "priority" if item.agent in PRIORITY else "later",

"available": item.agent in installed or st.get("available", False), "installable": item.agent in INSTALLERS,

"config_found": bool(st.get("available")), "status": st["status"]})

"""`"<python>" -m shelldeck.hook <agent> [event]`: absolute interpreter, so it works from any PATH.

if frozen.FROZEN:

return f'"{frozen.sd().as_posix()}" shelldeck.hook {agent}' + (f" {event}" if event else "")

exe = sys.executable.replace("\\", "/")

"""Missing or empty -> fallback; unreadable -> ValueError, and the file is left alone."""

if not file.exists():

return json.loads(json.dumps(fallback))

text = file.read_text(encoding="utf-8").lstrip("")

if not text.strip():

return json.loads(json.dumps(fallback))

try:

data = json.loads(text)

except ValueError:

raise ValueError(f"{file} is not plain JSON (comments or trailing commas?), so it wasn't changed: "

"remove them and install again") from None

if not isinstance(data, dict):

raise ValueError(f"{file} is not a JSON object, so it wasn't changed")

"""Atomic: a half-written config would break the agent."""

file.parent.mkdir(parents=True, exist_ok=True)

tmp = file.with_name(file.name + ".shelldeck-tmp")

tmp.write_text(text, encoding="utf-8")

"""Hooks in a shared JSON config: {"hooks": {Event: [entry, ...]}}."""

def __init__(self, agent: str, file, entry, top: dict | None = None, key: str | None = "hooks"):

# key=None: events at the top level of the file (MastraCode's hooks.json)

self.agent, self._file, self.entry, self.top, self.key = agent, file, entry, top or {}, key

def _box(self, cfg: dict, create: bool = False):

if self.key is None:

return cfg

if create:

return cfg.setdefault(self.key, {})

box = cfg.get(self.key)

return box if isinstance(box, dict) else None

@property

def file(self) -> Path:

return self._file()

def events(self) -> list[str]:

return [e for e, s in hook.EVENTS[self.agent].items() if s is not None or e in ("Notification", "notification")]

def _is_ours(self, item) -> bool:

if not isinstance(item, dict):

return False

cmds = [item.get("command")] + [h.get("command") for h in item.get("hooks", []) if isinstance(h, dict)]

return any(_ours(c, self.agent) for c in cmds)

def _strip(self, cfg: dict) -> bool:

changed = False

hooks = self._box(cfg)

if hooks is None:

return False

for event, items in list(hooks.items()):

if not isinstance(items, list):

continue

kept = [i for i in items if not self._is_ours(i)]

changed |= len(kept) != len(items)

if kept:

hooks[event] = kept

else:

del hooks[event]

if changed and not hooks and self.key:

del cfg[self.key]

return changed

def installed_commands(self) -> list[str]:

try:

hooks = self._box(_read_json(self.file, {})) or {}

except ValueError:

return []

out = []

for event, items in hooks.items() if isinstance(hooks, dict) else ():

for i in items if isinstance(items, list) else ():

if self._is_ours(i):

out.append(event)

return out

def install(self) -> dict:

if not self.file.parent.is_dir():

raise ValueError(f"{self.agent} config folder not found at {self.file.parent}; install {self.agent} first")

cfg = _read_json(self.file, self.top)

if self.key and cfg.get(self.key) is not None and not isinstance(cfg[self.key], dict):

raise ValueError(f"{self.file} has an unexpected \"{self.key}\" value, so it wasn't changed")

_backup(self.file)

self._strip(cfg)

for k, v in self.top.items():

cfg.setdefault(k, v)

hooks = self._box(cfg, create=True)

for event in self.events():

hooks.setdefault(event, []).append(self.entry(event))

_write(self.file, json.dumps(cfg, indent=2) + "\n")

return {"file": str(self.file)}

def uninstall(self) -> dict:

if not self.file.exists():

return {"file": str(self.file)}

cfg = _read_json(self.file, {})

if self._strip(cfg):

_write(self.file, json.dumps(cfg, indent=2) + "\n")

return {"file": str(self.file)}

def state(self) -> tuple[bool, bool]:

"""(installed, current): current = every event hooked and its interpreter still exists."""

found = self.installed_commands()

if not found:

return False, False

try:

cmds = [c for items in (self._box(_read_json(self.file, {})) or {}).values() if isinstance(items, list) for i in items if self._is_ours(i)

for c in [i.get("command")] + [h.get("command") for h in i.get("hooks", []) if isinstance(h, dict)] if _ours(c, self.agent)]

except (ValueError, AttributeError):

cmds = []

exe_ok = all((p := _python_of(c)) and Path(p).exists() for c in cmds) and bool(cmds)

"""A file shelldeck owns entirely (Copilot's hook file, OpenCode's plugin)."""

def __init__(self, agent: str, file, render, marker: str):

self.agent, self._file, self.render, self.marker = agent, file, render, marker

@property

def file(self) -> Path:

return self._file()

def install(self) -> dict:

root = self.file.parent.parent if self.file.parent.name in ("hooks", "plugins", "plugin", "extensions") else self.file.parent

if not root.is_dir():

raise ValueError(f"{self.agent} config folder not found at {root}; install {self.agent} first")

if self.file.exists() and self.marker not in self.file.read_text(encoding="utf-8", errors="replace"):

_backup(self.file)

_write(self.file, self.render())

return {"file": str(self.file)}

def uninstall(self) -> dict:

if self.file.exists() and self.marker in self.file.read_text(encoding="utf-8", errors="replace"):

self.file.unlink()

bak = self.file.with_name(self.file.name + ".shelldeck-backup")

if bak.exists() and not self.file.exists():

os.replace(bak, self.file)

return {"file": str(self.file)}

def state(self) -> tuple[bool, bool]:

if not self.file.exists():

return False, False

text = self.file.read_text(encoding="utf-8", errors="replace")

if self.marker not in text:

return False, False

"""~/.codex/hooks.json plus `[features] hooks = true` in config.toml, which Codex needs to run hooks (as herdr

@property

def config(self) -> Path:

return self.file.with_name("config.toml")

def install(self) -> dict:

out = super().install()

text = self.config.read_text(encoding="utf-8") if self.config.exists() else ""

new = enable_codex_hooks(text)

if new != text:

_backup(self.config)

_write(self.config, new)

return out

def state(self) -> tuple[bool, bool]:

on, current = super().state()

text = self.config.read_text(encoding="utf-8") if self.config.exists() else ""

"""Set `hooks = true` in the top-level [features] table (line edit: comments and order are kept)."""

lines = text.splitlines()

in_features, header, hooks_at = False, None, None

for i, line in enumerate(lines):

s = line.strip()

if s.startswith("["):

in_features = s.split("#", 1)[0].strip() == "[features]"

if in_features and header is None:

header = i

continue

if in_features and re.match(r"(hooks|codex_hooks)\s*=", s):

hooks_at = hooks_at if hooks_at is not None else i

if s.startswith("codex_hooks"):

lines[i] = "hooks = true"

if hooks_at is not None:

lines[hooks_at] = "hooks = true"

elif header is not None:

lines.insert(header + 1, "hooks = true")

else:

lines += ([""] if lines and lines[-1].strip() else []) + ["[features]", "hooks = true"]

if os.environ.get("XDG_CONFIG_HOME"):

return Path(os.environ["XDG_CONFIG_HOME"]) / "devin"

if sys.platform == "win32" and os.environ.get("APPDATA"):

return Path(os.environ["APPDATA"]) / "devin"

"""A Claude-shaped hook group: {matcher?, hooks: [{type: command, command, timeout}]}."""

def entry(event: str) -> dict:

group = {"hooks": [{"type": "command", "command": hook_command(agent), "timeout": timeout}]}

return {"matcher": matcher, **group} if matcher else group

"""One shelldeck-owned key in a JSON file keyed by hook name (Antigravity CLI's hooks.json)."""

def __init__(self, agent: str, file, render):

self.agent, self._file, self.render = agent, file, render

@property

def file(self) -> Path:

return self._file()

def install(self) -> dict:

if not self.file.parent.is_dir():

raise ValueError(f"{self.agent} config folder not found at {self.file.parent}; install {self.agent} first")

cfg = _read_json(self.file, {})

_backup(self.file)

cfg["shelldeck"] = self.render()

_write(self.file, json.dumps(cfg, indent=2) + "\n")

return {"file": str(self.file)}

def uninstall(self) -> dict:

if self.file.exists():

cfg = _read_json(self.file, {})

if cfg.pop("shelldeck", None) is not None:

_write(self.file, json.dumps(cfg, indent=2) + "\n")

return {"file": str(self.file)}

def state(self) -> tuple[bool, bool]:

try:

block = _read_json(self.file, {}).get("shelldeck")

except ValueError:

return False, False

("PreToolUse", "^(?!AskUserQuestion$).*$", "working"), ("PreToolUse", "^AskUserQuestion$", "blocked"),

("PostToolUse", "^AskUserQuestion$", "working"), ("PostToolUseFailure", "^AskUserQuestion$", "working"),

("SubagentStart", None, "working"), ("PreCompact", None, "working"), ("PermissionRequest", None, "blocked"),

out, inside = [], False

for line in text.splitlines():

if line.strip() == KIMI_BEGIN:

inside = True

elif line.strip() == KIMI_END and inside:

inside = False

elif not inside:

out.append(line)

body = "\n".join(out).rstrip("\n")

"""A marked `[[hooks]]` block at the end of Kimi Code's config.toml (needs Kimi 0.14+, as herdr notes)."""

agent = "kimi"

@property

def file(self) -> Path:

return _home("KIMI_CODE_HOME", ".kimi-code") / "config.toml"

def install(self) -> dict:

if not self.file.parent.is_dir():

raise ValueError(f"kimi config folder not found at {self.file.parent}; install kimi first")

text = self.file.read_text(encoding="utf-8") if self.file.exists() else ""

rest = strip_kimi_block(text)

new = (rest + "\n" if rest else "") + kimi_block()

if new != text:

_backup(self.file)

_write(self.file, new)

return {"file": str(self.file)}

def uninstall(self) -> dict:

if self.file.exists():

text = self.file.read_text(encoding="utf-8")

if KIMI_BEGIN in text:

_write(self.file, strip_kimi_block(text))

return {"file": str(self.file)}

def state(self) -> tuple[bool, bool]:

text = self.file.read_text(encoding="utf-8") if self.file.exists() else ""

if KIMI_BEGIN not in text:

return False, False

"""Add/remove the plugin in config.yaml's `plugins.enabled` block list. Only simple layouts are edited;

item = f" - {HERMES_PLUGIN}"

lines = text.splitlines()

top = [i for i, line in enumerate(lines) if line.startswith("plugins:")]

if not top:

if not on:

return text

body = text.rstrip("\n")

return (body + "\n" if body else "") + f"plugins:\n enabled:\n{item}\n"

i = top[0]

if lines[i].strip() != "plugins:":

raise ValueError("config.yaml has an inline `plugins:` value; add shelldeck-agent-state to plugins.enabled by hand")

end = next((j for j in range(i + 1, len(lines)) if lines[j] and not lines[j].startswith((" ", "#"))), len(lines))

en = next((j for j in range(i + 1, end) if lines[j].rstrip() == " enabled:"), None)

if on:

if any(line.rstrip() == item for line in lines[i:end]):

return text

if en is None:

if any(lines[j].startswith(" enabled") for j in range(i + 1, end)):

raise ValueError("config.yaml lists plugins.enabled inline; add shelldeck-agent-state to it by hand")

lines[i + 1:i + 1] = [" enabled:", item]

else:

lines.insert(en + 1, item)

else:

lines = [line for j, line in enumerate(lines) if not (i < j < end and line.rstrip() == item)]

k = next((j for j, line in enumerate(lines) if line.rstrip() == " enabled:"), None)

# drop an `enabled:` / `plugins:` we left empty

if k is not None and (k + 1 >= len(lines) or not lines[k + 1].startswith(" ")):

del lines[k]

p = lines.index("plugins:") if "plugins:" in lines else None

if p is not None and (p + 1 >= len(lines) or not lines[p + 1].startswith(" ")):

del lines[p]

out = "\n".join(lines)

agent = "hermes"

@property

def root(self) -> Path:

if os.environ.get("HERMES_HOME"):

return Path(os.environ["HERMES_HOME"])

if sys.platform == "win32" and os.environ.get("LOCALAPPDATA"):

return Path(os.environ["LOCALAPPDATA"]) / "hermes"

return Path.home() / ".hermes"

@property

def file(self) -> Path:

return self.root / "plugins" / HERMES_PLUGIN / "__init__.py"

def install(self) -> dict:

if not self.root.is_dir():

raise ValueError(f"hermes config folder not found at {self.root}; install hermes first")

cfg = self.root / "config.yaml"

text = cfg.read_text(encoding="utf-8") if cfg.exists() else ""

new = hermes_enable(text, True) # raises before anything is written

_write(self.file, HERMES_INIT)

_write(self.file.with_name("plugin.yaml"), HERMES_MANIFEST)

if new != text:

_backup(cfg)

_write(cfg, new)

return {"file": str(self.file)}

def uninstall(self) -> dict:

cfg = self.root / "config.yaml"

if cfg.exists():

text = cfg.read_text(encoding="utf-8")

try:

new = hermes_enable(text, False)

except ValueError:

new = text

if new != text:

_write(cfg, new)

shutil.rmtree(self.file.parent, ignore_errors=True)

return {"file": str(self.file)}

def state(self) -> tuple[bool, bool]:

if not self.file.exists():

return False, False

cfg = self.root / "config.yaml"

enabled = cfg.exists() and f" - {HERMES_PLUGIN}" in cfg.read_text(encoding="utf-8").splitlines()

"pi": ''' pi.on("agent_settled", (_e, ctx) => { if (root && ctx?.isIdle?.() === true) send("done") })

''',

"omp": ''' pi.on("session_switch", (_e, ctx) => { if (start(ctx)) send("idle") })

''',

"""A Pi/OMP extension file; installing needs the agent's own folder (the extensions dir's parent)."""

def install(self) -> dict:

if not self.file.parent.parent.is_dir():

raise ValueError(f"{self.agent} config folder not found at {self.file.parent.parent}; install {self.agent} first")

if self.agent == "omp" and _omp_dir() == _pi_dir():

raise ValueError("pi and omp use the same extensions folder; set separate agent folders first")

self.file.parent.mkdir(exist_ok=True)

"claude": JsonHooks("claude", lambda: _home("CLAUDE_CONFIG_DIR", ".claude") / "settings.json",

lambda e: {"hooks": [{"type": "command", "command": hook_command("claude"), "timeout": 5, "async": True}]}),

"gemini": JsonHooks("gemini", lambda: _home("GEMINI_DIR", ".gemini") / "settings.json",

lambda e: {"matcher": "*", "hooks": [{"name": "shelldeck", "type": "command", "command": hook_command("gemini"), "timeout": 5000}]}),

"cursor": JsonHooks("cursor", lambda: _home("CURSOR_DIR", ".cursor") / "hooks.json",

lambda e: {"command": hook_command("cursor"), "timeout": 5}, top={"version": 1}),

# herdr's formats (src/integration/targets.rs); Qwen/Qoder/Droid/Devin report the session id only

"codex": CodexHooks("codex", lambda: _home("CODEX_HOME", ".codex") / "hooks.json", _cmd_entry("codex", 10)),

"qwen": JsonHooks("qwen", lambda: _home("QWEN_HOME", ".qwen") / "settings.json", _cmd_entry("qwen", 10_000, "*")),

"qodercli": JsonHooks("qodercli", lambda: _home("QODER_CONFIG_DIR", ".qoder") / "settings.json", _cmd_entry("qodercli", 10, "*")),

"droid": JsonHooks("droid", lambda: Path.home() / ".factory" / "settings.json", _cmd_entry("droid", 10)),

"devin": JsonHooks("devin", lambda: _devin_dir() / "config.json", _cmd_entry("devin", 10)),

"mastracode": JsonHooks("mastracode", lambda: Path.home() / ".mastracode" / "hooks.json", _flat_entry("mastracode", 10_000), key=None),

"kimi": KimiToml(),

"letta": JsonHooks("letta", lambda: Path.home() / ".letta" / "settings.json",

lambda e: {"hooks": [{"type": "command", "command": hook_command("letta"), "timeout": 10_000, "quiet": True}]}),

"hermes": HermesPlugin(),

"pi": Extension("pi", lambda: _pi_dir() / "shelldeck-agent-state.ts", lambda: _pi_extension("pi"), "shelldeck-pi-extension"),

"omp": Extension("omp", lambda: _omp_dir() / "shelldeck-omp-agent-state.ts", lambda: _pi_extension("omp"), "shelldeck-omp-extension"),

"antigravity": NamedBlock("antigravity", lambda: _home("ANTIGRAVITY_CLI_CONFIG_DIR", ".gemini", "config") / "hooks.json", _antigravity_block),

"grok": OwnFile("grok", lambda: _home("GROK_HOME", ".grok") / "hooks" / "shelldeck.json", _grok_file, "shelldeck.hook grok"),

"kilo": OwnFile("kilo", lambda: _xdg() / "kilo" / "plugin" / "shelldeck.js", lambda: _opencode_plugin("kilo"), "shelldeck-kilo-plugin"),

"copilot": OwnFile("copilot", lambda: _home("COPILOT_HOME", ".copilot") / "hooks" / "shelldeck.json", _copilot_file, "shelldeck.hook copilot"),

"opencode": OwnFile("opencode", lambda: _xdg() / "opencode" / "plugins" / "shelldeck.js", _opencode_plugin, OPENCODE_MARKER),

"""The agent's own config folder (installing needs it to exist)."""

f = inst.file

if isinstance(inst, HermesPlugin):

return inst.root

"""Per-run hooks as the agent's own command-line flags, so nothing global changes. Only Claude Code has such a

if agent != "claude" or INSTALLERS["claude"].state()[0]:

return []

from . import db # noqa: PLC0415 - integrations stays importable without the database

inst = INSTALLERS["claude"]

file = db.config_dir() / "agent-hooks" / "claude-settings.json"

text = json.dumps({"hooks": {e: [inst.entry(e)] for e in inst.events()}}, indent=2) + "\n"

if not file.exists() or file.read_text(encoding="utf-8") != text:

_write(file, text)

"""installed | outdated (re-install to fix: moved interpreter, changed events) | not_installed | unsupported | error."""

inst = INSTALLERS.get(agent)

if not inst:

return {"agent": agent, "status": "unsupported", "file": None}

try:

on, current = inst.state()

except (OSError, ValueError) as e:

return {"agent": agent, "status": "error", "file": str(inst.file), "detail": str(e)}

return {"agent": agent, "status": "installed" if on and current else "outdated" if on else "not_installed",