derot 0.1.0__py3-none-any.whl

derot/__init__.py

@@ -0,0 +1,3 @@
+"""derot: one console for every Claude Code and Codex session."""
+
+__version__ = "0.1.0"

derot/__main__.py

@@ -0,0 +1,5 @@
+import sys
+
+from .cli import main
+
+sys.exit(main())

derot/cli.py

@@ -0,0 +1,287 @@
+"""derot command-line entry point."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+import time
+from typing import List, Optional
+
+from . import __version__
+from . import config as config_mod
+from . import log as log_mod
+from .config import ConfigError
+from .log import log
+
+
+def _load(create: bool = False):
+    path = config_mod.config_path()
+    created = config_mod.ensure_config(path) if create else False
+    return config_mod.load(path), created
+
+
+def _hex_to_ansi(color: str, text: str, bold: bool) -> str:
+    r, g, b = (int(color[i:i + 2], 16) for i in (1, 3, 5))
+    return f"\033[{'1;' if bold else ''}38;2;{r};{g};{b}m{text}\033[0m"
+
+
+def cmd_tui(args) -> int:
+    cfg, created = _load(create=True)
+    if created:
+        print(f"Created a starter config at {cfg.path}")
+    from . import tui
+    tui.run(cfg, created=created)
+    return 0
+
+
+def cmd_init(args) -> int:
+    path = config_mod.config_path()
+    if config_mod.ensure_config(path):
+        print(f"Created {path}")
+        print("Next: edit it, then run `derot login ACCOUNT` and `derot setup`.")
+    else:
+        print(f"{path} already exists")
+    return 0
+
+
+def cmd_setup(args) -> int:
+    from . import installer
+    cfg, _ = _load()
+    return installer.setup(cfg, remove=args.remove)
+
+
+def cmd_ls(args) -> int:
+    from . import sessions
+    from .notify import brief
+    from .sessions import STYLE
+    cfg, _ = _load()
+    statuses, offline = sessions.poll_full(cfg)
+    if not statuses:
+        print(f"no sessions yet — add some to {cfg.path}")
+        return 0
+    color = sys.stdout.isatty()
+    now = time.time()
+    rows = []
+    for st in statuses:
+        icon, _, hexcolor, bold = STYLE[st.state]
+        name = st.name + (" ◂" if st.attached else "")
+        rows.append((icon, name, st.account.name, st.host.name,
+                     sessions.status_text(st, now), brief(sessions.happening(st), 100),
+                     hexcolor, bold))
+    headers = ("", "SESSION", "ACCOUNT", "MACHINE", "STATUS", "WHAT'S HAPPENING")
+    widths = [max(len(headers[i]), *(len(r[i]) for r in rows)) for i in range(5)]
+
+    def line(cells, hexcolor=None, bold=False) -> str:
+        parts = [cells[i].ljust(widths[i]) for i in range(5)] + [cells[5]]
+        if color and hexcolor:
+            parts[0] = _hex_to_ansi(hexcolor, parts[0], bold)
+            parts[4] = _hex_to_ansi(hexcolor, parts[4], bold)
+        return "  ".join(parts).rstrip()
+
+    print(line(headers))
+    for r in rows:
+        print(line(r[:6], r[6], r[7]))
+    for host, err in offline.items():
+        print(f"✗ can't reach {host}: {err}", file=sys.stderr)
+    return 0
+
+
+def cmd_start(args) -> int:
+    from . import installer, sessions
+    cfg, _ = _load()
+    cfg.session(args.name)
+    try:
+        s = cfg.session(args.name)
+        if not installer.ensure_hooks(cfg, cfg.host_of(s), cfg.account_of(s)):
+            print(f"derot: status hooks for {s.account} on {s.host} couldn't be set up "
+                  "(see `derot log`)", file=sys.stderr)
+        sessions.start(cfg, args.name, cont=args.cont, resume=args.resume or "")
+    except sessions.SessionError as e:
+        print(f"derot: {e}", file=sys.stderr)
+        return 1
+    if args.detach:
+        print(f"started {args.name}")
+        return 0
+    return sessions.attach(cfg, args.name)
+
+
+def cmd_history(args) -> int:
+    from . import sessions
+    cfg, _ = _load()
+    cfg.session(args.name)
+    try:
+        items = sessions.conversations(cfg, args.name, limit=args.n)
+    except sessions.SessionError as e:
+        print(f"derot: {e}", file=sys.stderr)
+        return 1
+    if not items:
+        print(f"no past conversations for {args.name}")
+    for c in items:
+        print(f"{c.id}  {sessions.age(c.mtime):>4} ago  {' '.join((c.title or c.first).split())[:70]}")
+    return 0
+
+
+def cmd_attach(args) -> int:
+    from . import sessions
+    cfg, _ = _load()
+    cfg.session(args.name)
+    return sessions.attach(cfg, args.name)
+
+
+def cmd_stop(args) -> int:
+    from . import sessions
+    cfg, _ = _load()
+    cfg.session(args.name)
+    try:
+        sessions.stop(cfg, args.name)
+    except sessions.SessionError as e:
+        print(f"derot: {e}", file=sys.stderr)
+        return 1
+    print(f"stopped {args.name}")
+    return 0
+
+
+def cmd_watch(args) -> int:
+    from . import sessions
+    from .notify import Notifier
+    from .notify import acquire_watch_lock
+    cfg, _ = _load()
+    if not acquire_watch_lock():
+        print("derot watch is already running", file=sys.stderr)
+        return 1
+    notifier = Notifier(cfg.notify)
+    print(f"watching {len(cfg.sessions)} session(s) every {cfg.refresh:g}s — Ctrl-C to stop")
+    mtime = _mtime(cfg.path)
+    try:
+        while True:
+            m = _mtime(cfg.path)
+            if m != mtime:
+                mtime = m
+                try:
+                    cfg = config_mod.load(cfg.path)
+                    notifier.settings = cfg.notify
+                    print("config reloaded")
+                except ConfigError as e:
+                    log.error("watch: config not reloaded: %s", e)
+                    print(f"config not reloaded: {e}", file=sys.stderr)
+            try:
+                statuses = sessions.poll(cfg)
+                for title, body in notifier.update(statuses):
+                    print(f"{time.strftime('%H:%M:%S')}  {title}: {body}", flush=True)
+            except Exception as e:  # keep watching; logged too (a service's stderr is unread)
+                log.error("watch: poll failed: %s", e, exc_info=e)
+                print(f"poll failed: {e}", file=sys.stderr)
+            time.sleep(cfg.refresh)
+    except KeyboardInterrupt:
+        return 0
+
+
+def _mtime(path) -> float:
+    try:
+        return path.stat().st_mtime if path else 0.0
+    except OSError:
+        return 0.0
+
+
+def cmd_log(args) -> int:
+    path = log_mod.log_path()
+    if args.follow:
+        import subprocess
+        try:
+            return subprocess.call(["tail", "-n", str(args.lines), "-F", str(path)])
+        except KeyboardInterrupt:
+            return 0
+    text = log_mod.tail(args.lines)
+    print(text if text else "(empty)")
+    print(f"\n— {path}   (derot log -f to follow; DEROT_DEBUG=1 logs every command)",
+          file=sys.stderr)
+    return 0
+
+
+def cmd_login(args) -> int:
+    from . import sessions
+    cfg, _ = _load()
+    try:
+        return sessions.login(cfg, args.account, args.host)
+    except sessions.SessionError as e:
+        print(f"derot: {e}", file=sys.stderr)
+        return 1
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="derot",
+        description="One console for every Claude Code and Codex session, across "
+                    "projects, accounts and machines.",
+    )
+    p.add_argument("--version", action="version", version=f"derot {__version__}")
+    p.set_defaults(func=cmd_tui)
+    sub = p.add_subparsers(dest="command", metavar="COMMAND")
+
+    sub.add_parser("init", help="create the config file").set_defaults(func=cmd_init)
+
+    sp = sub.add_parser("setup", help="install / remove status hooks on every host+account")
+    sp.add_argument("--remove", action="store_true", help="remove the hooks instead")
+    sp.set_defaults(func=cmd_setup)
+
+    sub.add_parser("ls", help="print a status table").set_defaults(func=cmd_ls)
+
+    sp = sub.add_parser("start", help="start a session and attach to it")
+    sp.add_argument("name")
+    sp.add_argument("-c", "--continue", dest="cont", action="store_true",
+                    help="resume the last conversation in that folder")
+    sp.add_argument("-r", "--resume", metavar="ID",
+                    help="resume that conversation (ids from `derot history NAME`)")
+    sp.add_argument("-d", "--detach", action="store_true", help="don't attach")
+    sp.set_defaults(func=cmd_start)
+
+    sp = sub.add_parser("history", help="list a session's past conversations (newest first)")
+    sp.add_argument("name")
+    sp.add_argument("-n", type=int, default=20, help="how many (default 20)")
+    sp.set_defaults(func=cmd_history)
+
+    sp = sub.add_parser("attach", help="attach to a running session")
+    sp.add_argument("name")
+    sp.set_defaults(func=cmd_attach)
+
+    sp = sub.add_parser("stop", help="stop a session")
+    sp.add_argument("name")
+    sp.set_defaults(func=cmd_stop)
+
+    sub.add_parser("watch", help="poll and send notifications without the console"
+                   ).set_defaults(func=cmd_watch)
+
+    sp = sub.add_parser("log", help="show the log (~/.derot/derot.log), for tracing errors")
+    sp.add_argument("-n", "--lines", type=int, default=60, help="how many lines (default 60)")
+    sp.add_argument("-f", "--follow", action="store_true", help="keep printing new lines")
+    sp.set_defaults(func=cmd_log)
+
+    sp = sub.add_parser("login", help="log in to an account (Claude Code: /login; Codex: codex login)")
+    sp.add_argument("account")
+    sp.add_argument("--host", default="local")
+    sp.set_defaults(func=cmd_login)
+    return p
+
+
+def main(argv: Optional[List[str]] = None) -> int:
+    args = build_parser().parse_args(argv)
+    log_mod.setup()
+    if args.func is not cmd_log:
+        log.debug("derot %s", " ".join(sys.argv[1:] if argv is None else argv))
+    try:
+        return int(args.func(args) or 0)
+    except ConfigError as e:
+        log.error("config error: %s", e)
+        print(f"derot: {e}", file=sys.stderr)
+        return 2
+    except KeyboardInterrupt:
+        return 130
+    except Exception as e:
+        log.critical("unexpected error in `derot %s`", args.command or "", exc_info=e)
+        print(f"derot: unexpected error: {e}\n(full traceback in {log_mod.log_path()})",
+              file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

derot/config.py

@@ -0,0 +1,359 @@
+"""Load and validate ~/.config/derot/config.yaml."""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Dict, List, Optional
+
+import yaml
+
+from .log import log
+
+NAME_RE = re.compile(r"^[A-Za-z0-9_-][A-Za-z0-9_.-]*$")
+DEFAULT_CONFIG_DIR = "~/.claude"
+
+# The coding agents derot can run. Each account belongs to one: its folder is that agent's
+# config folder (CLAUDE_CONFIG_DIR / CODEX_HOME).
+AGENTS = {
+    "claude": {"label": "Claude Code", "dir": "~/.claude", "env": "CLAUDE_CONFIG_DIR"},
+    "codex": {"label": "Codex", "dir": "~/.codex", "env": "CODEX_HOME"},
+}
+
+
+class ConfigError(Exception):
+    """A one-line, user-facing configuration problem."""
+
+
+@dataclass
+class Host:
+    name: str
+    ssh: Optional[str] = None
+    claude: str = "claude"
+    codex: str = "codex"
+
+    def command(self, agent: str) -> str:
+        """The command (or full path) for an agent on this machine."""
+        return self.codex if agent == "codex" else self.claude
+
+    @property
+    def is_local(self) -> bool:
+        return self.ssh is None
+
+    @property
+    def label(self) -> str:
+        return "this Mac" if self.is_local else str(self.ssh)
+
+
+@dataclass
+class Account:
+    name: str
+    config_dir: str = DEFAULT_CONFIG_DIR
+    env: Dict[str, str] = field(default_factory=dict)
+    agent: str = "claude"
+
+    @property
+    def default_dir(self) -> str:
+        return AGENTS[self.agent]["dir"]
+
+    @property
+    def dir_env(self) -> str:
+        """The variable that points the agent at this account's folder."""
+        return AGENTS[self.agent]["env"]
+
+    @property
+    def agent_label(self) -> str:
+        return AGENTS[self.agent]["label"]
+
+    @property
+    def is_default_dir(self) -> bool:
+        """True for the agent's default folder, however it is written (on this machine)."""
+        d = self.config_dir.rstrip("/")
+        if d == self.default_dir:
+            return True
+        return os.path.expanduser(d) == os.path.expanduser(self.default_dir)
+
+
+@dataclass
+class SessionDef:
+    name: str
+    host: str
+    dir: str
+    account: str
+    note: str = ""
+    args: str = ""
+
+
+@dataclass
+class Notify:
+    on_waiting: bool = True
+    on_done: bool = True
+    sound: str = "Glass"
+
+
+@dataclass
+class Config:
+    hosts: Dict[str, Host]
+    accounts: Dict[str, Account]
+    sessions: List[SessionDef]
+    notify: Notify = field(default_factory=Notify)
+    refresh: float = 3
+    detach_key: str = "C-q"
+    path: Optional[Path] = None
+
+    def session(self, name: str) -> SessionDef:
+        for s in self.sessions:
+            if s.name == name:
+                return s
+        raise ConfigError(f"no session named '{name}' in the config")
+
+    def host_of(self, s: SessionDef) -> Host:
+        return self.hosts[s.host]
+
+    def account_of(self, s: SessionDef) -> Account:
+        return self.accounts[s.account]
+
+    def used_hosts(self) -> List[Host]:
+        """Hosts that have at least one session, in config order."""
+        seen: List[str] = []
+        for s in self.sessions:
+            if s.host not in seen:
+                seen.append(s.host)
+        return [self.hosts[h] for h in seen]
+
+    def accounts_on(self, host: str) -> List[Account]:
+        seen: List[str] = []
+        for s in self.sessions:
+            if s.host == host and s.account not in seen:
+                seen.append(s.account)
+        return [self.accounts[a] for a in seen]
+
+
+def config_path() -> Path:
+    env = os.environ.get("DEROT_CONFIG")
+    if env:
+        return Path(env).expanduser()
+    return Path("~/.config/derot/config.yaml").expanduser()
+
+
+def example_text() -> str:
+    return (Path(__file__).parent / "example_config.yaml").read_text()
+
+
+def ensure_config(path: Optional[Path] = None) -> bool:
+    """Write the example config if missing. Returns True if it was created."""
+    path = path or config_path()
+    if path.exists():
+        return False
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(example_text())
+    os.chmod(path, 0o600)
+    return True
+
+
+def norm_path(path: str) -> str:
+    """`$HOME/x` / `${HOME}/x` -> `~/x`: everything downstream expands `~` (shell and
+    Python alike), but a quoted `$HOME` would reach Claude as a literal relative path."""
+    for prefix in ("${HOME}", "$HOME"):
+        if path == prefix or path.startswith(prefix + "/"):
+            return "~" + path[len(prefix):]
+    return path
+
+
+def _mapping(value, where: str) -> dict:
+    if value is None:
+        return {}
+    if not isinstance(value, dict):
+        raise ConfigError(f"{where}: expected a mapping")
+    return value
+
+
+def _str(value, where: str, default: str = "") -> str:
+    if value is None:
+        return default
+    if isinstance(value, (dict, list)):
+        raise ConfigError(f"{where}: expected a string")
+    return str(value)
+
+
+def parse(data, path: Optional[Path] = None) -> Config:
+    data = _mapping(data, "config")
+
+    hosts: Dict[str, Host] = {"local": Host("local")}
+    for name, h in _mapping(data.get("hosts"), "hosts").items():
+        name = str(name)
+        h = _mapping(h, f"host '{name}'")
+        claude = _str(h.get("claude"), f"host '{name}' claude", "claude") or "claude"
+        codex = _str(h.get("codex"), f"host '{name}' codex", "codex") or "codex"
+        if name == "local":
+            hosts["local"] = Host("local", None, claude, codex)
+            continue
+        ssh = _str(h.get("ssh"), f"host '{name}' ssh")
+        if not ssh:
+            raise ConfigError(f"host '{name}': missing 'ssh' (e.g. ssh: user@my-vm)")
+        hosts[name] = Host(name, ssh, claude, codex)
+
+    accounts: Dict[str, Account] = {}
+    for name, a in _mapping(data.get("accounts"), "accounts").items():
+        name = str(name)
+        a = _mapping(a, f"account '{name}'")
+        agent = _str(a.get("agent"), f"account '{name}' agent", "claude") or "claude"
+        if agent not in AGENTS:
+            raise ConfigError(f"account '{name}': unknown agent '{agent}' (use "
+                              + " or ".join(AGENTS) + ")")
+        default = AGENTS[agent]["dir"]
+        cdir = _str(a.get("config_dir"), f"account '{name}' config_dir", default)
+        env = {
+            str(k): _str(v, f"account '{name}' env {k}")
+            for k, v in _mapping(a.get("env"), f"account '{name}' env").items()
+        }
+        accounts[name] = Account(name, norm_path(cdir or default), env, agent)
+    if not accounts:
+        accounts["default"] = Account("default", DEFAULT_CONFIG_DIR)
+
+    raw_sessions = data.get("sessions") or []
+    if not isinstance(raw_sessions, list):
+        raise ConfigError("sessions: expected a list")
+    sessions: List[SessionDef] = []
+    names = set()
+    tmux_keys: Dict[str, str] = {}
+    for i, s in enumerate(raw_sessions):
+        s = _mapping(s, f"session #{i + 1}")
+        name = _str(s.get("name"), f"session #{i + 1} name")
+        label = f"session '{name}'" if name else f"session #{i + 1}"
+        if not name or not NAME_RE.match(name):
+            raise ConfigError(f"{label}: invalid name (use letters, digits, _ . -; not starting with .)")
+        if name in names:
+            raise ConfigError(f"{label}: duplicate session name")
+        clash = tmux_keys.get(name.replace(".", "_"))
+        if clash:  # tmux names write `.` as `_`
+            raise ConfigError(f"{label}: too similar to session '{clash}' (. and _ count "
+                              "as the same in tmux session names)")
+        names.add(name)
+        tmux_keys[name.replace(".", "_")] = name
+        host = _str(s.get("host"), f"{label} host", "local") or "local"
+        if host not in hosts:
+            raise ConfigError(f"{label}: unknown host '{host}'")
+        if len(accounts) == 1 and not s.get("account"):
+            account = next(iter(accounts))
+        else:
+            account = _str(s.get("account"), f"{label} account")
+        if account not in accounts:
+            raise ConfigError(f"{label}: unknown account '{account}'")
+        d = _str(s.get("dir"), f"{label} dir")
+        if not d:
+            raise ConfigError(f"{label}: missing 'dir'")
+        sessions.append(SessionDef(
+            name=name, host=host, dir=norm_path(d), account=account,
+            note=_str(s.get("note"), f"{label} note"),
+            args=_str(s.get("args"), f"{label} args"),
+        ))
+
+    n = _mapping(data.get("notify"), "notify")
+    notify = Notify(
+        on_waiting=bool(n.get("on_waiting", True)),
+        on_done=bool(n.get("on_done", True)),
+        sound=_str(n.get("sound", "Glass"), "notify sound"),
+    )
+
+    try:
+        refresh = float(data.get("refresh", 3))
+    except (TypeError, ValueError):
+        raise ConfigError("refresh: expected a number of seconds")
+    if not 0 < refresh <= 3600:  # also rejects .inf and .nan
+        raise ConfigError("refresh: expected a number of seconds between 1 and 3600")
+    refresh = max(1.0, refresh)
+    detach_key = _str(data.get("detach_key"), "detach_key", "C-q") or "C-q"
+
+    return Config(hosts, accounts, sessions, notify, refresh, detach_key, path)
+
+
+SAVED_HEADER = """\
+# derot configuration (edited from the derot console; comments are not kept).
+# Hosts: machines ("local" is this computer). Accounts: Claude Code or Codex folders.
+# Sessions: a project folder + machine + account. See the README for every option.
+"""
+
+
+def to_dict(cfg: Config) -> dict:
+    """The YAML-ready form of cfg, leaving out values that are at their defaults."""
+    hosts: dict = {}
+    for h in cfg.hosts.values():
+        entry: dict = {}
+        if not h.is_local:
+            entry["ssh"] = h.ssh
+        if h.claude != "claude":
+            entry["claude"] = h.claude
+        if h.codex != "codex":
+            entry["codex"] = h.codex
+        if entry or not h.is_local:
+            hosts[h.name] = entry
+    accounts: dict = {}
+    for a in cfg.accounts.values():
+        entry = {"config_dir": a.config_dir}
+        if a.agent != "claude":
+            entry = {"agent": a.agent, **entry}
+        if a.env:
+            entry["env"] = dict(a.env)
+        accounts[a.name] = entry
+    sessions = []
+    for s in cfg.sessions:
+        entry = {"name": s.name, "host": s.host, "dir": s.dir, "account": s.account}
+        if s.note:
+            entry["note"] = s.note
+        if s.args:
+            entry["args"] = s.args
+        sessions.append(entry)
+    data: dict = {}
+    if hosts:
+        data["hosts"] = hosts
+    data["accounts"] = accounts
+    data["sessions"] = sessions
+    data["notify"] = {"on_waiting": cfg.notify.on_waiting, "on_done": cfg.notify.on_done,
+                      "sound": cfg.notify.sound}
+    data["refresh"] = int(cfg.refresh) if cfg.refresh == int(cfg.refresh) else cfg.refresh
+    data["detach_key"] = cfg.detach_key
+    return data
+
+
+def save(cfg: Config, path: Optional[Path] = None) -> Config:
+    """Validate and write cfg. Keeps a one-time backup of the hand-written file."""
+    path = path or cfg.path or config_path()
+    data = to_dict(cfg)
+    checked = parse(data, path)  # raises ConfigError if the change made it invalid
+    path.parent.mkdir(parents=True, exist_ok=True)
+    backup = path.with_name(path.name + ".bak")
+    if path.exists() and not backup.exists():
+        backup.write_text(path.read_text())
+    tmp = path.with_name(f".{path.name}.tmp")
+    text = SAVED_HEADER + "\n" + yaml.safe_dump(
+        data, sort_keys=False, allow_unicode=True, default_flow_style=False)
+    # 0600: the config can hold API keys (account env)
+    fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w") as f:
+        f.write(text)
+    os.chmod(tmp, 0o600)
+    os.replace(tmp, path)
+    if backup.exists():
+        os.chmod(backup, 0o600)
+    log.info("saved config %s (%d sessions, accounts: %s, hosts: %s)", path,
+             len(checked.sessions), ", ".join(checked.accounts), ", ".join(checked.hosts))
+    return checked
+
+
+def load(path: Optional[Path] = None) -> Config:
+    path = path or config_path()
+    try:
+        text = path.read_text()
+    except FileNotFoundError:
+        raise ConfigError(f"config not found: {path} (run `derot init`)")
+    try:
+        data = yaml.safe_load(text)
+    except yaml.YAMLError as e:
+        mark = getattr(e, "problem_mark", None)
+        where = f" at line {mark.line + 1}" if mark else ""
+        problem = getattr(e, "problem", None) or "parse error"
+        raise ConfigError(f"invalid YAML in {path}{where}: {problem}")
+    return parse(data, path)

