seedagent 0.7.0__py3-none-any.whl

coding_agent/__init__.py

@@ -0,0 +1,169 @@
+"""Personal coding agent: Claude on Azure (Microsoft Foundry) with a manual tool-use loop.
+
+Tools:
+  - list_directory   : list the folders and files in a directory
+  - change_directory : move the agent's current directory (never outside the workspace)
+  - grep        : regex search across files in the workspace
+  - read_file   : read a file (optionally a line range)
+  - edit_file   : replace an exact snippet in a file -- shows a diff and asks permission first
+  - write_file  : create/overwrite a file -- shows a diff and asks permission first
+  - download_file : download a URL (http/https) into the workspace -- always asks, even in
+                  autonomous mode; size-capped (AGENT_DOWNLOAD_MAX_MB, default 50); cloud metadata
+                  and link-local addresses are refused (they can leak Azure managed-identity tokens)
+  - clone_repo  : git clone an https or ssh repository into a new folder of the workspace -- always
+                  asks, even in autonomous mode; shallow by default; hooks and non-network
+                  protocols (file://, ext::) are disabled
+  - screenshot_page : open a page in headless Chromium (your dev server, a local HTML file, or a
+                  public site) and show Claude the screenshot, plus console errors and failed
+                  requests -- Claude sees the image itself (text, layout, colors), no OCR needed.
+                  Needs Playwright: `pip install playwright` (or `uv add --dev playwright`), then
+                  `playwright install chromium` -- or it uses the installed Edge / Chrome when that
+                  download is blocked. `coding-agent --check-browser` tests it. localhost / private addresses and workspace files
+                  open without asking; public sites always ask. AGENT_BROWSER_PATH picks a specific
+                  Chromium/Chrome/Edge executable.
+  - web_open, web_click, web_type, web_back, web_page, web_look, web_close : browse a site step by step in a
+                  hidden browser that stays open -- the page's text and its links and fields with numbers; the
+                  user approves each new site and every form that sends data; never passwords or payments
+                  (same Playwright setup as screenshot_page)
+  - view_image  : show Claude an image from the workspace (a mockup, a design export, a screenshot)
+  - read_pdf    : give Claude a PDF's pages as a document it reads itself -- text, tables, layout and
+                  scanned pages -- or just the extracted text for long documents
+  - search_pdf  : find a word or phrase in a PDF's text: the page numbers and a short snippet of every match
+  - search_library : find the pages of all the PDFs of the library that have a query's words (full-text index, ranked; scans through OCR)
+                  (the text is extracted once and cached), then open just those pages with read_pdf
+  - read_excel  : list a workbook's sheets and show cells (values and formulas) of a sheet or range
+  - edit_excel  : set cell values or formulas in an .xlsx/.xlsm (or create a new workbook) -- shows a
+                  cell-by-cell diff and asks first; a copy of the previous file is kept in
+                  $HOME/.coding-agent/backups/; warns (and always asks) when the workbook has charts,
+                  images or pivot tables, which openpyxl cannot keep (with Excel doing the saving --
+                  AGENT_EXCEL_BACKEND=xlwings, the default when Excel and xlwings are there -- nothing is lost)
+  - view_excel  : see a sheet or range as the person sees it (Excel's rendering with charts, or a drawing)
+  - format_excel: bold, fills, borders, wrap, widths, number formats, frozen header, filters
+  - add_chart, add_table, add_pivot_table : add a chart, an Excel table or a pivot table (pivot
+                  tables need Excel) -- shows what will be added and asks first; a backup is kept
+  - run_python_excel : a Python script run with Excel (xlwings) on a workbook --
+                  macros, programs and other files refused before it runs; a backup is kept first
+  - copy_path   : copy a file or a folder inside the workspace -- a text file shows a diff, a
+                  binary file or folder shows what will be created; asks permission first
+  - delete_file : delete a file -- always asks for human validation, even in autonomous mode
+  - delete_folder : delete a folder and everything in it -- shows what it contains and always
+                  asks for human validation, even in autonomous mode; never the workspace root,
+                  a .git folder, or a folder holding the agent's own files
+                  (edit_file, write_file, delete_file and delete_folder never touch the agent's own source)
+  - ask_human   : lets the model ask you a question mid-task
+  - git         : read-only git -- status, diff and log of the workspace (never commits, checks
+                  out or changes anything; external diff tools, textconv filters, pagers and
+                  fsmonitor hooks are disabled so a repository's config cannot run commands)
+  - run_python  : run a Python snippet, script or module (e.g. pytest) -- asks permission first
+                  (uses `uv run --frozen/--no-sync` when uv is installed: the project's own
+                  environment, never rewriting uv.lock; the code cannot start, replace or kill
+                  processes or modify files, including through ctypes -- see GUARD_SOURCE)
+  - load_skill  : load a skill's full instructions when a task matches it
+  - web_search  : Anthropic's server-side web search (runs on Anthropic's side; nothing executes
+                  locally). AGENT_WEB_SEARCH=20250305 (default; the only version on Foundry
+                  deployments hosted on Azure), 20260209 (better filtering; Anthropic-hosted
+                  deployments), or off.
+
+Skills are folders with a SKILL.md (a `name` / `description` header, then instructions), found in:
+    coding_agent/skills/                 -- shipped with the agent
+    $HOME/.coding-agent/skills/          -- personal, every project (override with AGENT_SKILLS_DIR)
+    <project>/.agent/skills/             -- per project (can be committed)
+A later location overrides an earlier one with the same skill name. Only names and descriptions
+are sent up front; Claude loads a skill's instructions when it needs them.
+
+Memory: notes about each project, kept between runs in
+$HOME/.coding-agent/memory/<project>/memories/notes.md (override the root with AGENT_MEMORY_DIR).
+They are given to Claude at the start of each session. Updating them never slows the agent down:
+after each instruction a background thread sends a summary of what happened to a separate
+"memory curator" call, which rewrites notes.md only when something durable was learned. You get
+the next prompt right away; "[memory] ..." shows when the update finishes. AGENT_MEMORY_MODEL
+picks the deployment it uses (default: the main one -- a smaller, cheaper one works well);
+AGENT_MEMORY=off disables updates. On exit the agent waits (up to 60 s) for a pending update.
+
+Configuration (environment variables or a .env file):
+    ANTHROPIC_FOUNDRY_ENDPOINT     https://<resource>.services.ai.azure.com/anthropic
+    ANTHROPIC_FOUNDRY_API_KEY      API key; leave unset to sign in with a Microsoft work account: the
+                                   Windows session's account, `az login`, ... or else the Microsoft
+                                   sign-in page, once (see coding_agent/signin.py)
+    ANTHROPIC_FOUNDRY_DEPLOYMENT   your Claude deployment name
+    AZURE_TENANT_ID / AZURE_CLIENT_ID  tenant and app registration for the sign-in page (optional)
+    ANTHROPIC_FOUNDRY_BROWSER_SIGN_IN=0  never open the sign-in page (servers, CI)
+
+    Or, without Azure: Anthropic's own API (used only when ANTHROPIC_FOUNDRY_ENDPOINT is not set)
+    ANTHROPIC_API_KEY              an API key from console.anthropic.com
+    ANTHROPIC_MODEL                a model ID (default claude-sonnet-5)
+    CODEAGENT_THINKING             off (default), adaptive, between_tools or disabled
+    CODEAGENT_EFFORT               medium (default), low, high, xhigh, max or default (see example.env)
+
+Usage:
+    uv sync                                   # once, in the agent's folder (add --extra browser for screenshots)
+    uv run coding-agent -d path/to/project "Add input validation to the CLI"
+    python agent.py -d path/to/project "..."      # same thing, without installing
+    coding-agent -d path/to/project "..." -i      # keep chatting after the task
+    coding-agent -d path/to/project               # interactive mode only
+    coding-agent -d path/to/project -r            # resume the last conversation in this project
+    coding-agent -d path/to/project "..." --auto  # autonomous mode (see below)
+    coding-agent -d path/to/project --where       # show where memory and skills are read from
+
+As a library (other front ends, e.g. a desktop app), see coding_agent.session:
+    from coding_agent import session
+    session.open_project(path, ui=MyUI(), tools=[...], system_prompt="...")
+    session.send("instruction")
+    coding_agent.register_tool(schema, handler)  # the application's own tool (see the README)
+The package layout: config (settings), state (the session), ui (the UI interface and the
+terminal), loop (the agent loop), tools/ (one module per tool family), guard (the run_python
+sandbox), skills, memory, context (context window management), cli (the terminal front end).
+    (in interactive mode, /skills re-scans the skill folders and shows them)
+
+$HOME is used when set; otherwise your user folder (on Windows, %USERPROFILE%).
+
+Autonomous mode (--auto, or /auto in interactive mode to toggle, /mode to show): edits,
+new files and run_python are applied without asking (diffs are still printed), and ask_human
+does not wait -- Claude decides and states its assumptions. Deleting a file or a folder always
+waits for your approval, even in autonomous mode. Workspace confinement,
+self-protection and the subprocess block still apply; Ctrl+C stops it. AGENT_MAX_STEPS (default
+100) caps the model calls per instruction in every mode.
+
+Token usage: coding_agent.usage adds up what the API reports for every model call (agent, compact, memory) and
+estimates what each tool's results added: mark = usage.snapshot(); session.send(...); usage.since(mark).
+After each instruction the agent shows "[tokens: ... in, ... out]".
+
+Logs: everything the agent shows (tool calls and results, changes, warnings, errors, questions, token usage) is also written to
+MEMORY_HOME/<project>/agent.log (about 2 MB at most) through the logger coding_agent.ui. AGENT_LOG_LEVEL=DEBUG adds the model's text;
+AGENT_LOG=off writes no file. File contents and typed answers are never logged.
+
+Context management (long sessions): the agent tracks how much of the model's context window
+the conversation uses and prints it after each instruction ("[context] 84k / 200k tokens").
+Past 50% it replaces old tool outputs with a short note (Claude re-reads files when needed);
+past 70% it compacts: a summary call replaces the earlier conversation with a brief (goal,
+decisions, files changed, state, next steps). If the API still says the prompt is too long, it
+compacts and retries once. AGENT_CONTEXT_WINDOW (default 200000) is your deployment's window;
+AGENT_COMPACT_MODEL picks the deployment that writes summaries (default: the main one).
+Pasting: multi-line text pasted at the "You:" prompt (a traceback, a code snippet) is sent as
+one instruction. You can also type three double quotes on a line of their own, then paste or
+type anything, and end with three double quotes on their own line again. Approval prompts ignore anything typed or pasted before they appear, so
+leftover pasted lines can never answer "Apply this change?".
+
+Interactive commands: /context shows usage, /compact compacts now, /clear starts a fresh
+conversation (memory notes are kept).
+
+`path:line` references in the output are clickable links that open the file at that line.
+Set AGENT_EDITOR to vscode (default), cursor, file, or none.
+"""
+
+from .certificates import use_system_certificates as _use_system_certificates
+
+_use_system_certificates()  # HTTPS behind a company proxy: trust what the operating system trusts
+
+
+
+def __getattr__(name: str):
+    """configure, active_provider and make_anthropic_client (runtime settings for a host application),
+    loaded on first use so that importing the package does not read the configuration."""
+    if name in ("configure", "active_provider", "make_anthropic_client"):
+        from . import config
+        return getattr(config, name)
+    if name == "register_tool":  # a host application's own tools (loads the tool modules on first use)
+        from .tools import register_tool
+        return register_tool
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

