G4Term

Gemma 4 Terminal - a free, terminal-based autonomous coding agent powered by Google's Gemma / Gemini models on the Google AI Studio free tier, with support for HuggingFace Inference Providers, Kaggle Models, and local Ollama.

Install

pip install -e .
export GEMINI_API_KEY="your-key-here"   # from Google AI Studio, free tier

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

pip 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

Interactive mode

Run g4term with no instruction to enter the REPL. Arrow-key history persists across sessions (~/.g4term/history). Slash commands:

/model <name>       switch model (e.g. gemma-4-31b-it)
/backend <name>     switch backend (google, ollama, huggingface, kaggle)
/yes on|off         toggle auto-approve
/think on|off       toggle deep thinking mode
/fix                enter test-and-fix loop
/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
/agent <type>       switch agent type (build, plan, explore)
/permissions        show or set permission profile
/models             list available models
/auto on|off        toggle auto-model-routing
/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	Description
read_local_file	Read file contents with optional line range
list_directory	List directory (optional recursive with depth limit)
write_local_file	Create/overwrite a file (for new files only)
patch_file	Search-and-replace edit (preferred for existing files)
grep_code	Regex search across project files
glob_files	Find files by glob pattern
run_terminal_command	Run shell commands
revert_changes	Undo file changes since the last snapshot
snapshot_list	List recent file snapshots
snapshot_diff	Show diff between current files and a snapshot
ask_user	Ask a clarifying question mid-task
git_status	Show working tree status
git_diff	Show unstaged changes
git_diff_staged	Show staged changes
git_add	Stage files for commit
git_commit	Stage all + commit
git_checkout	Create/switch branch
git_log	Recent commits
browse	Fetch a URL (auto-selects best backend)
spawn_subagent	Single subagent in parallel
spawn_subagents	Multiple subagents in parallel

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)

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 text extraction → w3m/lynx → playwright.

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

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"]')

Subagents auto-approve their actions. Useful for parallel research, multi-file analysis, and independent checks.

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 pipeline
---

# 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)
  browser.py      # Conversational browsing session state
  cli.py          # argparse entry: one-shot, REPL, config
  compaction.py   # Context compaction
  config.py       # API keys, settings, model config
  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
  permissions.py  # Pattern-based permission profiles
  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)