derot/example_config.yaml

@@ -0,0 +1,43 @@
+# derot configuration
+# Docs: run `derot --help`, or see the README.
+
+# Machines. "local" (this computer) always exists; add VMs reachable over SSH.
+hosts:
+  local:
+    claude: claude             # command or full path for Claude Code on this machine
+    codex: codex               # command or full path for Codex on this machine
+  # vm:
+  #   ssh: user@my-vm          # anything `ssh` accepts, incl. ~/.ssh/config aliases
+  #   claude: claude           # optional override
+
+# Accounts. Each account is an agent's config folder with its own login: Claude Code
+# (agent: claude, the default; CLAUDE_CONFIG_DIR) or Codex (agent: codex; CODEX_HOME).
+accounts:
+  personal:
+    config_dir: ~/.claude      # Claude Code's default folder
+  # work:
+  #   config_dir: ~/.claude-work
+  #   env:                     # optional extra env vars for this account
+  #     ANTHROPIC_API_KEY: sk-ant-...
+  # openai:
+  #   agent: codex
+  #   config_dir: ~/.codex     # Codex's default folder
+  #   env:
+  #     OPENAI_API_KEY: sk-... # optional; otherwise log in with `l` (codex login)
+
+# Sessions to manage. Each one runs in its own tmux session on its host.
+sessions: []
+  # - name: shop-api           # letters, digits, _ . - ; must be unique
+  #   host: local              # "local" or a key of hosts
+  #   dir: ~/code/shop-api     # project folder on that host (~ allowed)
+  #   account: personal        # key of accounts
+  #   note: payments refactor  # optional reminder shown in the UI
+  #   args: ""                 # optional extra flags for `claude` / `codex`
+
+notify:
+  on_waiting: true             # alert when a session needs approval/input
+  on_done: true                # alert when a session finishes
+  sound: Glass                 # macOS sound name, "" = silent
+
+refresh: 3                     # poll interval in seconds (min 1)
+detach_key: C-q                # key that returns to derot from a session