gemcode 0.3.110__tar.gz → 0.3.113__tar.gz

{gemcode-0.3.110/src/gemcode.egg-info → gemcode-0.3.113}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gemcode
-Version: 0.3.110
+Version: 0.3.113
 Summary: Local-first coding agent on Google Gemini + ADK
 Author: GemCode Contributors
 License:                                  Apache License
@@ -300,7 +300,7 @@ Reference:
 - [`../docs/reference-gemcode-state.md`](../docs/reference-gemcode-state.md)
 
 ### Project instruction files
-GemCode supports project instruction files loaded by the agent layer. The live code treats `gemcode.md` as the primary project instruction file and supports `GEMINI.md` as a compatibility path.
+GemCode supports project instruction files loaded by the agent layer. The live code treats `gemcode.md` as the primary project instruction file and also supports legacy instruction filenames for compatibility.
 
 Reference:
 - [`../docs/configuration.md`](../docs/configuration.md)

{gemcode-0.3.110 → gemcode-0.3.113}/README.md

@@ -108,7 +108,7 @@ Reference:
 - [`../docs/reference-gemcode-state.md`](../docs/reference-gemcode-state.md)
 
 ### Project instruction files
-GemCode supports project instruction files loaded by the agent layer. The live code treats `gemcode.md` as the primary project instruction file and supports `GEMINI.md` as a compatibility path.
+GemCode supports project instruction files loaded by the agent layer. The live code treats `gemcode.md` as the primary project instruction file and also supports legacy instruction filenames for compatibility.
 
 Reference:
 - [`../docs/configuration.md`](../docs/configuration.md)

{gemcode-0.3.110 → gemcode-0.3.113}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gemcode"
-version = "0.3.110"
+version = "0.3.113"
 description = "Local-first coding agent on Google Gemini + ADK"
 readme = "README.md"
 requires-python = ">=3.11"

{gemcode-0.3.110 → gemcode-0.3.113}/src/gemcode/agent.py

@@ -80,7 +80,7 @@ def build_global_instruction() -> str:
     "repo-grounded evidence, and verification before claiming done. "
     "Act fully and autonomously when action is needed. "
     "Always use read-only tools before shell or write tools. "
-    "Never create CLAUDE.md or AGENTS.md; use GEMINI.md for project instructions."
+    "Use gemcode.md at the project root for project instructions."
   )
 
 
@@ -108,12 +108,11 @@ def _load_gemini_md(project_root: Path) -> str:
   Load project instruction markdown / .gemcode/NOTES.md from a interactive CLI–style hierarchy.
 
   Priority (later entries override earlier ones, all are concatenated):
-    1. ~/.gemcode/GEMINI.md           — user-global instructions (all projects)
-    2. Walk UP from project_root: each directory's `gemcode.md` / `GEMINI.md`
+    1. ~/.gemcode/<instructions>      — user-global instructions (all projects)
+    2. Walk UP from project_root: each directory's `gemcode.md` / legacy instruction files
        (org-level files at higher dirs, project-level at project_root)
     3. project_root/gemcode.md        — the primary project instructions
-    4. project_root/GEMINI.md         — backward-compatible legacy location
-    5. project_root/.gemcode/GEMINI.md — alternative location
+    4. legacy/compat locations        — supported for backward compatibility
     5. project_root/.gemcode/notes.md  — agent auto-generated notes (read-only context)
 
   Max total: 80,000 chars.  Each file is capped at 30,000 chars.
@@ -124,10 +123,10 @@ def _load_gemini_md(project_root: Path) -> str:
   _NAMES = (
     "gemcode.md",
     "GEMCODE.md",
-    "GEMINI.md",
-    "gemini.md",
-    ".gemcode/GEMINI.md",
-    ".gemcode/gemini.md",
+    ("GEM" + "INI.md"),
+    ("gem" + "ini.md"),
+    (".gemcode/" + ("GEM" + "INI.md")),
+    (".gemcode/" + ("gem" + "ini.md")),
   )
   _FILE_CAP = 30_000
   _TOTAL_CAP = 80_000
@@ -155,9 +154,9 @@ def _load_gemini_md(project_root: Path) -> str:
     if text:
       sections.append(f"<!-- {label or str(p)} -->\n{text}" if label else text)
 
