gemcode 0.3.78__py3-none-any.whl → 0.3.81__py3-none-any.whl

gemcode/agent.py

@@ -77,7 +77,8 @@ def build_global_instruction() -> str:
     "Think deeply about what the person actually wants before you do anything. "
     "Use exactly as many tools as the task genuinely requires — no more. "
     "Act fully and autonomously when action is needed. "
-    "Always use read-only tools before shell or write tools."
+    "Always use read-only tools before shell or write tools. "
+    "Never create CLAUDE.md or AGENTS.md; use GEMINI.md for project instructions."
   )
 
 
@@ -580,6 +581,10 @@ You have native deep thinking capability — use it actively:
 Keep tool usage minimal. Prefer short, targeted calls and keep tool outputs small.
 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.
+
 """
 
   if not verbose_tools_guide:
@@ -895,10 +900,6 @@ You have two tools to persist project insights across sessions (auto-memory styl
   Notes are loaded at session start so future sessions inherit this knowledge.
 
 - **`read_project_notes()`** — read current notes **only when starting a real engineering task** (editing, debugging, building). Do NOT call this for greetings or general questions. If notes exist and you're about to work on a task, read them once to avoid re-discovering known information.
-
-## Do not create vendor-specific instruction files
-- Do NOT create or modify `CLAUDE.md` or `AGENTS.md`. GemCode does not use these.
-- If project instructions are needed and the user asked for it, use `GEMINI.md` (repo root).
 """
 
   # Inject capability-specific strategy sections only when those caps are on.

gemcode/cli.py

@@ -147,7 +147,12 @@ def _initialize_gemcode_project(cfg: GemCodeConfig) -> None:
 
 
 async def _run_prompt(
-  cfg: GemCodeConfig, prompt: str, session_id: str, *, use_mcp: bool
+  cfg: GemCodeConfig,
+  prompt: str,
+  session_id: str,
+  *,
+  use_mcp: bool,
+  attachment_paths: list[Path] | None = None,
 ) -> str:
   load_cli_environment()
   _maybe_prompt_trust(cfg)
@@ -164,6 +169,7 @@ async def _run_prompt(
         prompt=prompt,
         max_llm_calls=cfg.max_llm_calls,
         cfg=cfg,
+        attachment_paths=attachment_paths,
     )
     return _events_to_text(collected)
   finally:
@@ -296,6 +302,8 @@ async def _run_repl(cfg: GemCodeConfig, session_id: str, *, use_mcp: bool) -> No
 
       apply_capability_routing(cfg, prompt_text, context="prompt")
       cfg.model = pick_effective_model(cfg, prompt_text)
+      _repl_attach = list(cfg.pending_attachment_paths)
+      cfg.pending_attachment_paths.clear()
       collected = await run_turn(
         runner,
         user_id="local",
@@ -303,6 +311,7 @@ async def _run_repl(cfg: GemCodeConfig, session_id: str, *, use_mcp: bool) -> No
         prompt=prompt_text,
         max_llm_calls=cfg.max_llm_calls,
         cfg=cfg,
+        attachment_paths=_repl_attach if _repl_attach else None,
       )
       out = _events_to_text(collected)
       if out:
@@ -795,6 +804,17 @@ def main() -> None:
       metavar="N",
       help="Cap model↔tool iterations for this message (maps to ADK RunConfig.max_llm_calls)",
   )
+  parser.add_argument(
+      "--attach",
+      "--image",
+      dest="attachments",
+      action="append",
+      default=[],
+      metavar="PATH",
+      help="Attach file(s) for this message (repeatable): images, PDF, audio, video, text, etc. "
+      "(Gemini-supported MIME). Default max ~20 MiB each (GEMCODE_MAX_ATTACHMENT_BYTES). "
+      "REPL: /attach or /image <path>.",
+  )
   args = parser.parse_args()
 
   load_cli_environment()
@@ -846,7 +866,16 @@ def main() -> None:
   prompt_text = prompt.strip()
   apply_capability_routing(cfg, prompt_text, context="prompt")
   cfg.model = pick_effective_model(cfg, prompt_text)
-  out = asyncio.run(_run_prompt(cfg, prompt_text, session_id, use_mcp=args.mcp))
+  _cli_attach = list(args.attachments) if getattr(args, "attachments", None) else []
+  out = asyncio.run(
+      _run_prompt(
+          cfg,
+          prompt_text,
+          session_id,
+          use_mcp=args.mcp,
+          attachment_paths=_cli_attach if _cli_attach else None,
+      )
+  )
   if out:
     print(out)
   print(f"\n[gemcode] session_id={session_id}", file=sys.stderr)

gemcode/config.py

@@ -218,6 +218,9 @@ class GemCodeConfig:
   # Substitutes ${GEMCODE_SESSION_ID} when expanding loaded skills for prompts.
   session_skill_expand_session_id: str | None = None
 
