Install

Linux / macOS

# From PyPI (recommended)
pipx install g4term

# Or from source (for development)
git clone https://github.com/CYBWithFlourish/g4term.git
cd g4term
pipx install -e .

Windows

pipx install g4term

Note: Some features (screenshot, pyautogui) may have limited support on Windows. The CLI and all core features work fine.

Set your API key

export GEMINI_API_KEY="your-key-here"   # from Google AI Studio, free tier
# Or on Windows:
# set GEMINI_API_KEY=your-key-here
# Or in PowerShell:
# $env:GEMINI_API_KEY = "your-key-here"

Or set it from inside G4Term: /api your-key-here

Install optional dependencies

# Local Ollama backend
pipx install g4term[ollama]

# HuggingFace Inference Providers backend
pipx install g4term[huggingface]

# Kaggle Models backend (requires GPU, ~20 GB download)
pipx install g4term[kaggle]

# All backends
pipx install g4term[all]

Use

# One-shot
g4term "fix the syntax error in app.py"

# Interactive REPL (like Claude Code / OpenCode)
g4term

# Auto-approve writes and shell commands for this run
g4term --yes "run the test suite and fix any failures"

# Override model
g4term --model gemma-4-31b-it "refactor this module"
g4term --model gemini-2.5-flash "quick lint check"

# Lighter/faster model, thinking off (default)
g4term --fast "quick syntax check on app.py"

# Dense model + deep reasoning, for a hard refactor
g4term --think "restructure this module to remove the circular import"

# Test-and-fix loop (auto-detects test framework)
g4term --fix

# Resume a previous session
g4term --session <session-id>

# Browse a URL in conversational browse mode
g4term --browse https://docs.python.org/3

# Permission profile
g4term --profile conservative "analyze the codebase"

# ═══ Backends ═══════════════════════════════════════════════════════

# Local Ollama model
g4term --local "fix the syntax error"
g4term --local --ollama-model gemma2:7b "check code quality"

# HuggingFace Inference Providers (requires HF_TOKEN)
export HF_TOKEN="hf_..."
g4term # then /backend huggingface

# Kaggle Models (uses kagglehub + transformers, no auth for public models)
g4term # then /backend kaggle

# Run as an MCP server (for VS Code / Claude Desktop integration)
g4term --mcp

# ═══ Persistent config ══════════════════════════════════════════════

g4term config --model gemma-4-31b-it
g4term config --auto-approve on
g4term config --profile conservative
g4term config --lint "ruff check"
g4term config --test "pytest"

Backends

Backend	How to use	Auth	Default model
google	(default)	GEMINI_API_KEY env	gemma-4-26b-a4b-it
ollama	--local or /backend ollama	Ollama running locally	gemma2
huggingface	/backend huggingface	HF_TOKEN env	gemma-4-12b-it
kaggle	/backend kaggle	KAGGLE_KEY env or kaggle.json	gemma-4-2b-it

Switch at runtime: /backend google|ollama|huggingface|kaggle

Google AI Studio (default)

Free tier: gemma-4-26b-a4b-it (MoE, fast) and gemma-4-31b-it (dense, better reasoning). Gemini models (gemini-2.5-flash, gemini-2.5-pro) also available.

Get a key: https://aistudio.google.com/apikey

Local Ollama

pipx install ollama
ollama pull gemma2
g4term --local

HuggingFace Inference Providers

Uses the OpenAI-compatible endpoint at https://router.huggingface.co/v1. Supports Gemma 4, Llama, Qwen, and other open models.

export HF_TOKEN="hf_..."
g4term
# in REPL:
/backend huggingface

Kaggle Models

Runs Gemma 4 locally via kagglehub + transformers. No auth required for public models (but optional KAGGLE_KEY / ~/.kaggle/kaggle.json for gated models). Downloads weights on first use (~20 GB for the 26B MoE).

g4term
/backend kaggle
/model gemma-4-26b-a4b-it

Python library

Use G4Term programmatically from your own Python scripts:

from g4term.agent import G4TermAgent

# Build an agent (Google AI Studio backend by default)
agent = G4TermAgent(
    model="gemma-4-26b-a4b-it",
    temperature=0.1,
    approve=lambda desc: True,        # auto-approve all actions
    thinking=False,
    backend="google",                 # or "ollama", "kaggle", "huggingface"
)

