gemcode 0.3.48__tar.gz → 0.3.50__tar.gz

{gemcode-0.3.48/src/gemcode.egg-info → gemcode-0.3.50}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gemcode
-Version: 0.3.48
+Version: 0.3.50
 Summary: Local-first coding agent on Google Gemini + ADK
 Author: GemCode Contributors
 License:                                  Apache License

{gemcode-0.3.48 → gemcode-0.3.50}/pyproject.toml

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

{gemcode-0.3.48 → gemcode-0.3.50}/src/gemcode/agent.py

@@ -122,13 +122,68 @@ def _load_gemini_md(project_root: Path) -> str:
   return combined[:_TOTAL_CAP]
 
 
+def _get_git_context(root) -> str:
+  """
+  Run a quick git snapshot at session start — branch, recent commits, diff-stat.
+  Returns a formatted string or empty string if not a git repo.
+  Mirrors OpenClaude's getGitStatus() pattern.
+  """
+  import subprocess
+  import shutil
+
+  git = shutil.which("git")
+  if not git:
+    return ""
+  try:
+    def _run(*args, cwd=root):
+      r = subprocess.run(
+        [git, "--no-optional-locks"] + list(args),
+        cwd=str(cwd),
+        capture_output=True,
+        text=True,
+        timeout=5,
+      )
+      return r.stdout.strip() if r.returncode == 0 else ""
+
+    # Check it's a git repo
+    if not _run("rev-parse", "--is-inside-work-tree"):
+      return ""
+
+    branch   = _run("rev-parse", "--abbrev-ref", "HEAD") or "HEAD"
+    log      = _run("log", "--oneline", "-5")
+    status   = _run("status", "--short")
+    username = _run("config", "user.name")
+
+    if not log:  # empty repo
+      return ""
+
+    status_trunc = status[:2000] + "\n(truncated)" if len(status) > 2000 else status
+
+    lines = [
+      "This is the git state at session start — it is a snapshot and will NOT update automatically.",
+      f"Current branch: {branch}",
+    ]
+    if username:
+      lines.append(f"Git user: {username}")
+    lines.append(f"Recent commits:\n{log}")
+    if status_trunc:
+      lines.append(f"Working tree status:\n{status_trunc}")
+    else:
+      lines.append("Working tree: clean")
+    return "\n\n".join(lines)
+  except Exception:
+    return ""
+
+
 def _build_runtime_facts(cfg: GemCodeConfig) -> str:
   """
   Injected every session so the model is fully self-aware of its own capabilities,
   limits, and the environment — not just generic defaults.
   """
+  import datetime
   root = cfg.project_root.resolve()
   model = (getattr(cfg, "model", None) or "").strip() or "(default)"
+  today = datetime.date.today().strftime("%A, %B %d, %Y")
 
   # ── Active capabilities ──────────────────────────────────────────────────
   caps: list[str] = []
@@ -178,7 +233,12 @@ def _build_runtime_facts(cfg: GemCodeConfig) -> str:
     "would benefit from background parallelism."
   )
 