coding_agent/__main__.py

@@ -0,0 +1,5 @@
+"""`python -m coding_agent`: the terminal front end."""
+
+from .cli import main
+
+main()

coding_agent/backups.py

@@ -0,0 +1,89 @@
+"""Previous versions of the workbooks the agent changed, and putting one back.
+
+Before each change it saves to a workbook, the agent copies the workbook to
+BACKUP_HOME/<folder>-<code>/<YYYYmmdd-HHMMSS>-<file name>: <folder>-<code> identifies the project
+folder (its name and a hash of its full path), and the time is when the change was saved -- the
+copy is the workbook as it was just before. Backups are kept a few days (cleanup.py).
+
+Restoring a version first backs up the current one the same way, so a restore can be undone too.
+Used by the restore_backup tool and by applications (e.g. a "previous versions" list in a window).
+"""
+
+from __future__ import annotations
+
+import datetime
+import hashlib
+import os
+import re
+import shutil
+import time
+from pathlib import Path
+
+from . import state
+from .config import BACKUP_HOME
+
+NAME = re.compile(r"^(\d{8})-(\d{6})-(.+)$")
+
+
+def folder(workspace: Path | None = None) -> Path:
+    """The backups of a project folder (default: the current workspace)."""
+    ws = workspace or state.workspace
+    return BACKUP_HOME / f"{ws.name}-{hashlib.sha256(str(ws).encode()).hexdigest()[:8]}"
+
+
+def save(path: Path, content: bytes, workspace: Path | None = None) -> Path:
+    """Keep `content` (a file's current bytes) as a previous version of `path`. Returns the copy."""
+    target = folder(workspace)
+    target.mkdir(parents=True, exist_ok=True)
+    backup = target / f"{time.strftime('%Y%m%d-%H%M%S')}-{path.name}"
+    while backup.exists():  # two saves within the same second
+        backup = backup.with_name(f"{time.strftime('%Y%m%d-%H%M%S', time.localtime(time.time() + 1))}-{path.name}")
+        time.sleep(0.01)
+    backup.write_bytes(content)
+    return backup
+
+
+def moment(version: str) -> datetime.datetime:
+    match = NAME.match(version)
+    if not match:
+        raise ValueError(f"not a backup name: {version}")
+    return datetime.datetime.strptime(match.group(1) + match.group(2), "%Y%m%d%H%M%S")
+
+
+def versions(name: str, workspace: Path | None = None) -> list[dict]:
+    """The previous versions of the file called `name` in a project folder, newest first: id (the
+    backup's file name), time (ISO, local time of the change it preceded) and size in bytes."""
+    found = []
+    backups = folder(workspace)
+    for file in backups.iterdir() if backups.is_dir() else []:
+        match = NAME.match(file.name)
+        if not (file.is_file() and match and match.group(3) == name):
+            continue
+        try:
+            when = moment(file.name)
+        except ValueError:
+            continue
+        found.append({"id": file.name, "time": when.isoformat(timespec="seconds"), "size": file.stat().st_size})
+    return sorted(found, key=lambda v: v["id"], reverse=True)
+
+
+def restore(path: Path, version: str, workspace: Path | None = None) -> str:
+    """Put a previous version back in place of `path`, after backing up the current one. Returns a
+    sentence for the person. Raises ValueError (no such version) or PermissionError (the file is
+    open, e.g. in Excel)."""
+    if version not in {v["id"] for v in versions(path.name, workspace)}:
+        raise ValueError(f"No previous version {version} of {path.name}.")
+    source = folder(workspace) / version
+    if path.exists():  # so that the restore can be undone
+        save(path, path.read_bytes(), workspace)
+    tmp = path.with_name(f".{path.name}.restore-tmp")
+    try:
+        shutil.copyfile(source, tmp)
+        os.replace(tmp, path)
+    except PermissionError:
+        raise PermissionError(f"{path.name} could not be replaced: it is open (in Excel?). Close it and try again.")
+    finally:
+        if tmp.exists():
+            tmp.unlink()
+    return (f"{path.name} is back to its version from before the change of {moment(version):%d %b %Y at %H:%M}. "
+            "The version it replaced is kept among the previous versions.")