# Run a one-shot instruction
result = agent.run("Read src/main.py and explain what it does")
print(result)

# Use individual tools directly
from g4term.tools import read_local_file, grep_code, search_web

content = read_local_file("src/main.py")
matches = grep_code("TODO", include="*.py")
web_results = search_web("python async patterns")

# Persistent memory
from g4term.memory import get_memory_store
store = get_memory_store("/path/to/project")
store.save("architecture", "We use a plugin pattern")
results = store.recall("how do plugins work?")

# Custom tool plugins
from g4term.plugin_loader import discover_plugins, get_plugin_status
plugins = discover_plugins()
print(get_plugin_status())

# Multi-agent orchestration
from g4term.orchestrator import Orchestrator
orch = Orchestrator(agent)
report = orch.execute_with_review("Refactor auth.py to use JWT")
print(report)

Interactive mode

Run g4term with no instruction to enter the REPL. Arrow-key history persists across sessions (~/.g4term/history). Type @ to get a file autocomplete dropdown. Slash commands:

/model <name>       switch model (e.g. gemma-4-31b-it)
/backend <name>     switch backend (google, ollama, huggingface, kaggle)
/agent <type>       switch agent type (build, plan, explore, orchestrator)
/yes on|off         toggle auto-approve
/think on|off       toggle deep thinking mode
/auto on|off        toggle auto-model-routing
/fix                enter autonomous test-fix loop (with error parsing)
/orchestrate <task>  break down complex tasks with multi-agent orchestration
/computer           enter computer use mode (browser + desktop automation)
/browse [url]       enter browse mode, optionally opening a URL
/sessions           list saved sessions
/resume <id>        resume a previous session
/context            show token/context usage
/skills             list available skills
/skill <name>       load and run a skill
/api <key>          set your Google AI Studio API key
/permissions        show or set permission profile
/models             list available models
/hooks              configure pre/post tool hooks
/delete <id>        delete a session
/clear-sessions     delete all sessions
/clear              start a fresh conversation
/help               list commands
/exit               leave

Tools

Tool	Category	Description
read_local_file	File	Read file contents with optional line range
list_directory	File	List directory (optional recursive with depth limit)
write_local_file	File	Create/overwrite a file (for new files only)
patch_file	File	Search-and-replace edit (preferred for existing files)
grep_code	Search	Regex search across project files
glob_files	Search	Find files by glob pattern
run_terminal_command	Shell	Run shell commands
revert_changes	Snapshot	Undo file changes since last snapshot
snapshot_list	Snapshot	List recent file snapshots
snapshot_diff	Snapshot	Show diff between current files and a snapshot
ask_user	Utility	Ask a clarifying question mid-task
git_status_cmd	Git	Show working tree status
git_diff_cmd	Git	Show unstaged changes
git_diff_staged_cmd	Git	Show staged changes
git_add_cmd	Git	Stage files for commit
git_commit_cmd	Git	Stage all changes and commit
git_checkout_cmd	Git	Create or switch branches
git_log_cmd	Git	Show recent commit log
browse	Web	Fetch a URL (auto-selects best backend)
search_web	Web	Search DuckDuckGo — no API key needed
spawn_subagent	Agent	Single subagent in parallel
spawn_subagents	Agent	Multiple subagents in parallel
run_python	Code	Run Python code inline
run_node	Code	Run JavaScript/Node.js code inline
gh_pr_create	GitHub	Create a pull request
gh_pr_view	GitHub	View a pull request
gh_issue_list	GitHub	List issues (filter by label/state)
gh_issue_view	GitHub	View a specific issue
gh_ci_status	GitHub	Check CI status for a branch
memory_save	Memory	Store a persistent project memory
memory_recall	Memory	Semantic search across memories
memory_forget	Memory	Delete a memory entry by id
memory_list	Memory	List all stored memory keys
plugin_status	Plugin	List loaded custom tool plugins
screenshot	Vision	Capture desktop screen (mss / pyautogui)
analyze_image	Vision	Reference an image for model analysis
navigate	Browser	Open URL via Playwright
click	Browser	Click element via CSS selector
type_text	Browser	Type text into an element
browser_screenshot	Browser	Screenshot the browser page
run_js	Browser	Execute JavaScript in page context
mouse_move	Desktop	Move mouse to screen coordinates
mouse_click	Desktop	Click at a screen position
keyboard_type	Desktop	Type text via the desktop keyboard