+  # ── Git context ───────────────────────────────────────────────────────────
+  git_ctx = _get_git_context(root)
+  git_section = f"\n\n## Git context (snapshot at session start)\n{git_ctx}" if git_ctx else ""
+
   return f"""## Runtime facts (authoritative for this session)
+- **Today's date:** {today}
 - **Project root** — every filesystem tool path is relative to: `{root}`
 - **Model id in use:** `{model}`. Override mid-session with `/model use <id>` or `/mode fast|balanced|quality|auto`.
 - **Execution budget:** {budget_line}.
@@ -190,7 +250,7 @@ def _build_runtime_facts(cfg: GemCodeConfig) -> str:
 {kairos_section}
 - **UI banner** phrases like "GemCode Pro" are terminal marketing, not a separate API tier.
 - **Env toggles** (`GEMCODE_ENABLE_COMPUTER_USE`, `GEMCODE_MODEL`, etc.) affect only the OS process that launched gemcode. Pasting `VAR=1` in chat does NOT reconfigure a running session—tell the user to export in their shell, use project `.env`, or restart the CLI.
-- **Working in subfolders** — call `list_directory("Desktop")`, `glob_files("**/query.ts")`, `read_file("testing/ai-edtech-app/src/app/page.tsx")` directly. Never claim access is blocked unless a tool returned an explicit error."""
+- **Working in subfolders** — call `list_directory("Desktop")`, `glob_files("**/query.ts")`, `read_file("testing/ai-edtech-app/src/app/page.tsx")` directly. Never claim access is blocked unless a tool returned an explicit error.{git_section}"""
 
 
 def _build_memory_section(cfg: GemCodeConfig) -> str:
@@ -398,25 +458,19 @@ You run locally via the GemCode CLI. You are the same agent the user launched
 
 ## Core identity and approach
 
-Use your built-in thinking to read the user's intent before acting. Match the response style to what was actually asked:
+Before you respond to anything, **think through what the person is actually trying to achieve**. Not what category their message fits into — what outcome they want, what they already know, and what the most useful response looks like.
 
-| Message type | Examples | Right action |
-|---|---|---|
-| **Greeting / chitchat** | "hi", "thanks", "cool" | Reply warmly in one sentence. No tools. |
-| **General knowledge** | "what is a closure?", "explain OAuth" | Answer from knowledge. No tools unless this specific repo is needed. |
-| **Project question** | "how does auth work here?", "what's in this folder?" | 1–2 read-only tools, then a focused answer. |
-| **Engineering task** | "fix the bug", "add pagination", "refactor X" | Orient → Plan → Execute → Verify. |
-| **Analysis / audit** | "analyse the whole backend", "summarise all endpoints" | Thorough tool sweep, then synthesise. |
+That thinking should drive everything: how much you use tools, how deep you go, how long you reply, what tone you take. A one-line social message deserves a one-line reply. A vague half-formed request might need a clarifying question before acting. A complex multi-file task needs systematic exploration first. A debugging session mid-error needs a hypothesis, not a search. There is no fixed list of intent types — the space of what people ask is open-ended, and your judgment should be too.
 
-**Never call `list_directory`, `read_project_notes`, or any tool in response to a greeting or a general knowledge question that needs no project context.**
+The one hard rule: **only reach for tools when they genuinely serve the response**. If the answer is in your knowledge, give it. If project context is needed, use the minimal set of read-only tools to get it. If you need to execute something, do it. But never open a tool call just to appear busy.
 
-### Engineering task workflow
-1. **Orient** — use `list_directory`, `glob_files`, `grep_content`, `read_file` to understand structure. These tools need **no permission** and are instant.
-2. **Plan** — for complex tasks, call `todo_write` upfront to map out the work.
-3. **Execute** — make the changes, run the checks, iterate.
-4. **Verify** — confirm the result is correct before reporting done.
+When you do need to act on the codebase:
+1. **Understand first** — explore with `list_directory`, `glob_files`, `grep_content`, `read_file` before touching anything. These are instant and need no permission.
+2. **Plan for anything complex** — use `todo_write` to structure multi-step work before starting.
+3. **Execute completely** — don't stop at the first success. Finish the whole task.
+4. **Verify before you call it done** — check your own work.
 
-Never stop mid-task just because the first tool call succeeded. Keep going until the full task is complete or you hit a genuine blocker.
+The depth of each step should match the complexity of what was asked. Don't run a four-step engineering workflow for a one-sentence question.
 
 ## CRITICAL: Read-only tools first — never bash for exploration
 `bash` and `run_command` require permission confirmation by default. Always start with the **zero-permission** read-only tools:
@@ -439,12 +493,10 @@ You have native deep thinking capability — use it actively:
 - **For trade-off decisions** (which library, which pattern, which approach): reason through the pros/cons given this specific codebase.
 
 ## Interpreting requests
-- **Think first.** Read the message intent before touching any tool. The intent table above is your guide.
-- **Engineering tasks** ("fix", "add", "refactor", "analyse", "debug"): infer from the repo — search, read, then act. Do not give abstract advice when concrete files exist.
-- If the user refers to symbols or behaviors, **find them** with `glob_files`/`grep_content`/`list_directory` — never ask them to paste paths you can discover yourself.
+- If the user refers to symbols, files, or behaviors they expect you to know — **find them** with `glob_files`/`grep_content`/`list_directory`. Never ask them to paste paths you can discover yourself.
 - **Never propose edits to files you haven't read.** Read first, then edit.
 - When something fails, diagnose (re-read the error, check assumptions) before switching strategy. Do not repeat the same failed call.
-- For analysis tasks ("analyse X", "explain X", "what does X do"): immediately start reading files with `list_directory` + `read_file` + `grep_content`. Produce concrete findings, not hypotheses.
+- When asked to analyse or explain something: read the actual files, produce concrete findings, not hypotheses.
 
 ## Tool selection guide
 
@@ -535,13 +587,16 @@ One user message = many model↔tool rounds (up to 256 LLM calls by default). Th
 
 **Do not stop after step 2 or 3** — complete the full task.
 
-## Parallelism
-Issue independent tool calls in the same turn when outputs don't depend on each other:
-- Reading multiple files simultaneously ✓
-- Grepping for different patterns at once ✓
-- `list_directory` + `glob_files` in parallel ✓
-- Multiple `run_subtask` calls in one turn for parallel sub-agent exploration ✓
-Sequential: when step B needs step A's result.
+## Parallelism — batch independent work
+Issue independent tool calls **in the same turn** when outputs don't depend on each other.
+This is faster and costs fewer turns. Concrete examples:
+- Reading multiple files → send all `read_file` calls together
+- Grepping different patterns → one message, multiple `grep_content` calls
+- `list_directory` + `glob_files` → issue both at once
+- Exploring multiple subsystems → one `run_subtask` per subsystem in one turn
+- `git status` and `git log` → chain with `&&` or issue in parallel
+
+Sequential only when step B genuinely needs step A's output.
 
 ## Sub-agent delegation (orchestrator-worker pattern)
 Use `run_subtask` when the work is better done in an isolated context:
@@ -603,11 +658,51 @@ For tasks where quality matters:
 - **Unexpected file content**: re-read the actual file rather than assuming your mental model is correct.
 - **Compiler / linter errors pasted by the user**: extract the file path and line from the error, read that file, apply the minimal fix, and re-run the check. Never explain without fixing.
 
+## Git Safety Protocol
+Follow these rules on every turn, no exceptions:
+- **NEVER** update git config
+- **NEVER** run destructive git commands (`push --force`, `reset --hard`, `checkout .`, `restore .`, `clean -f`, `branch -D`) unless the user *explicitly* asks for it
+- **NEVER** skip hooks (`--no-verify`, `--no-gpg-sign`) unless the user explicitly requests it
+- **NEVER** force-push to main/master — warn the user if they ask for this
+- **Prefer NEW commits over amending.** Only amend when all three conditions hold: (a) user explicitly asked, (b) the commit was created in this session, (c) it has NOT been pushed to remote. If a pre-commit hook rejects a commit, the commit did NOT happen — fix the problem and create a NEW commit, never amend.
+- **Stage selectively** — prefer `git add <specific-file>` over `git add -A` or `git add .` to avoid accidentally including `.env`, credentials, or large binaries
+- **Never commit unless the user explicitly asks.** It is very important to only commit when asked.
+
+## Committing changes
+When the user asks for a git commit:
+1. Run in parallel: `git status`, `git diff`, `git log --oneline -5` (to match their style)
+2. Analyze all staged changes and draft a concise commit message (1-2 sentences, focus on *why* not *what*)
+3. Check for sensitive files (.env, credentials) — warn if they're staged
+4. Stage specific files, then commit via HEREDOC:
+   ```
+   git commit -m "$(cat <<'EOF'
+   Your message here.
+   EOF
+   )"
+   ```
+5. Run `git status` after to confirm success
+6. Do NOT push unless explicitly asked
+
+## Creating pull requests
+Use `gh pr create` via `bash`. When asked to create a PR:
+1. Run in parallel: `git status`, `git diff`, `git log [base]...HEAD`, check remote tracking
+2. Look at ALL commits in the PR (not just the latest)
+3. Push branch if needed: `git push -u origin HEAD`
+4. Create with: `gh pr create --title "..." --body "$(cat <<'EOF'\n## Summary\n...\n## Test plan\n...\nEOF\n)"`
+5. Return the PR URL
+
 ## Risk and permissions
 - State destructive operations clearly before doing them (deletes, force-push, data truncation).
 - For `bash` commands that could be destructive (`rm -rf`, `git push --force`), confirm with the user first.
 - If a tool is denied, adjust the plan — don't retry the same gated call.
 
+## Avoid unnecessary sleep / polling
+- Do NOT `sleep` between commands that can run immediately — just run them
+- Do NOT poll a process in a sleep loop — check its status directly or start it with `background=True`
+- If you're waiting for a background process you started, do not poll — it will complete on its own
+- If you must wait (e.g. for a server to start), use a one-shot check: `bash("sleep 2 && curl -s http://localhost:3000")`
+- Do NOT retry failing commands in a sleep loop — diagnose the root cause first
+
 ## Communication
 - One short line before the first tool call in a turn (e.g. "Reading the auth module and checking the test suite...").
 - Summarize tool results in plain language — the user doesn't see raw tool internals.
@@ -761,10 +856,10 @@ def build_root_agent(
   # prepended to every agent's effective instruction.
   global_instr = (
     "You are GemCode, an expert software engineering agent powered by Google Gemini. "
-    "Think through the user's intent before acting. "
-    "For greetings or general questions, reply directly without calling tools. "
-    "For engineering tasks, act fully and autonomously — orient, plan, execute, verify. "
-    "Use read-only tools before shell/write tools."
+    "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."
   )
 
   agent_kwargs: dict = dict(

{gemcode-0.3.48 → gemcode-0.3.50}/src/gemcode/tools/bash.py

@@ -40,19 +40,60 @@ def make_bash_tool(cfg: GemCodeConfig):
         Run an arbitrary shell command via bash. Supports pipelines, redirects,
         subshells, and multi-step workflows that run_command cannot express.
 
-        Use this for:
-        - Git operations: bash("git log --oneline -20")
-        - Pipelines: bash("cat package.json | python3 -m json.tool")
-        - Finding files: bash("find . -name '*.py' -newer setup.py | head -20")
-        - Complex builds: bash("cd frontend && npm ci && npm run build")
-        - Inspecting output: bash("ls -la | grep '.py'")
-        - Running tests with flags: bash("pytest -x -q --tb=short 2>&1 | head -100")
-
-        For long-running servers use background=True. cwd_subdir sets working
-        directory relative to the project root.
-
-        IMPORTANT: This runs real shell commands. Be precise and avoid destructive
-        operations (rm -rf, force-push, etc.) without explicit user approval.
+        ## Common usage patterns
+
+        Git / version control:
+          bash("git log --oneline -20")
+          bash("git diff HEAD~1 -- src/api/")
+          bash("git status && git diff --stat")
+          bash("git stash list")
+
+        Builds / tests:
+          bash("npm run build 2>&1 | tail -50")
+          bash("pytest tests/ -x -q --tb=short 2>&1 | head -150")
+          bash("cargo build --release 2>&1 | tail -30")
+          bash("go test ./... 2>&1 | tail -50")
+
+        Pipelines and inspection:
+          bash("find . -name '*.py' | xargs grep -l 'SomeClass' | head -20")
+          bash("cat package.json | python3 -m json.tool")
+          bash("wc -l $(find . -name '*.py') | sort -n | tail -20")
+
+        Long-running servers — ALWAYS use background=True:
+          bash("npm run dev", background=True)
+          bash("python manage.py runserver", background=True)
+          bash("tail -f logs/app.log", background=True)
+          NEVER call bash("npm run dev") without background=True — it blocks forever.
+
+        ## Issuing multiple commands
+        When commands are independent, issue them in separate parallel tool calls
+        in the same turn. When they depend on each other, chain with && in one call.
+        Use ; only when you don't care if earlier commands fail.
+        DO NOT use newlines to separate commands (newlines are ok inside quoted strings).
+
+        ## Git Safety Protocol — always follow these rules
+        - NEVER update git config
+        - NEVER run destructive git commands (push --force, reset --hard, checkout .,
+          restore ., clean -f, branch -D) without explicit user instruction
+        - NEVER skip hooks (--no-verify, --no-gpg-sign) unless the user explicitly asks
+        - NEVER force-push to main/master — warn the user if they request it
+        - ALWAYS prefer creating a NEW commit over amending an existing one.
+          Amending is ONLY appropriate when: (a) the user explicitly asks for it AND
+          (b) the commit has not been pushed to a remote yet
+        - When staging files, prefer adding specific files by name rather than
+          "git add -A" or "git add ." which can include .env or credentials
+        - Do NOT commit unless the user explicitly asks you to
+
+        ## Avoid unnecessary sleep
+        - Do NOT sleep between commands that can run immediately — just run them
+        - Do NOT poll in a sleep loop — check process status directly or use background=True
+        - If waiting for a background task, do not sleep-poll; it was started and will finish
+        - If you must wait (rate limits, deliberate pacing), keep it under 5 seconds
+
+        ## Security
+        Be precise. Avoid destructive operations (rm -rf, force-push) without
+        explicit user approval. Quote file paths that contain spaces.
+        cwd_subdir is relative to the project root.
         """
         if not trusted:
             return {"error": "Project folder is not trusted. Re-run GemCode and approve folder trust."}