coding_agent/certificates.py

@@ -0,0 +1,55 @@
+"""HTTPS through a company proxy: trust the certificates the operating system trusts.
+
+Many company networks inspect HTTPS: a proxy re-signs every site with the company's own root
+certificate, installed in the Windows (or macOS) certificate store -- which is why the browser works.
+Python brings its own list of certificates (certifi) and does not know that root, so every HTTPS call
+fails with CERTIFICATE_VERIFY_FAILED. (uv's --system-certs / UV_SYSTEM_CERTS only covers uv's own
+downloads: the packages it installs, not the program it runs.)
+
+With truststore, Python checks certificates with the operating system instead, like the browser:
+every HTTPS connection of the agent -- Claude, download_file, the gateway -- trusts what Windows
+trusts. It is turned on when the package is imported; AGENT_SYSTEM_CERTS=0 turns it off.
+"""
+
+from __future__ import annotations
+
+import os
+import ssl
+
+_enabled = False
+
+
+def use_system_certificates() -> bool:
+    """Make Python's ssl use the operating system's certificate store (once). True if it is on."""
+    global _enabled
+    if _enabled:
+        return True
+    if (os.environ.get("AGENT_SYSTEM_CERTS") or "1").strip().lower() in ("0", "false", "no", "off"):
+        return False
+    try:
+        import truststore
+    except ImportError:  # not installed: Python's own certificates, as before
+        return False
+    truststore.inject_into_ssl()
+    _enabled = True
+    return True
+
+
+def ssl_context() -> ssl.SSLContext:
+    """A client context that checks certificates with the operating system when it can."""
+    try:
+        import truststore
+        return truststore.SSLContext(ssl.PROTOCOL_TLS_CLIENT)
+    except ImportError:
+        return ssl.create_default_context()
+
+
+def explain(error: BaseException) -> str | None:
+    """A plain explanation for a certificate failure, None for any other error."""
+    if "CERTIFICATE_VERIFY_FAILED" not in str(error) and "certificate verify failed" not in str(error).lower():
+        return None
+    return ("the site's HTTPS certificate is not trusted on this machine. On a company network this "
+            "usually means a proxy inspects HTTPS with the company's own certificate: this is not a "
+            "temporary error, do not retry. The agent trusts the operating system's certificates when "
+            "truststore is installed (uv sync) and AGENT_SYSTEM_CERTS is not 0; otherwise ask IT for the "
+            "company root certificate and set SSL_CERT_FILE to it.")