@file References

Type @ followed by a file path in the REPL to autocomplete and inline file contents:

g4term> fix the bug in @src/utils.py
                         └── dropdown shows matching files as you type

On submit, @path is replaced with a <file> block containing the contents (truncated at 50 lines with a remaining-line-count notice). Non-file refs like @property are left untouched. Requires prompt_toolkit (bundled).

Precision Editing

Instead of overwriting entire files, use patch_file for surgical edits:

patch_file(filepath="app.py", old_text="def old_name():", new_text="def new_name():")

The agent shows a diff preview before applying changes.

Search

grep_code(pattern="TODO", include="*.py")
glob_files(pattern="src/**/*.ts")
list_directory(path=".", recursive=True)

Git Integration

git_status()
git_checkout("feature/my-branch")
git_add("src/")
git_commit("feat: add new feature")
git_log(n=5)

Web Browsing

The browse tool fetches web pages with automatic backend selection:

browse("https://docs.python.org/3/library/asyncio.html")
browse("https://github.com", goal="find the README section")

Backends tried in order: requests + stdlib HTML text extraction → w3m/lynx → playwright.

Web Search

search_web("python asyncio vs trio comparison", max_results=5)

Searches DuckDuckGo's HTML endpoint - no API key needed, zero dependencies.

GitHub Integration