gemcode-0.3.50/src/gemcode/tools/edit.py

@@ -0,0 +1,82 @@
+"""Write and search_replace tools."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from gemcode.config import GemCodeConfig
+from gemcode.paths import PathEscapeError, resolve_under_root
+
+
+def make_edit_tools(cfg: GemCodeConfig):
+  root = cfg.project_root
+
+  def write_file(path: str, content: str) -> dict:
+    """
+    Create or overwrite a file with the given content.
+
+    Path is relative to the project root.
+
+    IMPORTANT: If the file already exists, READ it first with read_file() before
+    calling write_file(). Overwriting without reading risks losing existing content.
+    Only use write_file for NEW files or when you intend a complete replacement.
+    For targeted in-place edits, use search_replace() instead.
+
+    Never write non-textual content (binary, base64 blobs) — those belong in
+    artifacts, not in source files.
+    """
+    try:
+      p = resolve_under_root(root, path)
+    except PathEscapeError as e:
+      return {"error": str(e)}
+    p.parent.mkdir(parents=True, exist_ok=True)
+    p.write_text(content, encoding="utf-8")
+    return {"path": path, "bytes_written": len(content.encode("utf-8"))}
+
+  def search_replace(
+    path: str,
+    old_string: str,
+    new_string: str,
+    replace_all: bool = False,
+  ) -> dict:
+    """
+    Perform an exact string replacement in a file.
+
+    IMPORTANT: You MUST call read_file() on the file at least once before calling
+    search_replace(). Editing a file you haven't read leads to wrong context
+    and broken changes.
+
+    Usage rules:
+    - old_string must match the file EXACTLY (whitespace, indentation, line endings).
+      The edit FAILS if old_string is not found, or if it appears more than once
+      and replace_all is False.
+    - Use the smallest old_string that is clearly unique — typically 3-5 lines of
+      surrounding context is enough. Do not include 20+ lines of context when 4
+      lines would uniquely identify the target location.
+    - Set replace_all=True to rename a variable or rename a string across the whole file.
+    - Always prefer search_replace over write_file for targeted edits — it preserves
+      the rest of the file and makes the change reviewable.
+    - Do NOT add emojis or comments that just explain what the code does. Only add
+      comments that explain non-obvious intent or trade-offs.
+    - NEVER propose edits before reading. Read first. Edit second.
+    """
+    try:
+      p = resolve_under_root(root, path)
+    except PathEscapeError as e:
+      return {"error": str(e)}
+    if not p.is_file():
+      return {"error": f"Not a file: {path}"}
+    text = p.read_text(encoding="utf-8", errors="strict")
+    count = text.count(old_string)
+    if count == 0:
+      return {"error": "old_string not found"}
+    if count > 1 and not replace_all:
+      return {"error": f"old_string appears {count} times; set replace_all=true or narrow snippet"}
+    if replace_all:
+      new_text = text.replace(old_string, new_string)
+    else:
+      new_text = text.replace(old_string, new_string, 1)
+    p.write_text(new_text, encoding="utf-8")
+    return {"path": path, "replacements": count if replace_all else 1}
+
+  return write_file, search_replace

{gemcode-0.3.48 → gemcode-0.3.50}/src/gemcode/tools/filesystem.py

@@ -21,12 +21,19 @@ def make_filesystem_tools(cfg: GemCodeConfig):
     end_line: int | None = None,
   ) -> dict:
     """
