cw-relay 0.1.0__tar.gz

cw_relay-0.1.0/.gitignore

@@ -0,0 +1,29 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+*.egg-info/
+*.egg
+build/
+dist/
+.venv/
+venv/
+env/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.tox/
+
+# IDE
+.vscode/
+.idea/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Local config — never commit a real API key
+config.json
+.env

cw_relay-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Casper White
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

cw_relay-0.1.0/PKG-INFO

@@ -0,0 +1,88 @@
+Metadata-Version: 2.4
+Name: cw-relay
+Version: 0.1.0
+Summary: A Claude Code-style terminal chatbot powered by Gemini, with file and shell access.
+Project-URL: Homepage, https://github.com/casperwhite-commits/relay
+Project-URL: Issues, https://github.com/casperwhite-commits/relay/issues
+Author: Casper White
+License: MIT
+License-File: LICENSE
+Keywords: ai,assistant,chat,cli,gemini,terminal
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Utilities
+Requires-Python: >=3.10
+Requires-Dist: google-genai>=0.3.0
+Requires-Dist: rich>=13.0.0
+Description-Content-Type: text/markdown
+
+# relay
+
+A Claude Code-style terminal chatbot, powered by Google Gemini, with direct file and shell access.
+
+```
+  ┌─────────────────────────────────────────┐
+  │   relay · terminal chat (Gemini)        │
+  └─────────────────────────────────────────┘
+```
+
+## Install
+
+```bash
+pip install relay-cli
+```
+
+Python 3.10+ on macOS, Linux, or Windows.
+
+## Setup
+
+You need a Google Gemini API key — grab a free one at [aistudio.google.com](https://aistudio.google.com/app/apikey).
+
+```bash
+relay --set-key
+```
+
+(Paste at the hidden prompt — Cmd+V / Ctrl+V works even though nothing visibly happens.)
+
+Or set the `GEMINI_API_KEY` environment variable, which takes precedence over the stored config.
+
+## Use
+
+```bash
+relay
+```
+
+Type to chat. Relay can read files, search your filesystem, run shell commands, and write files on its own when the conversation calls for it.
+
+### Commands
+
+| command | action |
+|---|---|
+| `/help` | show command list |
+| `/exit`, `/quit` | leave |
+| `/clear` | reset the conversation |
+| `/cls` | clear the screen, keep the conversation |
+| `/model <name>` | switch model (e.g. `gemini-2.5-pro`) |
+| `/system <text>` | replace the system instruction |
+| `/cwd <path>` | change working directory |
+| `/save <path>` | save the transcript to a file |
+
+### Tools the assistant uses automatically
+
+`list_directory` · `read_file` · `glob_files` · `grep_files` · `write_file` · `run_shell`
+
+## Safety
+
+Relay gives the model direct shell access on your machine. It will run commands and modify files without asking. Don't point it at machines you don't own, and consider reviewing the conversation as it runs.
+
+## License
+
+MIT

cw_relay-0.1.0/README.md

@@ -0,0 +1,62 @@
+# relay
+
+A Claude Code-style terminal chatbot, powered by Google Gemini, with direct file and shell access.
+
+```
+  ┌─────────────────────────────────────────┐
+  │   relay · terminal chat (Gemini)        │
+  └─────────────────────────────────────────┘
+```
+
+## Install
+
+```bash
+pip install relay-cli
+```
+
+Python 3.10+ on macOS, Linux, or Windows.
+
+## Setup
+
+You need a Google Gemini API key — grab a free one at [aistudio.google.com](https://aistudio.google.com/app/apikey).
+
+```bash
+relay --set-key
+```
+
+(Paste at the hidden prompt — Cmd+V / Ctrl+V works even though nothing visibly happens.)
+
+Or set the `GEMINI_API_KEY` environment variable, which takes precedence over the stored config.
+
+## Use
+
+```bash
+relay
+```
+
+Type to chat. Relay can read files, search your filesystem, run shell commands, and write files on its own when the conversation calls for it.
+
+### Commands
+
+| command | action |
+|---|---|
+| `/help` | show command list |
+| `/exit`, `/quit` | leave |
+| `/clear` | reset the conversation |
+| `/cls` | clear the screen, keep the conversation |
+| `/model <name>` | switch model (e.g. `gemini-2.5-pro`) |
+| `/system <text>` | replace the system instruction |
+| `/cwd <path>` | change working directory |
+| `/save <path>` | save the transcript to a file |
+
+### Tools the assistant uses automatically
+
+`list_directory` · `read_file` · `glob_files` · `grep_files` · `write_file` · `run_shell`
+
+## Safety
+
+Relay gives the model direct shell access on your machine. It will run commands and modify files without asking. Don't point it at machines you don't own, and consider reviewing the conversation as it runs.
+
+## License
+
+MIT

cw_relay-0.1.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "cw-relay"
+version = "0.1.0"
+description = "A Claude Code-style terminal chatbot powered by Gemini, with file and shell access."
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.10"
+authors = [{ name = "Casper White" }]
+keywords = ["cli", "chat", "gemini", "ai", "terminal", "assistant"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: OS Independent",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Utilities",
+]
+dependencies = [
+    "google-genai>=0.3.0",
+    "rich>=13.0.0",
+]
+
+[project.scripts]
+relay = "relay.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/casperwhite-commits/relay"
+Issues = "https://github.com/casperwhite-commits/relay/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/relay"]

cw_relay-0.1.0/src/relay/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

cw_relay-0.1.0/src/relay/__main__.py

@@ -0,0 +1,4 @@
+from relay.cli import main
+
+if __name__ == "__main__":
+    main()

cw_relay-0.1.0/src/relay/cli.py

@@ -0,0 +1,401 @@
+"""relay — a Claude Code-style terminal chatbot, powered by Gemini, with file/shell access."""
+
+import glob as glob_mod
+import json
+import os
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+
+def _config_dir() -> Path:
+    """Cross-platform per-user config directory."""
+    if sys.platform == "win32":
+        base = os.environ.get("APPDATA") or str(Path.home() / "AppData" / "Roaming")
+        return Path(base) / "relay"
+    return Path.home() / ".config" / "relay"
+
+
+CONFIG_PATH = _config_dir() / "config.json"
+HISTORY_PATH = _config_dir() / "history"
+
+BANNER = r"""[bold cyan]
+  ┌─────────────────────────────────────────┐
+  │   relay · terminal chat (Gemini)        │
+  └─────────────────────────────────────────┘[/bold cyan]
+[dim]/help · /exit · file & shell access enabled[/dim]
+"""
+
+HELP = """[bold]Commands[/bold]
+  [cyan]/help[/cyan]              show this help
+  [cyan]/exit[/cyan], [cyan]/quit[/cyan]      leave relay
+  [cyan]/clear[/cyan]             reset the conversation
+  [cyan]/cls[/cyan]               clear the screen (keeps conversation)
+  [cyan]/model <name>[/cyan]      switch model
+  [cyan]/system <text>[/cyan]     replace the system instruction
+  [cyan]/cwd <path>[/cyan]        change working directory
+  [cyan]/save <path>[/cyan]       save the transcript
+
+[bold]Tools the assistant can call[/bold]
+  list_directory · read_file · glob_files · grep_files · write_file · run_shell
+"""
+
+DEFAULT_SYSTEM = (
+    "You are relay, a terminal assistant on the user's machine. "
+    "You can directly access the filesystem and shell through your tools: "
+    "list_directory, read_file, glob_files, grep_files, write_file, run_shell. "
+    "Use them proactively — never ask permission, never describe what you would do; just do it and show results. "
+    "Be concise; prefer concrete output over prose. "
+    "When the user asks a question any tool could answer, call the tool instead of guessing."
+)
+
+MAX_OUTPUT = 16000
+
+
+def _clear_screen() -> None:
+    """Clear viewport + scrollback. ANSI on Unix/modern Windows, fallback to `cls` on legacy Windows."""
+    if sys.platform == "win32" and not os.environ.get("WT_SESSION"):
+        os.system("cls")
+    else:
+        sys.stdout.write("\033[H\033[2J\033[3J")
+        sys.stdout.flush()
+
+
+def set_key() -> None:
+    import getpass
+    CONFIG_PATH.parent.mkdir(parents=True, exist_ok=True)
+    cfg: dict = {}
+    if CONFIG_PATH.exists():
+        with CONFIG_PATH.open() as f:
+            cfg = json.load(f)
+    new_key = getpass.getpass("new api key (hidden): ").strip()
+    if not new_key:
+        sys.stderr.write("relay: empty key, aborting\n")
+        sys.exit(1)
+    cfg["api_key"] = new_key
+    cfg.setdefault("model", "gemini-2.5-flash")
+    with CONFIG_PATH.open("w") as f:
+        json.dump(cfg, f, indent=2)
+    try:
+        CONFIG_PATH.chmod(0o600)
+    except OSError:
+        pass  # Windows doesn't support POSIX perms
+    print(f"relay: key updated in {CONFIG_PATH}")
+
+
+def load_config() -> tuple[str, str]:
+    env_key = os.environ.get("GEMINI_API_KEY")
+    if CONFIG_PATH.exists():
+        with CONFIG_PATH.open() as f:
+            cfg = json.load(f)
+    else:
+        cfg = {}
+    key = env_key or cfg.get("api_key")
+    if not key:
+        sys.stderr.write(
+            "relay: no API key found.\n"
+            f"Run `relay --set-key` to save one, or set GEMINI_API_KEY in your environment.\n"
+        )
+        sys.exit(1)
+    return key, cfg.get("model", "gemini-2.5-flash")
+
+
+def _truncate(s: str, limit: int = MAX_OUTPUT) -> str:
+    if len(s) <= limit:
+        return s
+    return s[:limit] + f"\n\n[... {len(s) - limit} chars truncated ...]"
+
+
+# ─── tools exposed to the model ────────────────────────────────────────────
+
+def list_directory(path: str = ".") -> str:
+    """List files and subdirectories under `path`.
+
+    Args:
+        path: Filesystem path. Relative paths resolve against relay's current working dir.
+    """
+    p = Path(path).expanduser()
+    if not p.exists():
+        return f"error: {p} does not exist"
+    if not p.is_dir():
+        return f"error: {p} is not a directory"
+    rows = []
+    for entry in sorted(p.iterdir()):
+        kind = "dir " if entry.is_dir() else "file"
+        try:
+            size = str(entry.stat().st_size) if entry.is_file() else "-"
+        except OSError:
+            size = "?"
+        rows.append(f"{kind}  {size:>10}  {entry.name}")
+    return _truncate("\n".join(rows) if rows else "(empty)")
+
+
+def read_file(path: str) -> str:
+    """Read a text file's contents (capped at ~16KB). Refuses binary files.
+
+    Args:
+        path: Path to the file to read.
+    """
+    p = Path(path).expanduser()
+    if not p.exists():
+        return f"error: {p} does not exist"
+    if not p.is_file():
+        return f"error: {p} is not a regular file"
+    try:
+        data = p.read_bytes()
+        if b"\x00" in data[:2048]:
+            return f"error: {p} appears to be binary"
+        return _truncate(data.decode("utf-8", errors="replace"))
+    except OSError as e:
+        return f"error: {e}"
+
+
+def glob_files(pattern: str) -> str:
+    """Find files/dirs matching a glob pattern (supports ** for recursive).
+
+    Args:
+        pattern: Glob pattern, e.g. '**/*.py' or 'src/*.ts'.
+    """
+    try:
+        matches = sorted(glob_mod.glob(pattern, recursive=True))
+        return _truncate("\n".join(matches)) if matches else "(no matches)"
+    except Exception as e:
+        return f"error: {e}"
+
+
+def grep_files(pattern: str, path: str = ".") -> str:
+    """Recursively search for a regex pattern in files under `path`. Returns file:line:text.
+
+    Args:
+        pattern: Python regular expression.
+        path: Directory or file to search.
+    """
+    try:
+        regex = re.compile(pattern)
+    except re.error as e:
+        return f"error: invalid regex: {e}"
+    root = Path(path).expanduser()
+    if not root.exists():
+        return f"error: {root} does not exist"
+    files = [root] if root.is_file() else [p for p in root.rglob("*") if p.is_file()]
+    matches: list[str] = []
+    for f in files:
+        try:
+            with f.open("r", errors="replace") as fh:
+                for i, line in enumerate(fh, 1):
+                    if regex.search(line):
+                        matches.append(f"{f}:{i}:{line.rstrip()}")
+                        if len(matches) >= 200:
+                            matches.append("[... 200-match limit reached ...]")
+                            return _truncate("\n".join(matches))
+        except (OSError, UnicodeError):
+            continue
+    return _truncate("\n".join(matches)) if matches else "(no matches)"
+
+
+def write_file(path: str, content: str) -> str:
+    """Create or overwrite a file at `path` with `content`. Creates parent dirs if needed.
+
+    Args:
+        path: Destination file path.
+        content: Text to write.
+    """
+    p = Path(path).expanduser()
+    try:
+        p.parent.mkdir(parents=True, exist_ok=True)
+        p.write_text(content)
+        return f"wrote {len(content)} chars to {p}"
+    except OSError as e:
+        return f"error: {e}"
+
+
+def run_shell(command: str) -> str:
+    """Execute a shell command in the OS default shell. 60-second timeout.
+
+    Args:
+        command: Shell command string.
+    """
+    try:
+        r = subprocess.run(
+            command, shell=True, capture_output=True, text=True, timeout=60,
+        )
+        out = (r.stdout or "") + (r.stderr or "")
+        head = f"[exit {r.returncode}]\n" if r.returncode != 0 else ""
+        return _truncate(head + out) if out else f"[exit {r.returncode}] (no output)"
+    except subprocess.TimeoutExpired:
+        return "error: command timed out after 60s"
+    except Exception as e:
+        return f"error: {e}"
+
+
+TOOLS = [list_directory, read_file, glob_files, grep_files, write_file, run_shell]
+
+
+def _short(v) -> str:
+    if isinstance(v, str):
+        s = v.replace("\n", "\\n")
+        return repr(s if len(s) <= 60 else s[:57] + "...")
+    return repr(v)
+
+
+def main() -> None:
+    if len(sys.argv) > 1:
+        if sys.argv[1] in ("--set-key", "-k"):
+            set_key()
+            return
+        if sys.argv[1] in ("--version", "-V"):
+            from relay import __version__
+            print(f"relay {__version__}")
+            return
+        if sys.argv[1] in ("--help", "-h"):
+            print("Usage: relay [--set-key | --version | --help]\n\nRun `relay` with no args to start the chat.")
+            return
+
+    api_key, model = load_config()
+
+    try:
+        from google import genai
+        from google.genai import types as genai_types
+    except ImportError:
+        sys.stderr.write("relay: missing `google-genai`. Reinstall: pip install --upgrade relay-cli\n")
+        sys.exit(1)
+    try:
+        from rich.console import Console
+        from rich.markdown import Markdown
+        from rich.live import Live
+    except ImportError:
+        sys.stderr.write("relay: missing `rich`. Reinstall: pip install --upgrade relay-cli\n")
+        sys.exit(1)
+
+    try:
+        import readline
+        HISTORY_PATH.parent.mkdir(parents=True, exist_ok=True)
+        if HISTORY_PATH.exists():
+            readline.read_history_file(str(HISTORY_PATH))
+        readline.set_history_length(1000)
+    except Exception:
+        readline = None  # readline not available on Windows by default; that's fine
+
+    _clear_screen()
+
+    console = Console()
+    client = genai.Client(api_key=api_key)
+    system_instruction = DEFAULT_SYSTEM
+
+    def make_chat():
+        return client.chats.create(
+            model=model,
+            config=genai_types.GenerateContentConfig(
+                tools=TOOLS,
+                system_instruction=system_instruction,
+            ),
+        )
+
+    chat = make_chat()
+
+    def show_banner():
+        console.print(BANNER)
+        console.print(f"[dim]model:[/dim] [magenta]{model}[/magenta]   [dim]cwd:[/dim] [magenta]{os.getcwd()}[/magenta]\n")
+
+    show_banner()
+
+    def save_transcript(path_str: str) -> None:
+        path = Path(path_str).expanduser()
+        try:
+            with path.open("w") as out:
+                out.write(f"# system\n{system_instruction}\n\n")
+                for msg in chat.get_history():
+                    role = msg.role
+                    text = "".join((p.text or "") for p in (msg.parts or []) if hasattr(p, "text"))
+                    if text:
+                        out.write(f"# {role}\n{text}\n\n")
+            console.print(f"[dim]saved transcript to {path}[/dim]\n")
+        except OSError as e:
+            console.print(f"[red]save failed:[/red] {e}\n")
+
+    while True:
+        try:
+            user_input = console.input("[bold green]›[/bold green] ")
+        except (EOFError, KeyboardInterrupt):
+            console.print("\n[dim]bye.[/dim]")
+            break
+        if not user_input.strip():
+            continue
+
+        if user_input.startswith("/"):
+            parts = user_input.strip().split(maxsplit=1)
+            cmd, arg = parts[0].lower(), (parts[1] if len(parts) > 1 else "")
+            if cmd in ("/exit", "/quit"):
+                console.print("[dim]bye.[/dim]")
+                break
+            elif cmd == "/help":
+                console.print(HELP)
+            elif cmd == "/clear":
+                chat = make_chat()
+                _clear_screen()
+                show_banner()
+            elif cmd == "/cls":
+                _clear_screen()
+            elif cmd == "/model":
+                if not arg:
+                    console.print(f"[dim]current model:[/dim] [magenta]{model}[/magenta]\n")
+                else:
+                    model = arg.strip()
+                    chat = make_chat()
+                    console.print(f"[dim]model →[/dim] [magenta]{model}[/magenta] [dim](conversation reset)[/dim]\n")
+            elif cmd == "/system":
+                system_instruction = arg or DEFAULT_SYSTEM
+                chat = make_chat()
+                console.print("[dim]system instruction updated (conversation reset)[/dim]\n")
+            elif cmd == "/cwd":
+                target = Path(arg or str(Path.home())).expanduser()
+                try:
+                    os.chdir(target)
+                    console.print(f"[dim]cwd →[/dim] [magenta]{os.getcwd()}[/magenta]\n")
+                except OSError as e:
+                    console.print(f"[red]cd failed:[/red] {e}\n")
+            elif cmd == "/save":
+                if not arg:
+                    console.print("[red]usage:[/red] /save <path>\n")
+                else:
+                    save_transcript(arg)
+            else:
+                console.print(f"[red]unknown command:[/red] {cmd}  (try /help)\n")
+            continue
+
+        buf = ""
+        try:
+            stream = chat.send_message_stream(user_input)
+            with Live(Markdown(""), console=console, refresh_per_second=20, vertical_overflow="visible") as live:
+                for chunk in stream:
+                    for cand in (chunk.candidates or []):
+                        content = getattr(cand, "content", None)
+                        if not content or not getattr(content, "parts", None):
+                            continue
+                        for part in content.parts:
+                            text = getattr(part, "text", None)
+                            if text:
+                                buf += text
+                                live.update(Markdown(buf))
+                            fc = getattr(part, "function_call", None)
+                            if fc and fc.name:
+                                args = dict(fc.args or {})
+                                args_str = ", ".join(f"{k}={_short(v)}" for k, v in args.items())
+                                live.console.print(f"[dim cyan]  ↳ {fc.name}({args_str})[/dim cyan]")
+        except KeyboardInterrupt:
+            console.print("\n[dim]— interrupted —[/dim]\n")
+        except Exception as e:
+            console.print(f"[red]error:[/red] {e}\n")
+            continue
+
+        console.print()
+        if readline:
+            try:
+                readline.write_history_file(str(HISTORY_PATH))
+            except Exception:
+                pass
+
+
+if __name__ == "__main__":
+    main()