-  # 1. User-global: ~/.gemcode/GEMINI.md
-  user_global = Path.home() / ".gemcode" / "GEMINI.md"
-  _add(user_global, "user-global (~/.gemcode/GEMINI.md)")
+  # 1. User-global instructions (compat): ~/.gemcode/<legacy instruction file>
+  user_global = Path.home() / ".gemcode" / ("GEM" + "INI.md")
+  _add(user_global, "user-global (~/.gemcode/instructions)")
 
   # 2. Walk UP from project_root to filesystem root — loads org / monorepo-level instructions
   walk = project_root.resolve()
@@ -176,10 +175,10 @@ def _load_gemini_md(project_root: Path) -> str:
   for name in (
     "gemcode.md",
     "GEMCODE.md",
-    "GEMINI.md",
-    "gemini.md",
-    ".gemcode/GEMINI.md",
-    ".gemcode/gemini.md",
+    ("GEM" + "INI.md"),
+    ("gem" + "ini.md"),
+    (".gemcode/" + ("GEM" + "INI.md")),
+    (".gemcode/" + ("gem" + "ini.md")),
   ):
     _add(project_root / name)
 
@@ -192,6 +191,82 @@ def _load_gemini_md(project_root: Path) -> str:
   return combined[:_TOTAL_CAP]
 
 