-    Read a text file relative to the project root. Large files are truncated.
+    Read a text file relative to the project root.
 
-    Use start_line / end_line to read a specific line range (1-indexed, inclusive).
-    This is efficient for large files — e.g. read_file("app.py", start_line=100, end_line=200)
-    reads only lines 100–200 without loading the whole file into context.
-    Omit end_line to read from start_line to end of file (still subject to max_bytes).
+    IMPORTANT: ALWAYS use read_file before editing a file. Never propose changes
+    to code you haven't read — the mental model is always wrong without reading.
+    Never use bash("cat file") or bash("head file") — use read_file instead.
+
+    For large files, use start_line / end_line to read a specific range (1-indexed, inclusive):
+      read_file("app.py", start_line=100, end_line=200)  — lines 100-200
+      read_file("app.py", start_line=500)                — line 500 to end
+    This is efficient — loads only the needed slice into context.
+
+    When multiple files are needed, issue all read_file calls in the same turn
+    (parallel reads) rather than sequentially.
     """
     if not trusted:
       return {"error": "Project folder is not trusted. Re-run GemCode and approve folder trust."}
@@ -96,7 +103,13 @@ def make_filesystem_tools(cfg: GemCodeConfig):
     return {"src": src, "dest": dest, "moved": True}
 
   def list_directory(path: str = ".") -> dict:
-    """List files and directories under path (relative to project root)."""
+    """
+    List files and directories under a path (relative to project root).
+
+    Use this instead of bash("ls ...") — it needs no permission and is instant.
+    Prefer for directory exploration before any editing or execution.
+    Issue in parallel with glob_files when you need both structure and file matches.
+    """
     if not trusted:
       return {"error": "Project folder is not trusted. Re-run GemCode and approve folder trust."}
     try:
@@ -116,7 +129,14 @@ def make_filesystem_tools(cfg: GemCodeConfig):
     return {"path": path, "entries": entries[:500]}
 
   def glob_files(pattern: str) -> dict:
-    """Glob file paths relative to project root (e.g. 'src/**/*.py')."""
+    """
+    Find files by glob pattern relative to project root (e.g. 'src/**/*.py').
+
+    Use this instead of bash("find . -name '*.py'") — it needs no permission.
+    Supports recursive patterns: '**/*.ts', 'src/**/test_*.py', '**/config*.json'.
+    Can be issued in parallel with list_directory and grep_content in the same turn.
+    Returns up to 200 matches.
+    """
     if not trusted:
       return {"error": "Project folder is not trusted. Re-run GemCode and approve folder trust."}
     if ".." in pattern or pattern.startswith("/"):

{gemcode-0.3.48 → gemcode-0.3.50}/src/gemcode/tools/search.py

@@ -38,20 +38,28 @@ def make_grep_tool(cfg: GemCodeConfig):
         case_sensitive: bool = True,
     ) -> dict:
         """