All tools use the gh CLI (install from https://cli.github.com/):

gh_pr_create(title="Fix login bug", body="...", base="main")
gh_pr_view(42)
gh_issue_list(label="bug", state="open")
gh_ci_status()

Project Memory

Persistent semantic memory stored in .g4term/memory/. TF-IDF recall, zero deps:

memory_save(key="project-architecture", value="We use a plugin system with register() pattern")
memory_recall(query="how do we handle plugins?")
memory_list()

Custom Plugins

Drop .py files in ~/.g4term/tools/ - auto-discovered on session start:

# ~/.g4term/tools/my_tools.py
def register():
    return {"my_tool": my_tool_fn}

def my_tool_fn(param: str) -> str:
    """Description of my custom tool."""
    return f"result: {param}"

Computer Use & Vision

Desktop screenshot and browser automation:

screenshot()                                    # capture full screen
screenshot("100,200,800,600")                   # capture region
analyze_image("screenshot.png", "what do you see?")
navigate("https://example.com")                 # requires Playwright
click("#submit-btn")
type_text("#search", "query text")
browser_screenshot()
run_js("document.title")
mouse_move(500, 300)                            # requires pyautogui
mouse_click(500, 300)
keyboard_type("hello")

analyze_image returns an <image> tag that the backend resolves to image bytes for the model to analyze (works with Gemma 4's native vision support).

MCP Server

Run G4Term as an MCP (Model Context Protocol) server:

g4term --mcp

Exposes all tools (read, write, patch, search, git, browse) via JSON-RPC on stdin/stdout. Connect from VS Code, Claude Desktop, or any MCP client.

Subagents & Orchestration

Spawn isolated workers that run in parallel with full tool access:

spawn_subagent(task="analyze auth.py and summarize security issues")
spawn_subagents(tasks='["check coverage", "lint all files", "browse API docs"]')

For complex tasks, use multi-agent orchestration:

/orchestrate refactor the auth module to use JWT instead of sessions

The orchestrator breaks the task down, spawns executor subagents, reviews their output, and iterates on failures until quality standards are met.

Autonomous Fix Loop

g4term --fix
# or in REPL: /fix

Runs the test command, parses errors (tracebacks, pytest failures, generic file:line: patterns), reads the failing files, generates targeted fixes, and loops until tests pass.

Configuration

Project-local settings

.g4term/settings.json:

{
    "test_command": "pytest",
    "lint_command": "ruff check",
    "ignore_patterns": ["node_modules", ".venv"]
}

Project instructions

AGENTS.md in the project root:

# Project Instructions
- Always use type hints
- Run `pytest` before committing
- Don't modify config files without asking

Or .g4term/config.md for additional configuration.

Hooks

.g4term/hooks.json to run commands before/after tool execution:

{
    "pre_tool": [
        {"match_tool": "write_local_file", "command": "ruff check {filepath}"}
    ],
    "post_tool": [
        {"match_tool": "patch_file", "command": "black {filepath}"}
    ]
}

Skills

Create markdown skill files in .g4term/skills/ or ~/.g4term/skills/:

---
description: Run the full CI/CD pipxeline
---

# Deploy Skill
1. Run tests
2. Check git status
3. Bump version
4. Build and upload

Invoke with /skill deploy.

Sessions

Sessions are saved automatically in ~/.g4term/sessions/ as JSONL files. List: /sessions Resume: /resume <id>

Permissions

Pattern-based permission system for fine-grained tool access control.

Profile	Description
permissive	Allow everything - no prompts
conservative	Auto-allow reads/search/browse, ask for writes/commands (default)
restrictive	Ask for everything, deny .env/.key/.pem files

CLI: g4term --profile conservative REPL: /permissions conservative Persist: g4term config --profile conservative

How it works

[You type an instruction]
        │
        ▼
[Gemma/Gemini plans + calls tools]  <── system prompt + AGENTS.md
        │
        ▼
[Local tool executes: read/write/patch/grep/git/run/browse]
        │
   (write/patch/run → [Y/n] approval unless --yes)
        │
        ▼
[Tool output fed back to the model]
        │
        ▼
[Repeat until no more tool calls, then summarizes]

Project layout

g4term/
  __init__.py     # version
  agent.py        # ReAct loop with context pruning and hooks
  agents.py       # Named agent types (build, plan, explore, orchestrator)
  browser.py      # Conversational browsing session state
  cli.py          # argparse entry: one-shot, REPL, config
  compaction.py   # Context compaction
  computer.py     # Computer use (screenshot, browser, desktop automation)
  config.py       # API keys, settings, model config
  fix_loop.py     # Autonomous test-fix loop with structured error parsing
  fuzzy_match.py  # Fuzzy matching utility
  hooks.py        # Pre/post tool hooks
  huggingface.py  # HuggingFace Inference Providers backend
  kaggle.py       # Kaggle Models backend (kagglehub + transformers)
  local.py        # Ollama local model backend
  lsp.py          # LSP code intelligence integration
  mcp_server.py   # MCP (Model Context Protocol) server
  memory.py       # Persistent project memory (TF-IDF recall)
  orchestrator.py # Multi-agent orchestration with review gates
  permissions.py  # Pattern-based permission profiles
  plugin_loader.py# Custom tool plugin discovery
  session.py      # Session persistence (JSONL)
  skills.py       # Skills discovery and loading
  snapshot.py     # File snapshot/restore
  tools.py        # All tools: filesystem, search, git, shell, web
  ui.py           # Rich-based panels, syntax highlighting, diffs
  validation.py   # Tool call validation
.g4term/
  settings.json   # Project-local settings
  config.md       # Additional agent instructions
  hooks.json      # Tool lifecycle hooks
  skills/         # Skill files
AGENTS.md         # Project root agent instructions
pyproject.toml    # Packaging + g4term console script
Dockerfile        # Container build

Roadmap

• patch_file for search-and-replace editing
• grep_code and glob_files for codebase search
• Git integration (status, diff, commit, checkout, log)
• Session persistence with resume
• Skills system
• Hooks for pre/post tool execution
• AGENTS.md and project-local config
• Test-and-fix loop mode
• Conversational web browsing with smart backend selection
• Subagent spawning (parallel multi-agent task solving)
• LSP integration for code intelligence
• Multi-model routing
• MCP server support
• Kaggle Models API integration
• HuggingFace Inference Providers backend
• Containerized deployment (Docker)
• Web search (DuckDuckGo, zero deps)
• Inline code execution (Python + Node.js)
• GitHub integration (PRs, issues, CI)
• Persistent project memory (TF-IDF semantic recall)
• Custom tool plugins (auto-discovered from ~/.g4term/tools/)
• Visual understanding (screenshot + image analysis via Gemma 4 vision)
• Computer use (Playwright browser automation + pyautogui desktop)
• Multi-agent orchestration (decompose → execute → review → fix → report)
• Autonomous fix loop (structured error parsing, targeted fixes)
• @file autocomplete with dropdown + inline file resolution