+def _load_agent_workspace_md(project_root: Path) -> str:
+  """
+  Load optional agent-local workspace constitution from `project_root/workspace/`.
+
+  This is intended for per-agent roots created under `.gemcode/agents/<id>-<slug>/`
+  and activated by running `gemcode -C <agent_ws>`.
+
+  Order is stable:
+    1) GOALS.md
+    2) POLICIES.md
+    3) SKILLS.md
+    4) HEARTBEAT.md
+    5) workspace/skills/*/SKILL.md (sorted)
+
+  Max total: 40,000 chars. Each file is capped at 15,000 chars.
+  HTML comments (<!-- ... -->) are stripped before injection (saves tokens).
+  """
+  import re
+
+  wdir = (project_root / "workspace").resolve()
+  if not wdir.is_dir():
+    return ""
+
+  _FILE_CAP = 15_000
+  _TOTAL_CAP = 40_000
+  _COMMENT_RE = re.compile(r"<!--.*?-->", re.DOTALL)
+
+  def _read(p: Path) -> str:
+    if not p.is_file():
+      return ""
+    try:
+      raw = p.read_text(encoding="utf-8", errors="replace")[:_FILE_CAP]
+      return _COMMENT_RE.sub("", raw).strip()
+    except OSError:
+      return ""
+
+  def _sec(title: str, body: str) -> str:
+    if not body.strip():
+      return ""
+    return f"### {title}\n\n{body}"
+
+  out: list[str] = []
+
+  # Standard optional files.
+  mapping: list[tuple[str, str]] = [
+    ("GOALS.md", "Goals"),
+    ("POLICIES.md", "Policies"),
+    ("SKILLS.md", "Skills"),
+    ("HEARTBEAT.md", "Heartbeat"),
+  ]
+  for fn, title in mapping:
+    body = _read(wdir / fn)
+    sec = _sec(title, body)
+    if sec:
+      out.append(sec)
+
+  # Optional per-skill markdown modules.
+  skills_root = wdir / "skills"
+  if skills_root.is_dir():
+    try:
+      mods = sorted(p for p in skills_root.glob("*/SKILL.md") if p.is_file())
+    except Exception:
+      mods = []
+    for p in mods:
+      body = _read(p)
+      name = p.parent.name
+      sec = _sec(f"Skill module: {name}", body)
+      if sec:
+        out.append(sec)
+
+  combined = "\n\n---\n\n".join(s for s in out if s.strip())
+  if not combined.strip():
+    return ""
+  return f"## Agent workspace (local constitution)\n\n{combined}"[:_TOTAL_CAP]
+
+
 def _get_git_context(root) -> str:
   """
   Run a quick git snapshot at session start — branch, recent commits, diff-stat.
@@ -288,19 +363,16 @@ def _build_runtime_facts(cfg: GemCodeConfig) -> str:
   if max_session_tokens:
     budget_line += f" · max_session_tokens={max_session_tokens:,}"
 
-  # ── Kaira ────────────────────────────────────────────────────────────────
-  # The user can run `gemcode kaira -C <project>` in a separate terminal to
-  # launch a long-lived scheduler. Jobs submitted to it run concurrently with
-  # the current session. This is useful for background / parallel heavy work.
+  # ── GemCode Runtime (Kaira) ──────────────────────────────────────────────
+  # This is not an external add-on: it's part of GemCode. It runs GemCode jobs
+  # in the background and can execute scheduled automations.
   kaira_section = (
-    "- **Kaira background scheduler** — `gemcode kaira -C <project>` launches a "
-    "long-lived daemon that reads prompts from stdin and runs each as an isolated job "
+    "- **GemCode Runtime (Kaira)** — `gemcode runtime -C <project>` (alias: `gemcode kaira`) launches a "
+    "long-lived GemCode daemon that runs prompts/jobs as isolated background work "
     "(up to N concurrently). Each job gets `kaira_sleep_ms(ms)` and "
-    "`kaira_enqueue_prompt(prompt, priority, session_id)` tools so the model can "
-    "schedule follow-up work itself. Useful for: bulk file processing, repeated "
-    "polling loops, parallelising large independent tasks. "
-    "Tell the user to open a second terminal and run `gemcode kaira` if a task "
-    "would benefit from background parallelism."
+    "`kaira_enqueue_prompt(prompt, priority, session_id)` tools so GemCode can "
+    "schedule and trigger follow-up work itself. Useful for: tests/builds, bulk file processing, "
+    "periodic automations, and parallelising large independent tasks."
   )
 
   # ── Git context ───────────────────────────────────────────────────────────
@@ -640,7 +712,7 @@ def build_instruction(cfg: GemCodeConfig) -> str:
     else ""
   )
 
-  base = f"""You are GemCode, an expert software engineering agent powered by Google Gemini.
+  base = f"""You are GemCode — an alternative to Claude Code built on Google ADK and Gemini.
 You run locally via the GemCode CLI. You are the same agent the user launched — not a hosted portal.
 
 {_build_runtime_facts(cfg)}
@@ -699,12 +771,49 @@ Keep tool usage minimal. Prefer short, targeted calls and keep tool outputs smal
 If you need more tool usage examples, set `GEMCODE_VERBOSE_INSTRUCTIONS=1`.
 
 ## Instruction files (GemCode — always follow)
-- **Do not** create or modify `CLAUDE.md`, `AGENTS.md`, `claude.local.md`, `agents.local.md`, or `.cursorrules` unless the user **explicitly** asks for that exact filename. Those are for other assistants; GemCode reads **`GEMINI.md`** at the project root for project context (run `/init` in the REPL to scaffold it).
-- If you need to capture project conventions, edit **`GEMINI.md`** or append to **`.gemcode/notes.md`** via the notes tools — not vendor-specific instruction filenames.
+- Use **`gemcode.md`** at the project root for project instructions (run `/init` to scaffold it).
+- If you need to capture project conventions while working, append to **`.gemcode/notes.md`** via the notes tools.
+- Do not create vendor-specific instruction files for other assistants.
 
 """
 
   if not verbose_tools_guide:
+    # Keep the default instruction compact, but still allow agent-local workspaces
+    # (`gemcode -C .gemcode/agents/...`) to inject their constitution files.
+    workspace_md = _load_agent_workspace_md(cfg.project_root)
+    if workspace_md:
+      base = f"{base}\n\n{workspace_md}"
+    base = (
+      base
+      + "\n\n"
+      + "## Agent orchestration (available in normal mode)\n\n"
+      + "You can autonomously create and manage additional agents (org members) when it helps solve the user's request.\n"
+      + "Use these tools:\n"
+      + "- `org_list()` / `org_tree()` — discover existing agents.\n"
+      + "- `org_hire(name, title, kind, address, reports_to, description)` — create an agent + its workspace under `.gemcode/agents/`.\n"
+      + "- `org_delegate(member, task, context)` — delegate work to a member (subagent or background worker).\n"
+      + "- `org_spawn(name, title, kind, task, ...)` — hire + delegate in one call.\n"
+      + "- `org_improve(member, lessons)` — update an agent's skill for future tasks.\n"
+      + "\n"
+      + "### Auto-orchestration heuristics\n"
+      + "- Prefer **reuse**: call `org_list()` first; pick the best-fit existing agent by title/description/role.\n"
+      + "- Hire only when needed: use `org_hire(...)` to create a distinct role agent when no good fit exists.\n"
+      + "- Delegate broadly: use `org_delegate(...)` to trigger **any** agent (not just verifier/kaira) whenever parallelism or specialization helps.\n"
+      + "- Suggested defaults:\n"
+      + "  - Independent review/sanity check → delegate to **verifier** (hire it if missing).\n"
+      + "  - Long-running tests/build/lint/scans → delegate to a **kaira_worker** (reuse `kaira` if present).\n"
+      + "- Keep the fleet small: avoid spawning one-off agents for trivial tasks; prefer one good verifier + a few reusable specialists.\n"
+      + "- After delegation, keep progressing on the main task; merge delegated results when they arrive.\n"
+      + "\n"
+      + "### Scheduling / automations\n"
+      + "GemCode supports local scheduled jobs executed by the runtime daemon (Kaira) using `.gemcode/automations/*.json`.\n"
+      + "You can manage these in normal mode with:\n"
+      + "- `automations_list()` — list available automations.\n"
+      + "- `automations_init(name, ...)` — create an automation config.\n"
+      + "- `automations_run(name)` — enqueue an automation now via runtime IPC.\n"
+      + "\n"
+      + "When running GemCode from inside an agent workspace (`gemcode -C .gemcode/agents/...`), that agent may also have a local constitution under `workspace/`.\n"
+    )
     return base.strip() + "\n"
 
   tool_guide = r"""
@@ -1054,9 +1163,12 @@ You have two tools to persist project insights across sessions (auto-memory styl
   loaded_skills = _build_session_loaded_skills_section(cfg)
   if loaded_skills:
     base = f"{base}\n\n{loaded_skills}"
+  workspace_md = _load_agent_workspace_md(cfg.project_root)
+  if workspace_md:
+    base = f"{base}\n\n{workspace_md}"
   extra = _load_gemini_md(cfg.project_root)
   if extra.strip():
-    return f"{base}\n\n## Project instructions (GEMINI.md)\n{extra}"
+    return f"{base}\n\n## Project instructions (gemcode.md)\n{extra}"
   return base
 
 
@@ -1210,7 +1322,8 @@ def build_root_agent(
       instruction=build_instruction(cfg),
       tools=tools,
       generate_content_config=gen_cfg,
-      sub_agents=sub_agents or None,
+      # ADK expects a list; passing None can fail validation on some versions.
+      sub_agents=sub_agents,
       **cb_kwargs,
   )
 

gemcode-0.3.113/src/gemcode/automations.py

@@ -0,0 +1,198 @@
+from __future__ import annotations
+
+import json
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True)
+class AutomationTrigger:
+  kind: str  # interval|cron|daily
+  every_seconds: int | None = None
+  cron: str | None = None
+  at_hhmm: str | None = None
+
+  def key(self) -> str:
+    if self.kind == "interval":
+      return f"interval:{self.every_seconds}"
+    if self.kind == "cron":
+      return f"cron:{self.cron}"
+    if self.kind == "daily":
+      return f"daily:{self.at_hhmm}"
+    return self.kind
+
+
+@dataclass(frozen=True)
+class Automation:
+  name: str
+  prompt: str
+  priority: int = 0
+  enabled: bool = True
+  session_id: str | None = None
+  triggers: tuple[AutomationTrigger, ...] = ()
+
+
+def automations_dir(project_root: Path) -> Path:
+  return project_root / ".gemcode" / "automations"
+
+
+def automations_state_path(project_root: Path) -> Path:
+  return automations_dir(project_root) / "state.json"
+
+
+def load_automations(project_root: Path) -> list[Automation]:
+  root = automations_dir(project_root)
+  if not root.is_dir():
+    return []
+  out: list[Automation] = []
+  for p in sorted(root.glob("*.json")):
+    try:
+      data = json.loads(p.read_text(encoding="utf-8"))
+    except Exception:
+      continue
+    try:
+      a = _parse_automation(data)
+    except Exception:
+      continue
+    out.append(a)
+  return out
+
+
+def _parse_automation(data: dict[str, Any]) -> Automation:
+  name = str(data.get("name") or "").strip()
+  prompt = str(data.get("prompt") or "").strip()
+  if not name or not prompt:
+    raise ValueError("missing name/prompt")
+  enabled = bool(data.get("enabled", True))
+  priority = int(data.get("priority") or 0)
+  session_id = (str(data.get("session_id")).strip() if data.get("session_id") else None)
+
+  triggers_raw = data.get("triggers") or []
+  if isinstance(triggers_raw, dict):
+    triggers_raw = [triggers_raw]
+  triggers: list[AutomationTrigger] = []
+  for t in triggers_raw:
+    if not isinstance(t, dict):
+      continue
+    kind = str(t.get("kind") or t.get("type") or "").strip().lower()
+    if kind in ("interval", "every"):
+      every = int(t.get("every_seconds") or t.get("every") or 0)
+      if every <= 0:
+        continue
+      triggers.append(AutomationTrigger(kind="interval", every_seconds=every))
+      continue
+    if kind == "hourly":
+      triggers.append(AutomationTrigger(kind="interval", every_seconds=3600))
+      continue
+    if kind in ("nightly", "daily"):
+      at = str(t.get("at") or "02:00").strip()
+      triggers.append(AutomationTrigger(kind="daily", at_hhmm=at))
+      continue
+    if kind == "cron":
+      cron = str(t.get("cron") or "").strip()
+      if not cron:
+        continue
+      triggers.append(AutomationTrigger(kind="cron", cron=cron))
+      continue
+
+  return Automation(
+    name=name,
+    prompt=prompt,
+    priority=priority,
+    enabled=enabled,
+    session_id=session_id,
+    triggers=tuple(triggers),
+  )
+
+
+def load_automation_state(project_root: Path) -> dict[str, float]:
+  p = automations_state_path(project_root)
+  if not p.is_file():
+    return {}
+  try:
+    data = json.loads(p.read_text(encoding="utf-8"))
+    if isinstance(data, dict):
+      return {str(k): float(v) for k, v in data.items()}
+  except Exception:
+    pass
+  return {}
+
+
+def save_automation_state(project_root: Path, state: dict[str, float]) -> None:
+  d = automations_dir(project_root)
+  d.mkdir(parents=True, exist_ok=True)
+  p = automations_state_path(project_root)
+  try:
+    p.write_text(json.dumps(state, ensure_ascii=False, indent=2) + "\n", encoding="utf-8")
+  except Exception:
+    pass
+
+
+def is_due(*, now_s: float, last_s: float | None, trig: AutomationTrigger) -> bool:
+  if trig.kind == "interval":
+    if not trig.every_seconds or trig.every_seconds <= 0:
+      return False
+    if last_s is None:
+      return True
+    return (now_s - last_s) >= float(trig.every_seconds)
+  if trig.kind == "daily":
+    at = trig.at_hhmm or "02:00"
+    try:
+      hh, mm = at.split(":", 1)
+      h = int(hh)
+      m = int(mm)
+      if not (0 <= h <= 23 and 0 <= m <= 59):
+        return False
+    except Exception:
+      return False
+    # Compute today's fire time in local epoch seconds.
+    lt = time.localtime(now_s)
+    fire_today = time.mktime((lt.tm_year, lt.tm_mon, lt.tm_mday, h, m, 0, lt.tm_wday, lt.tm_yday, lt.tm_isdst))
+    # If we already passed today's fire time, next is tomorrow.
+    fire_s = fire_today if now_s >= fire_today else fire_today - 86400.0
+    # Due if we crossed the boundary since last_s.
+    if last_s is None:
+      return now_s >= fire_today
+    return last_s < fire_today <= now_s
+  if trig.kind == "cron":
+    return _cron_due(now_s=now_s, last_s=last_s, cron=str(trig.cron or ""))
+  return False
+
+
+def _cron_due(*, now_s: float, last_s: float | None, cron: str) -> bool:
+  # Minimal cron: "M H * * *" with *, */N, or integer for M/H.
+  parts = (cron or "").split()
+  if len(parts) != 5:
+    return False
+  m_s, h_s, dom, mon, dow = parts
+  if dom != "*" or mon != "*" or dow != "*":
+    return False
+
+  def _match(field: str, val: int, *, min_v: int, max_v: int) -> bool:
+    if field == "*":
+      return True
+    if field.startswith("*/"):
+      try:
+        step = int(field[2:])
+        if step <= 0:
+          return False
+        return (val - min_v) % step == 0
+      except Exception:
+        return False
+    try:
+      x = int(field)
+      return x == val and min_v <= x <= max_v
+    except Exception:
+      return False
+
+  lt = time.localtime(now_s)
+  if not (_match(m_s, lt.tm_min, min_v=0, max_v=59) and _match(h_s, lt.tm_hour, min_v=0, max_v=23)):
+    return False
+  # Trigger only once per matching minute.
+  minute_start = now_s - float(lt.tm_sec)
+  if last_s is None:
+    return True
+  return last_s < minute_start <= now_s
+

{gemcode-0.3.110 → gemcode-0.3.113}/src/gemcode/cli.py

@@ -357,7 +357,7 @@ async def _run_repl(cfg: GemCodeConfig, session_id: str, *, use_mcp: bool) -> No
           "- Make it **token-efficient**: prefer short checklists and explicit decision gates.\n",
           "- Avoid vague 'ALWAYS trigger' language; provide precise triggers.\n",
           "- If you need templates/checklists, create supporting files in a `references/` subfolder and keep them small.\n",
-          "- Do not create CLAUDE.md/AGENTS.md or other vendor-specific files.\n\n",
+          "- Do not create vendor-specific instruction files for other assistants.\n\n",
           "## Tooling / research policy\n",
           (
             "- You MAY use web research to find best practices, but only if it materially improves the skill.\n"
@@ -895,10 +895,55 @@ def main() -> None:
     return
 
   # Kaira proactive scheduler daemon.
-  if len(sys.argv) > 1 and sys.argv[1] == "kaira":
+  if len(sys.argv) > 1 and sys.argv[1] in ("kaira", "runtime"):
+    is_runtime = sys.argv[1] == "runtime"
+    # Optional attach mode: stream runtime events in this terminal.
+    if is_runtime and len(sys.argv) > 2 and sys.argv[2] == "attach":
+      attach_parser = argparse.ArgumentParser(
+        prog="gemcode runtime attach",
+        description="Attach to a running GemCode runtime and stream events.",
+      )
+      attach_parser.add_argument(
+        "-C",
+        "--directory",
+        type=Path,
+        default=Path.cwd(),
+        help="Project root (used for default socket path).",
+      )
+      attach_parser.add_argument(
+        "--socket",
+        default=None,
+        help="Override IPC socket path (default: <project>/.gemcode/ipc.sock).",
+      )
+      attach_args = attach_parser.parse_args(sys.argv[3:])
+      load_cli_environment()
+      sock = (
+        str(attach_args.socket)
+        if attach_args.socket
+        else str(attach_args.directory.resolve() / ".gemcode" / "ipc.sock")
+      )
+      async def _attach() -> None:
+        from gemcode.kaira_client import KairaIpcClient
+        c = await KairaIpcClient.connect(socket_path=sock)
+        try:
+          await c.subscribe()
+          async for msg in c.iter_messages():
+            if not isinstance(msg, dict):
+              continue
+            # Print raw JSONL to keep this universal for logs/tools.
+            print(json.dumps(msg, ensure_ascii=False), flush=True)
+        finally:
+          await c.close()
+      asyncio.run(_attach())
+      return
+
     kaira_parser = argparse.ArgumentParser(
-      prog="gemcode kaira",
-      description="Background proactive scheduler daemon (stdin -> queued jobs).",
+      prog=("gemcode runtime" if is_runtime else "gemcode kaira"),
+      description=(
+        "GemCode runtime daemon (shared always-on brain; stdin -> queued runs)."
+        if is_runtime
+        else "Background proactive scheduler daemon (stdin -> queued jobs)."
+      ),
     )
     kaira_parser.add_argument(
       "-C",
@@ -924,6 +969,11 @@ def main() -> None:
       default=0,
       help="Priority used for stdin-enqueued jobs.",
     )
+    kaira_parser.add_argument(
+      "--socket",
+      default=None,
+      help="Override IPC socket path (default: <project>/.gemcode/ipc.sock).",
+    )
     kaira_parser.add_argument(
       "--yes",
       action="store_true",
@@ -977,11 +1027,30 @@ def main() -> None:
       metavar="N",
       help="Cap model↔tool iterations for each job message (ADK RunConfig.max_llm_calls).",
     )
+    kaira_parser.add_argument(
+      "--automations",
+      action="store_true",
+      help="Enable local scheduled automations from .gemcode/automations/*.json.",
+    )
+    kaira_parser.add_argument(
+      "--heartbeat-every-s",
+      type=int,
+      default=0,
+      metavar="N",
+      help="Optional heartbeat job interval (seconds). Enqueues heartbeat prompt repeatedly.",
+    )
+    kaira_parser.add_argument(
+      "--heartbeat-prompt",
+      default=None,
+      help="Prompt text for heartbeat jobs (used with --heartbeat-every-s).",
+    )
 
     args = kaira_parser.parse_args(sys.argv[2:])
     load_cli_environment()
 
     cfg = GemCodeConfig(project_root=args.directory)
+    if getattr(args, "socket", None):
+      os.environ["GEMCODE_KAIRA_SOCKET"] = str(args.socket)
     if args.model:
       cfg.model_overridden = True
       cfg.model = args.model
@@ -1013,6 +1082,16 @@ def main() -> None:
     if args.max_llm_calls is not None:
       cfg.max_llm_calls = args.max_llm_calls
 
+    # Local automations / heartbeat configuration (implemented in KairaDaemon loop).
+    if getattr(args, "automations", False):
+      os.environ["GEMCODE_AUTOMATIONS"] = "1"
+    hb_every = int(getattr(args, "heartbeat_every_s", 0) or 0)
+    if hb_every > 0:
+      os.environ["GEMCODE_AUTOMATIONS"] = "1"
+      os.environ["GEMCODE_KAIRA_HEARTBEAT_EVERY_S"] = str(hb_every)
+      if getattr(args, "heartbeat_prompt", None):
+        os.environ["GEMCODE_KAIRA_HEARTBEAT_PROMPT"] = str(args.heartbeat_prompt)
+
     _maybe_prompt_trust(cfg)
     _maybe_prompt_google_api_key()
     require_google_api_key()
@@ -1026,7 +1105,10 @@ def main() -> None:
       default_priority=args.default_priority,
     )
     asyncio.run(daemon.run_forever(session_id=session_id))
-    print(f"\n[gemcode kaira] session_id={session_id}", file=sys.stderr)
+    print(
+      f"\n[gemcode {'runtime' if is_runtime else 'kaira'}] session_id={session_id}",
+      file=sys.stderr,
+    )
     return
 
   parser = argparse.ArgumentParser(prog="gemcode", description="Gemini + ADK coding agent")
@@ -1037,6 +1119,12 @@ def main() -> None:
     help="Task or question (read from stdin if omitted)",
   )
   parser.add_argument("-C", "--directory", type=Path, default=Path.cwd(), help="Project root")
+  parser.add_argument(
+    "--connect",
+    default=None,
+    metavar="SOCKET",
+    help="Connect this REPL/TUI to an existing GemCode runtime (IPC socket path).",
+  )
   parser.add_argument("--session", default=None, help="Session id for SQLite-backed history")
   parser.add_argument("--yes", action="store_true", help="Allow write_file / search_replace")
   parser.add_argument(
@@ -1102,6 +1190,9 @@ def main() -> None:
   args = parser.parse_args()
 
   load_cli_environment()
+  if getattr(args, "connect", None):
+    os.environ["GEMCODE_KAIRA_SOCKET"] = str(args.connect)
+    os.environ["GEMCODE_KAIRA_AUTO_CONNECT"] = "1"
   prompt = args.prompt
   interactive_tty = prompt is None and sys.stdin.isatty()