coding_agent/cleanup.py

@@ -0,0 +1,128 @@
+"""Clean-up of what the agent keeps on the machine, so nothing grows forever.
+
+Runs by itself, once per process: at the start of the coding-agent command, and the first time an
+application opens a project (session.open_project). AGENT_CLEANUP=off switches this automatic run
+off; an application that prefers to decide when (a server running for weeks might call it daily)
+calls cleanup.run() itself.
+
+- Backups (BACKUP_HOME, ~/.coding-agent/backups): the copy of a workbook taken before each change
+  is deleted after AGENT_BACKUP_DAYS days (default 3): long enough to undo a change noticed when
+  the workbook is checked, without keeping copies of confidential workbooks on the machine.
+- Saved conversations (MEMORY_HOME/<project>/conversation.json, used by --resume): deleted after
+  AGENT_CONVERSATION_DAYS days (default 30).
+- Memory (MEMORY_HOME/<project>/): the whole memory of a project folder not used for
+  AGENT_MEMORY_DAYS days (default 90) is deleted. The notes of a project in use are kept; the
+  memory curator already keeps them under a size limit.
+Nothing here ever touches the projects themselves. A file that cannot be deleted (open elsewhere,
+no permission) is left for next time.
+"""
+
+from __future__ import annotations
+
+import os
+import shutil
+import time
+from pathlib import Path
+
+BACKUP_DAYS = 3
+CONVERSATION_DAYS = 30
+MEMORY_DAYS = 90
+DAY = 86_400
+_ran = False  # the clean-up has run in this process (by run(), automatically or by the application)
+
+
+def days(variable: str, default: int) -> int:
+    """A number of days from the environment (at least 1), or the default."""
+    try:
+        return max(1, int(os.environ.get(variable) or default))
+    except ValueError:
+        return default
+
+
+def older_than(path: Path, days_old: float, now: float) -> bool:
+    return now - path.stat().st_mtime > days_old * DAY
+
+
+def clean_backups(backups: Path, days_old: float, now: float) -> int:
+    """Backups older than `days_old`. Returns how many were deleted."""
+    if not backups.is_dir():
+        return 0
+    deleted = 0
+    for file in [f for f in backups.rglob("*") if f.is_file()]:
+        if older_than(file, days_old, now):
+            try:
+                file.unlink()
+                deleted += 1
+            except OSError:
+                pass
+    for folder in sorted((p for p in backups.rglob("*") if p.is_dir()), key=lambda p: len(p.parts), reverse=True):
+        if not any(folder.iterdir()):
+            folder.rmdir()
+    return deleted
+
+
+def clean_memory(memory: Path, days_unused: float, now: float) -> int:
+    """The whole memory of each project not used for `days_unused` days (its newest file is older).
+    Returns how many projects' memories were deleted."""
+    if not memory.is_dir():
+        return 0
+    deleted = 0
+    for project in memory.iterdir():
+        if not project.is_dir():
+            continue
+        newest = max((f.stat().st_mtime for f in project.rglob("*") if f.is_file()), default=project.stat().st_mtime)
+        if now - newest > days_unused * DAY:
+            shutil.rmtree(project, ignore_errors=True)
+            deleted += not project.exists()
+    return deleted
+
+
+def clean_conversations(memory: Path, days_old: float, now: float) -> int:
+    """Saved conversations older than `days_old`. Returns how many were deleted."""
+    deleted = 0
+    for file in memory.glob("*/conversation.json") if memory.is_dir() else []:
+        if older_than(file, days_old, now):
+            try:
+                file.unlink()
+                deleted += 1
+            except OSError:
+                pass
+    return deleted
+
+
+def enabled() -> bool:
+    """AGENT_CLEANUP=off (or 0, false, no) switches the automatic clean-up off."""
+    return (os.environ.get("AGENT_CLEANUP") or "on").strip().lower() not in ("off", "0", "false", "no")
+
+
+def run_once(backups: Path | None = None, memory: Path | None = None) -> str | None:
+    """The clean-up, unless it already ran in this process or AGENT_CLEANUP=off: the summary, or None when it did not run."""
+    if _ran or not enabled():
+        return None
+    return run(backups, memory)
+
+
+def run(backups: Path | None = None, memory: Path | None = None, now: float | None = None) -> str:
+    """The whole clean-up; a one-line summary. Never raises. Given both folders, the agent's settings
+    are not loaded (an application may configure them later, before its first call to Claude)."""
+    global _ran
+    _ran = True
+    if backups is None or memory is None:
+        from .config import BACKUP_HOME, MEMORY_HOME
+
+        backups = BACKUP_HOME if backups is None else backups
+        memory = MEMORY_HOME if memory is None else memory
+    now = time.time() if now is None else now
+    done = []
+    for label, step in [
+        ("old backup(s)", lambda: clean_backups(backups, days("AGENT_BACKUP_DAYS", BACKUP_DAYS), now)),
+        ("unused project memories", lambda: clean_memory(memory, days("AGENT_MEMORY_DAYS", MEMORY_DAYS), now)),
+        ("old saved conversation(s)", lambda: clean_conversations(memory, days("AGENT_CONVERSATION_DAYS",
+                                                                                 CONVERSATION_DAYS), now)),
+    ]:
+        try:
+            if count := step():
+                done.append(f"{count} {label}")
+        except OSError as e:
+            done.append(f"{label}: not cleaned ({e})")
+    return "Clean-up: " + (", ".join(done) if done else "nothing to delete")