-        Search file contents with a regex pattern.
+        Search file contents with a regex pattern (backed by ripgrep when available).
 
-        Scans files matching path_glob (glob relative to project root). Binary files skipped.
+        Use this instead of bash("grep -r pattern .") — it needs no permission
+        and is instant. Binary files are skipped automatically.
 
-        Options:
-        - context_lines: show N lines before and after each match (like grep -C N). Very useful for
-          understanding surrounding code. Example: grep_content("def foo", context_lines=3)
-        - case_sensitive: set False for case-insensitive search (like grep -i)
-        - max_matches: cap on returned matches (1–500, default 80)
+        Parameters:
+        - pattern:       Regex pattern (Python/ripgrep syntax). Use | for alternation.
+        - path_glob:     File glob relative to project root (default: all files).
+        - context_lines: Lines before+after each match (like grep -C). Use to see
+                         surrounding code — e.g. context_lines=4 shows a function's body.
+        - case_sensitive: False for case-insensitive search.
+        - max_matches:   Cap on returned results (1–500, default 80).
 
         Examples:
-          grep_content("TODO", "**/*.py")                          # find all TODOs in Python files
-          grep_content("useState", "**/*.tsx", context_lines=2)    # React hooks with context
-          grep_content("error", "**/*.log", case_sensitive=False)  # case-insensitive log search
+          grep_content("def authenticate", "**/*.py", context_lines=4)
+          grep_content("TODO|FIXME|HACK", "**/*.ts")
+          grep_content("import React", "**/*.tsx", case_sensitive=False)
+          grep_content("class.*Error", "**/*.py", context_lines=2)
+          grep_content("useState", "src/**/*.tsx", context_lines=3)
+
+        Issue multiple grep_content calls in the same turn when searching for
+        different patterns — they run in parallel.
         """
         if max_matches < 1:
             max_matches = 1

{gemcode-0.3.48 → gemcode-0.3.50}/src/gemcode/tools/todo.py

@@ -21,14 +21,48 @@ def make_todo_tool(cfg: GemCodeConfig):
     tool_context: ToolContext,
   ) -> dict[str, Any]:
     """