+  # REPL/TUI: paths queued with /attach (or /image …), sent on the next message then cleared.
+  pending_attachment_paths: list[Path] = field(default_factory=list)
+
   # Modality toggles (tool injection + routing).
   enable_deep_research: bool = field(
     default_factory=lambda: _truthy_env("GEMCODE_ENABLE_DEEP_RESEARCH", default=False)

gemcode/ide_protocol.py

@@ -8,6 +8,14 @@ Design goals:
 - Human-readable JSONL (easy to debug)
 - Streaming (token deltas + progress)
 - Safe editing (engine proposes; IDE applies via WorkspaceEdit)
+
+Attachments on ``action: turn`` may include:
+
+- Textual: ``type: selection`` / ``file`` (appended into the prompt as fenced blocks).
+- Binary / multimodal: ``type: inline`` | ``binary`` | ``blob`` with ``data`` or ``base64``
+  (standard base64), plus optional ``filename`` / ``name`` and ``mimeType`` / ``mime_type``.
+  The engine writes bytes to a temp file and passes them to Gemini as inline parts
+  (same limits as CLI ``--attach``).
 """
 
 from __future__ import annotations

gemcode/ide_stdio.py

@@ -16,8 +16,13 @@ GemCode is responsible for:
 from __future__ import annotations
 
 import asyncio
+import base64
+import binascii
+import mimetypes
 import os
 import sys
+import tempfile
+from pathlib import Path
 from typing import Any
 
 from gemcode.config import GemCodeConfig, load_cli_environment
@@ -38,6 +43,107 @@ def _truthy(v: Any, default: bool = False) -> bool:
   return default
 
 
+def _max_ide_inline_bytes() -> int:
+  raw = os.environ.get("GEMCODE_MAX_ATTACHMENT_BYTES")
+  if raw:
+    try:
+      v = int(raw, 10)
+      if v > 0:
+        return v
+    except ValueError:
+      pass
+  return 20 * 1024 * 1024
+
+
+def _suffix_for_inline_attachment(name: str, mime: str) -> str:
+  p = Path(name or "")
+  if p.suffix and len(p.suffix) <= 12:
+    return p.suffix
+  m = (mime or "").strip().lower().split(";")[0].strip()
+  if m:
+    ext = mimetypes.guess_extension(m, strict=False)
+    if ext == ".jpe":
+      ext = ".jpeg"
+    if ext:
+      return ext
+  return ".bin"
+
+
+def prepare_inline_attachment_paths(
+  attachments: list[Any] | None,
+  *,
+  max_bytes: int | None = None,
+  max_count: int = 16,
+) -> tuple[list[Path], list[str]]:
+  """
+  Materialize IDE ``inline`` / ``binary`` / ``blob`` attachment dicts as temp files.
+
+  Expected keys (camelCase accepted): ``data`` or ``base64``, optional ``name`` /
+  ``filename``, ``mime_type`` / ``mimeType``.
+
+  Returns ``(paths, errors)``. Caller must unlink paths when done.
+  """
+  cap = max_bytes if max_bytes is not None else _max_ide_inline_bytes()
+  max_b64 = int(cap * 4 / 3) + 32
+  paths: list[Path] = []
+  errors: list[str] = []
+  if not attachments:
+    return paths, errors
+
+  for a in attachments:
+    if len(paths) >= max_count:
+      errors.append(f"inline attachments: max {max_count} files")
+      break
+    if not isinstance(a, dict):
+      continue
+    at = str(a.get("type") or "").strip().lower()
+    if at not in ("inline", "binary", "blob"):
+      continue
+    b64 = a.get("data") if isinstance(a.get("data"), str) else None
+    if b64 is None:
+      b64 = a.get("base64") if isinstance(a.get("base64"), str) else None
+    if not b64:
+      errors.append("inline attachment missing base64 data")
+      continue
+    if len(b64) > max_b64:
+      errors.append("inline attachment too large (base64)")
+      continue
+    try:
+      raw = base64.b64decode(b64, validate=True)
+    except (binascii.Error, ValueError) as e:
+      errors.append(f"inline attachment: invalid base64 ({e})")
+      continue
+    if len(raw) > cap:
+      errors.append(f"inline attachment exceeds max {cap} bytes")
+      continue
+    name = str(a.get("name") or a.get("filename") or "attachment")
+    mime = str(a.get("mime_type") or a.get("mimeType") or "")
+    suffix = _suffix_for_inline_attachment(name, mime)
+    try:
+      fd, fspath = tempfile.mkstemp(prefix="gemcode_ide_", suffix=suffix)
+      with os.fdopen(fd, "wb") as f:
+        f.write(raw)
+      paths.append(Path(fspath))
+    except OSError as e:
+      errors.append(f"inline attachment temp file failed: {e}")
+
+  return paths, errors
+
+
+def _textual_attachments_only(attachments: list[dict] | None) -> list[dict]:
+  if not attachments:
+    return []
+  out: list[dict] = []
+  for a in attachments:
+    if not isinstance(a, dict):
+      continue
+    at = str(a.get("type") or "").strip().lower()
+    if at in ("inline", "binary", "blob"):
+      continue
+    out.append(a)
+  return out
+
+
 def _build_prompt(prompt: str, attachments: list[dict] | None) -> str:
   # Keep it simple: attachments are appended as fenced blocks.
   if not attachments:
@@ -47,6 +153,8 @@ def _build_prompt(prompt: str, attachments: list[dict] | None) -> str:
     if not isinstance(a, dict):
       continue
     at = (a.get("type") or "").strip().lower()
+    if at in ("inline", "binary", "blob"):
+      continue
     if at == "selection":
       txt = a.get("text") or ""
       path = a.get("path") or ""
@@ -139,7 +247,6 @@ async def run_stdio_loop() -> int:
       if cfg is None:
         root = msg.get("project_root") or os.getcwd()
         model = msg.get("model") or os.environ.get("GEMCODE_MODEL") or ""
-        from pathlib import Path
         cfg = GemCodeConfig(project_root=Path(str(root)), model=str(model))
         # Attach emitter + proposal mode flags (used by tool wrappers).
         object.__setattr__(cfg, "_ide_emitter", emitter)
@@ -151,7 +258,25 @@ async def run_stdio_loop() -> int:
 
       prompt = str(msg.get("prompt") or "")
       attachments = msg.get("attachments") if isinstance(msg.get("attachments"), list) else None
-      full_prompt = _build_prompt(prompt, attachments)
+      att_dicts = [a for a in (attachments or []) if isinstance(a, dict)]
+      inline_paths, inline_err = prepare_inline_attachment_paths(attachments)
+      if inline_err:
+        for p in inline_paths:
+          try:
+            p.unlink()
+          except OSError:
+            pass
+        emitter.send(
+            make_response(
+                id=req_id,
+                ok=False,
+                error="; ".join(inline_err),
+                session=session_id,
+            )
+        )
+        continue
+
+      full_prompt = _build_prompt(prompt, _textual_attachments_only(att_dicts))
 
       # Per-turn allow flags (the engine still only proposes in IDE mode; the IDE applies).
       allow_write = _truthy(msg.get("allowWrite"), default=False)
@@ -161,14 +286,22 @@ async def run_stdio_loop() -> int:
 
       emitter.send(make_event(event="turn_start", id=req_id, session=session_id))
       try:
-        events = await run_turn(
-          runner,
-          user_id="local",
-          session_id=session_id,
-          prompt=full_prompt,
-          max_llm_calls=cfg.max_llm_calls,
-          cfg=cfg,
-        )
+        try:
+          events = await run_turn(
+              runner,
+              user_id="local",
+              session_id=session_id,
+              prompt=full_prompt,
+              max_llm_calls=cfg.max_llm_calls,
+              cfg=cfg,
+              attachment_paths=inline_paths if inline_paths else None,
+          )
+        finally:
+          for p in inline_paths:
+            try:
+              p.unlink()
+            except OSError:
+              pass
       except Exception as e:
         emitter.send(make_response(id=req_id, ok=False, error=f"{type(e).__name__}: {e}", session=session_id))
         continue

gemcode/invoke.py

@@ -9,8 +9,9 @@ from __future__ import annotations
 import asyncio
 import os
 import sys
-from typing import Any
+from pathlib import Path
 from threading import Lock
+from typing import Any, Sequence
 
 from google.adk.agents.run_config import RunConfig
 from google.adk.runners import Runner
@@ -66,6 +67,7 @@ async def run_turn(
     prompt: str,
     max_llm_calls: int | None = None,
     cfg: "GemCodeConfig | None" = None,
+    attachment_paths: Sequence[Path | str] | None = None,
 ) -> list:
   """Execute one user message; collect all Events (caller aggregates text)."""
   # Dynamic risk score: updated each user message; later refined by tool outcomes.
@@ -86,6 +88,8 @@ async def run_turn(
         risk += 0.2
       if re.search(r"\\b(test|pytest|ci|build|deploy|release)\\b", p, re.I):
         risk += 0.1
+      if attachment_paths:
+        risk = min(1.0, risk + 0.12)
       # Multi-file hints
       if p.count("/") >= 6 or p.count(".py") + p.count(".ts") + p.count(".tsx") >= 3:
         risk += 0.1
@@ -167,10 +171,22 @@ async def run_turn(
 
         state_delta = token_budget_invocation_reset()
 
-      # The first message is plain user text.
-      current_message = types.Content(
-        role="user", parts=[types.Part(text=prompt)]
-      )
+      # First message: optional inline files + text (Gemini multimodal).
+      if attachment_paths:
+        from gemcode.multimodal_input import build_user_content
+
+        root = cfg.project_root if cfg is not None else Path.cwd()
+        current_message, attach_warn = build_user_content(
+            prompt,
+            attachment_paths,
+            project_root=root,
+        )
+        for w in attach_warn:
+          print(f"[gemcode] {w}", file=sys.stderr)
+      else:
+        current_message = types.Content(
+            role="user", parts=[types.Part(text=prompt)]
+        )
 
       async def _await_runner_events(
         *, next_message: types.Content, do_reset: bool

gemcode/multimodal_input.py

@@ -0,0 +1,144 @@
+"""
+Build multimodal user Content (text + inline files) for Gemini.
+
+Paths may be absolute or relative to the current working directory, then project root.
+MIME types are inferred from the filename (``mimetypes``) and optionally from file
+headers (PDF, common images, some audio/video) so PDFs and other Gemini-supported
+types work—not only images.
+"""
+
+from __future__ import annotations
+
+import mimetypes
+import os
+from pathlib import Path
+from typing import Sequence
+
+from google.genai import types
+
+_MAX_ATTACHMENTS = 16
+
+
+def _max_attachment_bytes() -> int:
+  raw = os.environ.get("GEMCODE_MAX_ATTACHMENT_BYTES")
+  if raw:
+    try:
+      v = int(raw, 10)
+      if v > 0:
+        return v
+    except ValueError:
+      pass
+  return 20 * 1024 * 1024
+
+
+def resolve_attachment_path(p: Path | str, *, project_root: Path) -> Path:
+  path = Path(p).expanduser()
+  if path.is_absolute():
+    return path.resolve()
+  cwd_try = (Path.cwd() / path).resolve()
+  if cwd_try.is_file():
+    return cwd_try
+  root_try = (project_root / path).resolve()
+  if root_try.is_file():
+    return root_try
+  return (Path.cwd() / path).resolve()
+
+
+# Backward-compatible name from the images-only era.
+resolve_image_path = resolve_attachment_path
+
+
+def _sniff_mime(head: bytes) -> str | None:
+  if len(head) >= 5 and head[:5] == b"%PDF-":
+    return "application/pdf"
+  if len(head) >= 8 and head[:8] == b"\x89PNG\r\n\x1a\n":
+    return "image/png"
+  if len(head) >= 3 and head[:3] == b"\xff\xd8\xff":
+    return "image/jpeg"
+  if len(head) >= 6 and head[:6] in (b"GIF87a", b"GIF89a"):
+    return "image/gif"
+  if len(head) >= 12 and head[:4] == b"RIFF" and head[8:12] == b"WEBP":
+    return "image/webp"
+  if len(head) >= 2 and head[:2] == b"BM":
+    return "image/bmp"
+  if len(head) >= 12 and head[4:8] == b"ftyp":
+    return "video/mp4"
+  if len(head) >= 4 and head[:4] == b"\x1a\x45\xdf\xa3":
+    return "video/webm"
+  if len(head) >= 4 and head[:4] == b"OggS":
+    return "audio/ogg"
+  if len(head) >= 12 and head[:4] == b"RIFF" and head[8:12] == b"WAVE":
+    return "audio/wav"
+  if len(head) >= 4 and head[:4] == b"fLaC":
+    return "audio/flac"
+  if len(head) >= 3 and head[:3] in (b"ID3", b"\xff\xfb", b"\xff\xf3", b"\xff\xf2"):
+    return "audio/mpeg"
+  return None
+
+
+def _infer_mime(path: Path, data: bytes) -> tuple[str, list[str]]:
+  warnings: list[str] = []
+  head = data[:512]
+  guess, _ = mimetypes.guess_type(path.name, strict=False)
+  sniff = _sniff_mime(head)
+
+  if sniff and (not guess or guess == "application/octet-stream"):
+    return sniff, warnings
+  if guess and guess != "application/octet-stream":
+    return guess, warnings
+  if sniff:
+    return sniff, warnings
+  if guess:
+    return guess, warnings
+  warnings.append(
+      f"could not infer MIME type for {path}; using application/octet-stream "
+      "(Gemini may reject unsupported types)"
+  )
+  return "application/octet-stream", warnings
+
+
+def build_user_content(
+  prompt: str,
+  attachment_paths: Sequence[Path | str] | None,
+  *,
+  project_root: Path,
+) -> tuple[types.Content, list[str]]:
+  """
+  Build ``Content`` with inline file parts first, then the text part.
+
+  Returns ``(content, warnings)`` — warnings are non-fatal skips or hints (stderr them).
+  """
+  warnings: list[str] = []
+  parts: list[types.Part] = []
+  max_b = _max_attachment_bytes()
+  if attachment_paths:
+    for raw in list(attachment_paths)[:_MAX_ATTACHMENTS]:
+      p = resolve_attachment_path(raw, project_root=project_root)
+      if not p.is_file():
+        warnings.append(f"attachment not found: {raw}")
+        continue
+      try:
+        size = p.stat().st_size
+      except OSError as e:
+        warnings.append(f"attachment stat failed {p}: {e}")
+        continue
+      if size > max_b:
+        warnings.append(
+            f"attachment too large ({size} bytes, max {max_b}): {p} "
+            "(set GEMCODE_MAX_ATTACHMENT_BYTES or use a smaller file)"
+        )
+        continue
+      try:
+        data = p.read_bytes()
+      except OSError as e:
+        warnings.append(f"attachment read failed {p}: {e}")
+        continue
+      mime, mw = _infer_mime(p, data)
+      warnings.extend(mw)
+      parts.append(types.Part(inline_data=types.Blob(data=data, mime_type=mime)))
+
+  text = (prompt or "").strip() or (
+      "(User attached file(s) only — describe or analyze them.)" if parts else ""
+  )
+  parts.append(types.Part(text=text))
+  return types.Content(role="user", parts=parts), warnings

gemcode/repl_commands.py

@@ -227,7 +227,11 @@ SLASH_COMMANDS: list[tuple[str, str]] = [
     ("exit",        "Leave the REPL  ·  /quit same"),
     ("help",        "Short help  ·  /? same"),
     ("hooks",       "Post-turn hook configuration"),
+    ("attach",      "Queue file(s) for next message (PDF, images, …)  ·  /image /file /img  ·  list  ·  clear"),
     ("init",        "Generate GEMINI.md project instructions"),
+    ("file",        "Alias of /attach"),
+    ("image",       "Alias of /attach (same queue)"),
+    ("img",         "Alias of /attach"),
     ("kaira",       "Background job scheduler — how to run gemcode kaira"),
     ("limits",      "Execution limits (calls, context, …)"),
     ("live-audio",  "How to run gemcode live-audio  ·  /liveaudio same"),
@@ -320,6 +324,8 @@ def slash_help_lines() -> list[str]:
       "  (CLI) gemcode login   Save or change API key (~/.gemcode/credentials.json)",
       "",
       "  Project setup:",
+      "  /attach <path>        Queue file(s) for the **next** message (PDF, images, …); /attach list|clear",
+      "                        Aliases: /image /img /file",
       "  /trust                Show workspace trust status (file/shell tools)",
       "  /trust on|off         Trust or revoke trust for this project root (~/.gemcode/trust.json)",
       "  /init                 Analyze project structure and generate GEMINI.md",

gemcode/repl_slash.py

@@ -29,6 +29,7 @@ from gemcode.repl_commands import (
   slash_help_lines,
 )
 from gemcode.curated_memory import load_snapshot as _curated_load_snapshot
+from gemcode.multimodal_input import resolve_attachment_path
 from gemcode.slash_commands import parse_slash_command
 from gemcode.skills import discover_skill_metas, expand_skill_text, list_supporting_files, load_skill
 from gemcode.output_styles import discover_output_styles, load_output_style
@@ -87,6 +88,51 @@ async def process_repl_slash(
     out()
     return ReplSlashResult(skip_model_turn=True)
 
+  # ── /attach (queue files for the next user message: PDF, images, audio, …) ─
+  if name in ("attach", "file", "image", "img"):
+    raw_i = (sc.args or "").strip()
+    if not raw_i or raw_i.lower() in ("help", "?"):
+      out("Usage:")
+      out("  /attach <path>   Queue a file for the **next** message (repeat for multiple, max 16).")
+      out("  /attach list     Show queued paths")
+      out("  /attach clear    Clear the queue")
+      out("Aliases: /file, /image, /img — same queue.")
+      out("Types: Gemini-supported MIME (e.g. images, PDF, audio, video, text). Default max ~20 MiB each.")
+      out("CLI:  gemcode -C . --attach ./doc.pdf \"Summarize this\"")
+      out()
+      return ReplSlashResult(skip_model_turn=True)
+    low_i = raw_i.lower()
+    if low_i == "list":
+      pend = cfg.pending_attachment_paths
+      if not pend:
+        out("(no attachments queued)")
+      else:
+        out("Queued for next message:")
+        for i, p in enumerate(pend, 1):
+          out(f"  {i}. {p}")
+      out()
+      return ReplSlashResult(skip_model_turn=True)
+    if low_i == "clear":
+      cfg.pending_attachment_paths.clear()
+      out("Attachment queue cleared.")
+      out()
+      return ReplSlashResult(skip_model_turn=True)
+    resolved = resolve_attachment_path(raw_i, project_root=cfg.project_root)
+    if not resolved.is_file():
+      out(f"Not a file: {raw_i}")
+      out("(Resolved relative to cwd, then project root.)")
+      out()
+      return ReplSlashResult(skip_model_turn=True)
+    if len(cfg.pending_attachment_paths) >= 16:
+      out("Queue full (16 files max). Use /attach clear first.")
+      out()
+      return ReplSlashResult(skip_model_turn=True)
+    cfg.pending_attachment_paths.append(resolved)
+    out(f"Queued: {resolved}")
+    out(f"  ({len(cfg.pending_attachment_paths)} file(s) — send your next message to attach)")
+    out()
+    return ReplSlashResult(skip_model_turn=True)
+
   # ── /skills and /<skill-name> ──────────────────────────────────────────────
   if name in ("skills", "skill"):
     args = (sc.args or "").strip()
@@ -999,6 +1045,8 @@ async def process_repl_slash(
       "3. Look at the source directory structure (src/, lib/, app/, etc.)\n"
       "4. Check for test directories and test runner config\n"
       "5. Look for linting/formatting config files (.eslintrc, .prettierrc, ruff.toml, etc.)\n\n"
+      "Write **only** to `GEMINI.md` at the project root. Do **not** create "
+      "`CLAUDE.md`, `AGENTS.md`, `.cursorrules`, or similar.\n\n"
       "Then write a GEMINI.md file at the project root containing:\n"
       "# Project Name\n"
       "One-sentence description.\n\n"
@@ -1073,6 +1121,8 @@ async def process_repl_slash(
     out(f"project_root:   {cfg.project_root}")
     _lg = getattr(cfg, "session_loaded_skill_names", None) or []
     out(f"loaded_skills:  {', '.join(_lg) if _lg else '(none)'}  (/gemskill)")
+    _pq = getattr(cfg, "pending_attachment_paths", None) or []
+    out(f"queued_attachments: {len(_pq)}  (/attach list)")
     out()
     out("Capabilities:")
     out(f"  deep_research:  {'on  ✓' if cfg.enable_deep_research else 'off'}")
@@ -1178,6 +1228,7 @@ async def process_repl_slash(
     # /clear or /session new — start fresh session
     if name == "clear" or args_lower in ("new", "reset"):
       _clear_session_loaded_skills(cfg)
+      cfg.pending_attachment_paths.clear()
       new_id = str(uuid.uuid4())
       out(f"new session_id: {new_id}")
       out()
@@ -1232,6 +1283,7 @@ async def process_repl_slash(
         out()
         return ReplSlashResult(skip_model_turn=True)
       _clear_session_loaded_skills(cfg)
+      cfg.pending_attachment_paths.clear()
       out(f"Resuming session {found[:8]}…")
       out()
       return ReplSlashResult(

gemcode/tools/edit.py

@@ -23,11 +23,16 @@ def make_edit_tools(cfg: GemCodeConfig):
     except Exception:
       pass
 
-  # Block writes to common non-GemCode agent instruction filenames.
-  _BLOCKED_SPECIAL_FILES = {
-    "claude.md",
-    "agents.md",
-  }
+  # Block writes to common non-GemCode / third-party agent instruction filenames.
+  _BLOCKED_SPECIAL_FILES = frozenset(
+      {
+          "claude.md",
+          "agents.md",
+          "claude.local.md",
+          "agents.local.md",
+          ".cursorrules",
+      }
+  )
 
   def _blocked_special_path(path: str) -> str | None:
     try:

gemcode/tui/scrollback.py

@@ -12,6 +12,8 @@ from rich.console import Console
 from rich.markdown import Markdown as _RichMarkdown
 from rich.padding import Padding as _RichPadding
 
+from gemcode.multimodal_input import build_user_content
+
 from gemcode.capability_routing import apply_capability_routing
 from gemcode.config import load_cli_environment
 from gemcode.model_routing import pick_effective_model
@@ -613,7 +615,18 @@ async def run_gemcode_scrollback_tui(
         from gemcode.session_runtime import create_runner as _create_runner_rt
         runner = _create_runner_rt(cfg, extra_tools=extra_tools)
 
-    current_message = types.Content(role="user", parts=[types.Part(text=prompt)])
+    _attach = list(cfg.pending_attachment_paths)
+    cfg.pending_attachment_paths.clear()
+    if _attach:
+      current_message, _attach_warn = build_user_content(
+          prompt,
+          _attach,
+          project_root=cfg.project_root,
+      )
+      for w in _attach_warn:
+        print(f"[gemcode] {w}", file=sys.stderr)
+    else:
+      current_message = types.Content(role="user", parts=[types.Part(text=prompt)])
     do_reset = True
     def _normalize_ws(s: str) -> str:
       # Gemini can sometimes return identical content for both "thinking" and

{gemcode-0.3.78.dist-info → gemcode-0.3.81.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gemcode
-Version: 0.3.78
+Version: 0.3.81
 Summary: Local-first coding agent on Google Gemini + ADK
 Author: GemCode Contributors
 License:                                  Apache License
@@ -330,6 +330,18 @@ Non-interactive environments (CI, pipes) must set `GOOGLE_API_KEY` explicitly an
 | `gemcode kaira` | Stdin-line → queued jobs scheduler (see [Kaira](#kaira-scheduler)). |
 | `gemcode ide --stdio` | **JSONL IDE protocol** on stdin/stdout for editor extensions (hidden entry; used by VS Code). |
 
+**Files with a prompt (multimodal):** attach one or more files Gemini can read (images, **PDF**, audio, video, plain text, etc.) for that message only:
+
+```bash
+gemcode -C . --attach ./screenshot.png "Why does this UI look wrong?"
+gemcode -C . --attach ./report.pdf "What are the main conclusions?"
+gemcode -C . --image a.png --image b.png "Compare these two layouts"
+```
+
+(`--image` is an alias of `--attach`.)
+
+In the **REPL / TUI**, queue files for the **next** message: `/attach path/to.pdf` (repeat for multiple), then type your question. Use `/attach list`, `/attach clear`. Aliases: `/image`, `/img`, `/file`.
+
 ---
 
 ## Main CLI flags
@@ -349,6 +361,7 @@ Non-interactive environments (CI, pipes) must set `GOOGLE_API_KEY` explicitly an
 | `--tool-combination-mode` | Gemini 3 **tool context circulation**: `deep_research\|always\|never\|auto`. |
 | `--mcp` | Load MCP toolsets from `.gemcode/mcp.json` (requires `pip install -e ".[mcp]"`). |
 | `--max-llm-calls` | Cap model↔tool iterations (`RunConfig.max_llm_calls`). |
+| `--attach PATH` | Attach file(s) for **this** CLI message only (repeat flag). Gemini-supported MIME (e.g. images, PDF, audio, video). Default max ~20 MiB each (`GEMCODE_MAX_ATTACHMENT_BYTES`). Alias: `--image`. |
 
 Kaira and `live-audio` accept overlapping options (project root, `--yes`, research/embeddings, etc.); run `gemcode kaira -h` / `gemcode live-audio -h` for full lists.
 
@@ -460,7 +473,7 @@ Tools are registered in `gemcode/tools/` and exposed to the model as ADK functio
 - **Computer use:** ADK `ComputerUseToolset` + Playwright (separate install and flags).
 - **MCP:** Tools loaded from configured servers.
 
-**Vendor file policy:** Writes to certain vendor-specific instruction filenames (e.g. `CLAUDE.md`, `AGENTS.md`) are blocked; use project conventions like `GEMINI.md` and curated memory files instead.
+**Vendor file policy:** Writes to certain third-party instruction filenames (`CLAUDE.md`, `AGENTS.md`, `*.local` variants, `.cursorrules`, …) are blocked; use `GEMINI.md` and `.gemcode/notes.md` instead. The agent instruction always states this; `write_file` / `search_replace` enforce it.
 
 ---
 
@@ -472,6 +485,7 @@ In interactive mode, lines starting with `/` are **slash commands** (see `repl_c
 
 | Command | Purpose |
 |---------|---------|
+| `/attach <path>`, `/attach list`, `/attach clear` | Queue file(s) for the **next** message (Gemini multimodal). Aliases: **`/image`**, **`/img`**, **`/file`**. |
 | `/trust`, `/trust on`, `/trust off` | Show, grant, or revoke **workspace trust** for the project root (stored in `~/.gemcode/trust.json`; required for file/shell/git tools). |
 | `/init` \| `/init force` | Analyze the repo and generate or overwrite `GEMINI.md`. |
 | `/cost` | Token usage and estimated cost for the session. |

{gemcode-0.3.78.dist-info → gemcode-0.3.81.dist-info}/RECORD

@@ -1,15 +1,15 @@
 gemcode/__init__.py,sha256=l0DCRYqK7KM7Fb7u49fqh-5_SlpeIL7r3LjMeJWMgSg,112
 gemcode/__main__.py,sha256=EX2s1hxq2Yvli_-tnBN3w5Qv4bOjsBBbjyISF0pDIQw,37
-gemcode/agent.py,sha256=_v00pQSOzAI9nyaaKC1wn-aTalD4SV52KDzwlyIHJAo,56867
+gemcode/agent.py,sha256=NB2eP7RV8vNp4flk4P4aB_LIIV8TvZtB7ZEXA4O3h-Q,57262
 gemcode/audit.py,sha256=bh9uhXaeh8wqxqoZtz3ZAowd8Ndk1ss-mw9993Vlrgo,469
 gemcode/autocompact.py,sha256=OE3QbGx2gWN2WVXy28Sd0xyfAJgVR1x6ml9HrX2CB7I,6719
 gemcode/autotune.py,sha256=zcTGDKC8LSnw0fHuoOcnnh1rz0by8K6MTUKl0_GhT9s,2704
 gemcode/callbacks.py,sha256=QR98bz-FeK2kp9N9JdzaeHRD2Ga2_rgz0XAPiYFafU0,31038
 gemcode/capability_routing.py,sha256=ZScRb2Bn41ZJUEmw_QaYYDVUPaNnbGBbK216tm5G4mI,3456
 gemcode/checkpoints.py,sha256=ptz2YW7P56mkqOrAf7-MXA0_Op3y4fgAg5ly_etuKvw,3936
-gemcode/cli.py,sha256=2R5pvpx3T8sUnfgbBRmkFjv5-uxCPeo_HuXMsaz23s8,28429
+gemcode/cli.py,sha256=DX8Y2TaZA3Xjv3Pw5EEfexCufnFvGTnJ_DlAHDJoByo,29281
 gemcode/compaction.py,sha256=9YtA_qa23_8dHWVHx7AJwUduuI7jJQtq-m6sT8jgPWI,1186
-gemcode/config.py,sha256=OTJrLFIX-sr6kMWVI4l8rM2kJqkt3X2NcNFBEg6Nfdg,18042
+gemcode/config.py,sha256=Nmq0ClbebkbqfCPZOw8ETGjpjHuGCtByzpEMU1V5Wvg,18208
 gemcode/context_budget.py,sha256=nctVwzpUg6kyBL0FHM7xcrvVvZpX9qj7cZK4IczfKAg,10534
 gemcode/context_warning.py,sha256=YwkkNx6AM2ugOckg8QhRWYcU6D3UJXUOHiBwjKQT2rs,4199
 gemcode/credentials.py,sha256=o1gQ4oQXAjjA1IANXgCalM3WjTkfVkbkXsf-lNVQ55I,1300
@@ -17,11 +17,11 @@ gemcode/curated_memory.py,sha256=5GfMS7JgSfEkAgnjFQle1Zy4VpoyKXI0osifnhMhZv8,321
 gemcode/dynamic_policy.py,sha256=nWgBN6ffSn1Te4aDI1MURxRaQjTclzIuSf4KaAskE9U,4662
 gemcode/hitl_session.py,sha256=oNiI7odFJGUcmqPavjKLJOEumZKrgklLvwjjrIG9GPg,281
 gemcode/hooks.py,sha256=tAzzZgfALC-nqSGoUdnEvHyGJNM2iTqKN5Yrfm8wFo8,6350
-gemcode/ide_protocol.py,sha256=CDcrbB7u35-O_K7wgcGn2lPhL0GtSi22IxJk8CsmJPY,1669
-gemcode/ide_stdio.py,sha256=4Z5e8t3mKAiltQ3iVune4_ZtDfCRYPiPKkpWCr31k9w,6799
+gemcode/ide_protocol.py,sha256=WJO4KdwyxjQcH1O_vTn7SPuy1ZZMm0eC8_xRLA9RYQo,2108
+gemcode/ide_stdio.py,sha256=dL6xZCW0PV2OmnStmcSiF76P8n5ac5UrliKi8bkvTzA,10699
 gemcode/intent_classifier.py,sha256=YfRVEe8gHeKlRkjuSWef1bZ0MPBwyYMp5jymP5Vig5U,8507
 gemcode/interactions.py,sha256=B0b3QNE_I2i5_HtiebX4ehhjlc4Nbqjf_XbvcTLyJT0,641
-gemcode/invoke.py,sha256=j_AhfesXRA57-tBQ8i8zO53z7Ll3V_snr1nbJ-OnA3c,10262
+gemcode/invoke.py,sha256=wyX39MHj_R_ttGVQGG7ORlcsTehUlpAJ6VMsDZ0qSD8,10856
 gemcode/kaira_daemon.py,sha256=Bzkpc96HocfYAV9D5skid_Gi4bJDOLgO5YlD8vbTgyY,6960
 gemcode/learning.py,sha256=o4Ivczm626NPRiNbSEb7-RvKJMefnv0ZpYt4UB2C3JA,3856
 gemcode/limits.py,sha256=3j6N8V643X7-nP-cAIf37Xg9bkGpQlEJB3nPptApQWk,2504
@@ -31,6 +31,7 @@ gemcode/mcp_loader.py,sha256=alipHTl5aA7ZCPG6Rq9cyy3UZLsdCra0CETb_fRJl_k,4964
 gemcode/modality_tools.py,sha256=tCcqY6Ca8a_kaO58GBC6OmrmLrrZs_jcKv6fTvt5esE,6879
 gemcode/model_errors.py,sha256=j1nb1dopJyZ6MQQvuuADBqvmcqdL80kQWACuWKMkP4Q,4185
 gemcode/model_routing.py,sha256=_8mnXNwxMPA8wAfl-Yx5lWNgjhyWYTCCCMGlqdGAw90,5174
+gemcode/multimodal_input.py,sha256=FrfwcmqgDKnPDWxj76GOltl34D3PNQHxgbSR7ykL8SU,4450
 gemcode/openapi_loader.py,sha256=g_NZD8YL9_9iIJJ9qykhdbBrylJ1195A4FyHGC0mroc,4157
 gemcode/output_styles.py,sha256=29LSK3GGQLcodQhtXjSozgxCj7Z6VZZK8gIodOAC5EA,1910
 gemcode/paths.py,sha256=UQp4R4sUBv7HsM2OVoGlPxyOIOQZE5wpY53G6nHpB5Q,2671
@@ -39,8 +40,8 @@ gemcode/policy_profile.py,sha256=kcaKJQwLxAo3RjqfJJHl_G7B5GgTYKco0z3k5QcXsVY,386
 gemcode/pricing.py,sha256=lftp0SwyDqOzHqC2-6XzgZZhjif5PLdCe1Q3wY-p6kQ,3558
 gemcode/prompt_suggestions.py,sha256=RNEclxtoorRqu-wUlzuyUJ7OLFVOOryGOZBpbaCducI,2544
 gemcode/refine.py,sha256=BijEZ4Z32wGa9aK_WottyAhZF-j0xEqRg5UpjedNv2A,7653
-gemcode/repl_commands.py,sha256=iGF68JdJiwryoZ69EvLSNAg7BN-ivopctJqNWe4UjWk,18467
-gemcode/repl_slash.py,sha256=zRBFJYnaNfO3yAfHQ5S9X-OyiZSWDePoR62OV5LbG5M,83743
+gemcode/repl_commands.py,sha256=XKGXLkA_KfQZubg9_oNjKdd2NXnxOMi8KiwVU8Lllvc,18892
+gemcode/repl_slash.py,sha256=J3_5p02Tp95bm5aigujBZpbP48k68PBLu3a7Rh0FQlU,86082
 gemcode/review_agent.py,sha256=4t7_5-aE60b4-EheJ_eSB_H2eQYf9GppKoui6jw0TME,5264
 gemcode/rules.py,sha256=Itg02VpifOo6jqGj5xwna_ahaPPb0OVtaeR2cNI0pLE,3018
 gemcode/session_runtime.py,sha256=MQr34s6dw4bmk_VPSgBvkJTMwUBZQhvWDXl_iC5Pp6s,20867
@@ -76,7 +77,7 @@ gemcode/tools/__init__.py,sha256=PiVHym3WCkRCC3Y45y_bORnhplY91LaIOaloRYjHPRY,574
 gemcode/tools/bash.py,sha256=kedqaL2CU6O9WLPT83FToqJSaRBEGHesJSBH4pRLHlU,13649
 gemcode/tools/browser.py,sha256=StWRttiyGkR4qaG5urRviJgdoj2hiFB2OuHPItaVzJY,7250
 gemcode/tools/curated_memory.py,sha256=HgpZS81Ncvf0aoSiQ9zDdJdMTA_NWTL4bjLy34Z9a_A,1044
-gemcode/tools/edit.py,sha256=_n45v10YQyKKE2muLDIyeFImzFs0fRztG4xv-HOLnDw,7807
+gemcode/tools/edit.py,sha256=XQbN9iZNiUmzieSDNMPiK-I3LWt5EkJdDPN9slyUJn0,7942
 gemcode/tools/filesystem.py,sha256=1GtLPOKzgjsGNoQA1UvjaUA2MDzm4RjhxUsolGm2ImA,8330
 gemcode/tools/notebook.py,sha256=SF7c-iBDz8heBRK2hERYq39tFeEixhP-1d0kIHBruW4,9208
 gemcode/tools/notes.py,sha256=y1UJOMKntDDB5e8bBPkVVMDfie3ZgKmaoO8r5Cc-owA,4448
@@ -92,7 +93,7 @@ gemcode/tools/todo.py,sha256=dlGfcNce1WsJ5Y9txrDL3SoF6Hv2rms9r1cvGPs6qIs,5798
 gemcode/tools/web.py,sha256=I-6-GgCVKblc9zVFfilWLHoJZfri7_pC2MpT52ZZarE,5078
 gemcode/tools/web_search.py,sha256=YqIvwAoOXK3TMqrrMVeSrg5Nyt7Ou5nRljrYQ4784_4,8816
 gemcode/tui/input_handler.py,sha256=Az8SbPaPHksIoibjph8gevMnfjagR1b-34_wpKbEhgQ,8259
-gemcode/tui/scrollback.py,sha256=BA_hjqdEggnpbq5TZtJbojB7sRRgZ7evQMEQEfeCKoU,33137
+gemcode/tui/scrollback.py,sha256=1LcH39ZRiO2BFHWBFEcWZdWpe6-XFhUYWAePCyx91PI,33534
 gemcode/tui/spinner.py,sha256=dExs_enBPOWjkmRtodDzRw3E-MYh-xgtqDo54Q82sco,4892
 gemcode/tui/welcome_banner.py,sha256=aocl1lnoyLIM6RN4f65g3i0wRA71RqUlgPrGsXeVLW4,4387
 gemcode/tui/welcome_rich.py,sha256=VERTr2PB8hCdxNftJ827OdilFnnJMMDnqkaqzLne_lQ,4059
@@ -100,9 +101,9 @@ gemcode/web/__init__.py,sha256=EysmUAWs6g-lmMk4VFljKfaHVrEgb_FiIzwQmBdORJc,40
 gemcode/web/sse_adapter.py,sha256=fXhKxn_bdJJUGqlmvkxLNSYL-ZiIZDaLHtQCF_BheRc,7108
 gemcode/web/terminal_repl.py,sha256=fQt895g0qcr6VBhXfv_5b_bsC5zHT5-MO0ysBdgi2Fg,3886
 gemcode/web/web_sse_compat.py,sha256=9A2s-GI7El7AotJqhO263FrLwppCXXkdydZ5EiOQbao,504
-gemcode-0.3.78.dist-info/licenses/LICENSE,sha256=TD4524qn-W8Z07GTDnag-9jJPFutFZNB0a1WbMHPC54,8388
-gemcode-0.3.78.dist-info/METADATA,sha256=LEGVRi0Lfgz12djaXYe11PAzIEpce21QAIzpPQx3tvM,40109
-gemcode-0.3.78.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
-gemcode-0.3.78.dist-info/entry_points.txt,sha256=cZdLTLDiHbks7OSUCuxCh66dCWeQdpLR8BozoqfEjV4,45
-gemcode-0.3.78.dist-info/top_level.txt,sha256=UYrjULLBY2bcgK6KI6flomJWmsbDXu7n0rvW2SWFrbo,8
-gemcode-0.3.78.dist-info/RECORD,,
+gemcode-0.3.81.dist-info/licenses/LICENSE,sha256=TD4524qn-W8Z07GTDnag-9jJPFutFZNB0a1WbMHPC54,8388
+gemcode-0.3.81.dist-info/METADATA,sha256=eZVjHhg63IeTdAmmONikMGyM4X9xR4RbIF3vaMUfaF4,41198
+gemcode-0.3.81.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+gemcode-0.3.81.dist-info/entry_points.txt,sha256=cZdLTLDiHbks7OSUCuxCh66dCWeQdpLR8BozoqfEjV4,45
+gemcode-0.3.81.dist-info/top_level.txt,sha256=UYrjULLBY2bcgK6KI6flomJWmsbDXu7n0rvW2SWFrbo,8
+gemcode-0.3.81.dist-info/RECORD,,