coding_agent/cli.py

@@ -0,0 +1,201 @@
+"""The terminal front end: `coding-agent -d <project> [instruction]`."""
+
+import argparse
+import sys
+from pathlib import Path
+
+import anthropic
+
+from . import history, session, state
+from .config import CLEAR_AT, COMPACT_AT, UV, WEB_SEARCH, _get_client, provider_label, uses_deepseek
+from .errors import connection_summary
+from .context import compact_between_instructions, context_status, reset_usage
+from .conversation import save_conversation
+from .loop import send, set_auto_mode
+from .memory import print_memory_status
+from .skills import discover_skills, locations_report, skills_catalog
+from .tools.browser import check_browser
+from .ui import TerminalUI, read_text
+
+
+def parse_args() -> argparse.Namespace:
+    parser = argparse.ArgumentParser(description="Personal coding agent (Claude on Azure).")
+    parser.add_argument("instruction", nargs="?", help="Task for the agent. Omit to start in interactive mode.")
+    parser.add_argument("-d", "--dir", default=".", help="Project directory the agent works in (default: current directory).")
+    parser.add_argument("-i", "--interactive", action="store_true", help="Keep chatting after the instruction finishes.")
+    parser.add_argument("-r", "--resume", action="store_true", help="Continue the last conversation in this project.")
+    parser.add_argument("--auto", action="store_true", help="Autonomous mode: apply edits and Python runs without asking.")
+    parser.add_argument("--read", action="append", default=[], metavar="DIR",
+                        help="Another folder the agent may read but never write (repeat for several).")
+    parser.add_argument("--where", action="store_true", help="Show where memory and skills are read from, then exit.")
+    parser.add_argument("--check", action="store_true", help="Test each step of a call to Claude (sign-in, request, streaming, thinking, tools), then exit.")
+    parser.add_argument("--memories", nargs="?", const="", metavar="NAME",
+                        help="List every project's memory (or show one project's notes), then exit.")
+    parser.add_argument("--forget", metavar="NAME",
+                        help="Delete a project's memory (NAME, 'all', or '.' for the -d project), after confirmation, then exit.")
+    parser.add_argument("--forget-logins", nargs="?", const="all", metavar="SITE",
+                        help="Delete the sign-ins kept for the browsing tools (a site, or all), then exit.")
+    parser.add_argument("--forget-secrets", action="store_true", help="Delete the mail and SMS logins saved in ~/.coding-agent/secrets, then exit.")
+    parser.add_argument("--ocr", nargs="+", metavar="PDF", help="Read the scanned pages of these PDFs once with OCR (tesseract), keep the text for search_pdf and read_pdf, then exit.")
+    parser.add_argument("--index", nargs="+", metavar="FOLDER", help="Index the PDFs of these folders for search_library (scanned pages are read with OCR, which takes a while), then exit.")
+    parser.add_argument("--check-browser", action="store_true", help="Test the browser used by screenshot_page, then exit.")
+    return parser.parse_args()
+
+
+def run_ocr(files: list[str]) -> None:
+    """`coding-agent --ocr FILE...`: OCR every page without a text layer, with a progress line, and keep the text."""
+    from . import ocr
+    from .config import OCR_LANGS
+    from .tools.documents import pdf_page_texts
+    if not ocr.available():
+        raise SystemExit(ocr.missing_message())
+    for name in files:
+        path = Path(name).expanduser().resolve()
+        texts = pdf_page_texts(path)
+        blank = [n for n, t in enumerate(texts, 1) if not t]
+        done = ocr.cached(path)
+        todo = [n for n in blank if n not in done]
+        print(f"{path.name}: {len(texts)} page(s), {len(blank)} without a text layer, {len(blank) - len(todo)} already read ({OCR_LANGS})")
+        if todo:
+            ocr.read_pages(path, todo, progress=lambda i, total: print(f"\r  OCR {i}/{total}", end="", flush=True))
+            print()
+
+
+def run_index(folders: list[str]) -> None:
+    """`coding-agent --index FOLDER...`: (re)index the PDFs of each folder, OCR included; only new or changed files are read."""
+    from . import index, ocr
+    if not ocr.available():
+        print("Warning: " + ocr.missing_message() + " Scanned pages will not be indexed.")
+    for name in folders:
+        root = Path(name).expanduser().resolve()
+        if not root.is_dir():
+            raise SystemExit(f"Not a folder: {root}")
+        read = index.refresh(root, ocr_scans=ocr.available(), log=print,
+                             progress=lambda i, total: print(f"\r  OCR {i}/{total}", end="", flush=True))
+        print(f"{root}: {len(index.documents_under(root))} document(s), {len(read)} read")
+
+
+def main() -> None:
+    args = parse_args()
+    if args.memories is not None or args.forget:  # developers: no project opened, no call to Claude
+        from . import memories
+        from .config import MEMORY_HOME
+        current = session.project_id(Path(args.dir).expanduser().resolve())
+        if args.forget:
+            print(memories.forget(MEMORY_HOME, current if args.forget == "." else args.forget))
+        elif args.memories:
+            print(memories.show(MEMORY_HOME, current if args.memories == "." else args.memories))
+        else:
+            print(memories.listing(MEMORY_HOME, current))
+        return
+    if args.forget_logins:
+        from . import websessions
+        removed = websessions.forget(args.forget_logins)
+        print("Removed: " + ", ".join(removed) if removed else "No saved sign-in" + ("" if args.forget_logins == "all" else f" for {args.forget_logins}") + ".")
+        return
+    if args.forget_secrets:
+        from . import credentials
+        removed = credentials.forget()
+        print("Removed: " + ", ".join(removed) if removed else "No saved login.")
+        return
+    if args.index:
+        return run_index(args.index)
+    if args.ocr:
+        return run_ocr(args.ocr)
+    if args.check_browser:
+        print(check_browser())
+        return
+    try:
+        workspace = Path(args.dir).expanduser().resolve()
+        if args.check:
+            from .diagnose import run_check
+            session.open_project(workspace, ui=TerminalUI())
+            raise SystemExit(0 if run_check() else 1)
+        if args.where:  # no API client, no saved conversation needed
+            session.open_project(workspace, ui=TerminalUI())
+            print(f"Workspace: {state.workspace}")
+            print(locations_report(verbose=True))
+            return
+        client = _get_client()
+        from .cleanup import run_once as clean_up
+        if (cleaned := clean_up()) and cleaned != "Clean-up: nothing to delete":  # old backups, unused memories
+            print(cleaned)
+        print(f"Workspace: {workspace}")
+        print(f"Python runner: {'uv run (' + UV + ')' if UV else sys.executable + ' (uv not found)'}")
+        session.open_project(workspace, ui=TerminalUI(), resume=args.resume, auto=args.auto)
+        state.ask_read_outside = True  # reading outside the project: asks first, once per folder
+        for folder in args.read:  # read-only folders, e.g. documents kept elsewhere
+            print(f"Read-only: {session.add_read_folder(folder)}")
+    except NotADirectoryError as e:
+        raise SystemExit(str(e))
+    print(f"{provider_label()}: {connection_summary()}")
+    print(locations_report(verbose=False))
+    print(f"Web search: {'off' if WEB_SEARCH == 'off' or uses_deepseek() else 'web_search_' + WEB_SEARCH}")
+
+    try:
+        interact(client, session.messages, args)
+    finally:
+        session.close()
+
+
+def interact(client: anthropic.Anthropic, messages: list, args: argparse.Namespace) -> None:
+    if args.instruction:
+        ok = send(client, messages, args.instruction)
+        if not args.interactive:
+            if not ok:
+                raise SystemExit(1)  # main() still waits for the memory update first
+            return
+
+    print("Interactive mode. Type 'exit' to quit. Multi-line pastes are sent as one message (or wrap "
+          "text in \"\"\" lines).\nCommands: /auto (toggle autonomous mode), /mode, /skills (re-scan "
+          "skills), /context, /compact, /clear.")
+    history.enable()  # up arrow recalls earlier questions
+    while True:
+        print_memory_status()
+        try:
+            print()
+            user_input = read_text(history.prompt("\033[1mYou:\033[0m ")).strip()
+        except (EOFError, KeyboardInterrupt):
+            break
+        history.remember(user_input)
+        if user_input.lower() in ("exit", "quit"):
+            break
+        if user_input.lower() == "/auto":
+            set_auto_mode(not state.auto_mode)
+            continue
+        if user_input.lower() == "/mode":
+            print(f"Autonomous mode is {'ON' if state.auto_mode else 'OFF'}.")
+            continue
+        if user_input.lower() == "/context":
+            print(f"Context: {context_status(messages)} in {len(messages)} messages "
+                  f"(window from AGENT_CONTEXT_WINDOW; tool outputs cleared past {CLEAR_AT:.0%}, "
+                  f"compaction past {COMPACT_AT:.0%}).")
+            print(f"This session: {state.context['cleared']} tool output(s) cleared, "
+                  f"{state.context['compactions']} compaction(s).")
+            continue
+        if user_input.lower() == "/compact":
+            try:
+                compact_between_instructions(client, messages)
+            except (anthropic.APIError, RuntimeError) as e:
+                print(f"[compaction failed] {e}")
+            continue
+        if user_input.lower() == "/clear":
+            messages.clear()
+            state.pending_blocks.clear()
+            state.memory_sent = False
+            state.pdf_read_as_text = False  # the conversation is empty: read_pdf's visual mode needs a text read again
+            reset_usage()
+            save_conversation(messages)
+            print("Started a fresh conversation (memory notes are kept).")
+            continue
+        if user_input.lower() == "/skills":
+            state.skills = discover_skills()
+            print(locations_report(verbose=True))
+            state.skills_note = "Updated skill list (the user re-scanned the skill folders):\n" + skills_catalog()
+            continue
+        if user_input:
+            send(client, messages, user_input)
+
+
+if __name__ == "__main__":
+    main()