-    Maintain a task list for this session. Use for multi-step work: plan, then
-    mark items completed as you go.
-
-    Args:
-      merge: If true, upsert by task id and keep prior order for existing ids;
-        if false, replace the entire list.
-      todos: Each item must have id (str), content (str), and status
-        (pending | in_progress | completed | cancelled).
+    Create and maintain a structured task list for the current session.
+    Tracks progress, organises complex tasks, and makes multi-step work
+    visible to the user.
+
+    ## When to use
+    Use proactively when:
+    1. Task has 3 or more distinct steps
+    2. Task is non-trivial and requires careful planning
+    3. User provides a list of things to do (numbered or comma-separated)
+    4. After receiving new instructions — capture them as todos immediately
+    5. When you start working on a sub-task — mark it in_progress BEFORE beginning.
+       Only one task should be in_progress at a time.
+    6. After completing a sub-task — mark it completed and add any discovered follow-ups
+
+    ## When NOT to use
+    Skip this tool when:
+    1. There is only one simple, straightforward task
+    2. The task is trivial (can be done in 1-2 steps)
+    3. The task is purely conversational or informational
+    4. Answering a question that requires no planning
+
+    ## Verification
+    After completing a list of 3 or more tasks, if none of them was a verification
+    step, add a final verification task: "Verify all changes are correct and
+    consistent" — then actually do it (re-read key files, run tests, check imports).
+
+    ## Args
+    - merge: True = upsert by id (update specific items). False = replace entire list.
+    - todos: list of {id: str, content: str, status: pending|in_progress|completed|cancelled}
+
+    ## Examples
+    Good use (complex multi-step task):
+      todo_write(merge=False, todos=[
+        {"id":"1","content":"Read current auth.ts","status":"in_progress"},
+        {"id":"2","content":"Add JWT refresh logic","status":"pending"},
+        {"id":"3","content":"Update tests","status":"pending"},
+        {"id":"4","content":"Run npm run build to verify","status":"pending"},
+      ])
+
+    Bad use (single trivial task — just do it directly):
+      todo_write(merge=False, todos=[{"id":"1","content":"Fix typo in README","status":"pending"}])
+      # Don't do this. Just fix the typo.
     """
     if not isinstance(todos, list):
       return {"error": "todos must be a list"}

{gemcode-0.3.48 → gemcode-0.3.50/src/gemcode.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gemcode
-Version: 0.3.48
+Version: 0.3.50
 Summary: Local-first coding agent on Google Gemini + ADK
 Author: GemCode Contributors
 License:                                  Apache License

gemcode-0.3.48/src/gemcode/tools/edit.py

@@ -1,53 +0,0 @@
-"""Write and search_replace tools."""
-
-from __future__ import annotations
-
-from pathlib import Path
-
-from gemcode.config import GemCodeConfig
-from gemcode.paths import PathEscapeError, resolve_under_root
-
-
-def make_edit_tools(cfg: GemCodeConfig):
-  root = cfg.project_root
-
-  def write_file(path: str, content: str) -> dict:
-    """Create or overwrite a file relative to the project root."""
-    try:
-      p = resolve_under_root(root, path)
-    except PathEscapeError as e:
-      return {"error": str(e)}
-    p.parent.mkdir(parents=True, exist_ok=True)
-    p.write_text(content, encoding="utf-8")
-    return {"path": path, "bytes_written": len(content.encode("utf-8"))}
-
-  def search_replace(
-    path: str,
-    old_string: str,
-    new_string: str,
-    replace_all: bool = False,
-  ) -> dict:
-    """
-    Replace old_string with new_string in a text file. Fails if old_string
-    is missing or duplicate (unless replace_all=True).
-    """
-    try:
-      p = resolve_under_root(root, path)
-    except PathEscapeError as e:
-      return {"error": str(e)}
-    if not p.is_file():
-      return {"error": f"Not a file: {path}"}
-    text = p.read_text(encoding="utf-8", errors="strict")
-    count = text.count(old_string)
-    if count == 0:
-      return {"error": "old_string not found"}
-    if count > 1 and not replace_all:
-      return {"error": f"old_string appears {count} times; set replace_all=true or narrow snippet"}
-    if replace_all:
-      new_text = text.replace(old_string, new_string)
-    else:
-      new_text = text.replace(old_string, new_string, 1)
-    p.write_text(new_text, encoding="utf-8")
-    return {"path": path, "replacements": count if replace_all else 1}
-
-  return write_file, search_replace