git-grass Developer Documentation

What you can do with git-grass

Explore core capabilities designed to protect developer well-being without compromising Git repository integrity.

Prerequisites

git-grass is designed to run locally with zero native toolchain dependencies:

• Node.js: Version 18.0.0 or later (verified across Node 18 LTS, 20 LTS, and 22).
• Git: Version 2.20 or later accessible in your operating system PATH.
• Operating System: macOS (Apple Silicon / Intel), Linux (glibc and musl), or Windows 10/11 (PowerShell and Git Bash).
• Local Network: Workstation and mobile device connected to the same Wi-Fi router or personal mobile hotspot for QR session pairing.
• Zero Local AI Requirements: No Ollama, no Docker, no Python, and no GPU setup required.

Quickstart Tutorial

Get up and running in under 60 seconds with three simple steps:

# 1. Install CLI globally
npm install -g git-grass

# 2. Enter any Git repository
cd my-project

# 3. Initialize git-grass break gate
git grass init

Once initialized, work on your project normally. When you reach your configured focus threshold and run git commit, git-grass prompts you to step outside, provides a QR code, and unlocks automatically upon your return.

CLI Installation Options

Choose the installation path that matches your development workflow:

Option A: Global NPM Package (Recommended)

npm install -g git-grass

Option B: Ephemeral Execution via NPX

npx git-grass init

Option C: Clone & Build from Source

git clone https://github.com/sn3hhaa/git-grass.git
cd git-grass
npm install
npm run build
npm link

CLI Commands Reference

Every command supports --help for inline usage flags. Below is a comprehensive breakdown of all commands.

$ git grass init
[git-grass] Initializing repository hook gate...
[git-grass] Created .git-grass/config.json with default thresholds.
[git-grass] Installed hook wrapper into .git/hooks/pre-commit.
[git-grass] Initialization complete. Your next commit will verify focus interval.

$ git grass status
[git-grass] Status:
  Last break completed: 74 minutes ago
  Configured interval:  60 minutes
  Minimum walk duration: 10 minutes
  Break due:            YES (next git commit will require outdoor break)
  Active session server: None (ready)

$ git commit -m "feat(auth): add OAuth2 provider"
[git-grass] Focus interval exceeded (74m >= 60m).
[git-grass] Commit paused. Staged tree SHA-1 fingerprinted: 4b825dc642cb...
[git-grass] Scan QR code with your phone or visit:
  http://192.168.1.48:4242/session/grass-7c42
[git-grass] Waiting for outdoor break completion (min: 10m)...

git grass config breakIntervalMinutes 90     # Set 90m focus block
git grass config defaultDurationMinutes 15   # Require 15m outdoor walk
git grass config autoPush true               # Auto-push after commit unlock

$ git grass doctor
[doctor] Running environment diagnostic:
  [PASS] Node.js runtime: v20.11.0 (>= 18.0.0 required)
  [PASS] Git binary: 2.43.0 in PATH
  [PASS] Repository root: C:/Users/Admin/projects/cache (worktree active)
  [PASS] Hook status: .git/hooks/pre-commit contains git-grass gate
  [PASS] Network interface: 192.168.1.48 (IPv4 LAN address bound)
  [PASS] Offline catalog: 15 curated challenges loaded
  [PASS] Hosted AI backend: Render service healthy (HTTP 200)
All diagnostics passed. System ready.

$ git grass challenge --category systems
[git-grass] Challenge generated:
  Title:      Kinetic Topology & Flow Walk
  Category:   systems
  Duration:   15 minutes (Phone-Free)
  Instructions:
    1. Step outside into open air for 15 minutes.
    2. Walk toward a pathway intersection or trail bifurcation.
    3. Observe how physical pathways route pedestrian flow without centralized locks.
  Reflection:
    "How does physical pedestrian queueing compare to partition bottlenecks in your cluster?"

Tech Stack & How It Was Built

git-grass is engineered with a strict minimal-dependency philosophy to guarantee zero runtime baggage and maximum developer trust:

• TypeScript & Node.js ES Modules: Strict typing across all CLI commands, schemas, and network transports. Zero build compilation needed at user runtime.
• Git Plumbing Architecture: Instead of fragile porcelain scraping, git-grass interacts with low-level Git plumbing: git write-tree to compute index SHAs, git rev-parse for repository boundaries, and atomic commit verification.
• Express & Web Break Gateway: Serves a cryptographically authenticated Break Gateway both locally on port 4242 and via the cloud gateway (https://git-grass.onrender.com/break/) with base64url-encoded AI mission payloads.
• Zod Runtime Schema Validation: Every generated outdoor activity is checked against OutdoorChallengeSchema and an anti-screen word filter before presentation to ensure safety, duration (>= 10m), and phone-free compliance.
• Multi-Provider Cloud AI (Backboard + Thinking Machines Tinker + Render): Uses Backboard's 3-step stateful Assistant & Thread API (POST /assistants → POST /threads → POST /threads/{id}/messages) and Thinking Machines Tinker open-weight sampling (Qwen/Qwen3-30B-A3B) deployed on Render with 1-hour TTL caching and sliding-window rate limiting.

Staged Index Fingerprinting

When a break is enforced, git-grass immediately executes git write-tree to compute the cryptographic SHA of your current staging index.

When you return from outside and submit your commit from your phone, git-grass re-verifies the index hash before committing. If any staged file was modified or altered while you were outside, the commit halts immediately to prevent committing unexpected changes.

Break Gateway & Mobile Pairing Architecture

When a break triggers, git-grass generates a cryptographic QR code and Break Gateway URL (https://git-grass.onrender.com/break/?session=...) alongside a local LAN listener (http://192.168.x.x:4242). The generated AI challenge is embedded directly in the signed URL so your phone receives the exact repository-specific mission even on mobile data outdoors.

Git Hook Architecture & Reentrancy Guard

When your outdoor break completes and git-grass triggers the final commit, it prevents infinite recursive hook loops using an internal environment flag:

if [ -n "$GIT_GRASS_BYPASS_TOKEN" ]; then
  exit 0
fi

Cloud AI Setup (Render + Backboard + Thinking Machines Tinker)

git-grass connects to a lightweight cloud API deployed on Render (or directly via your local .env), using Backboard and Thinking Machines Tinker to generate project-aware outdoor prompts without any local GPU or heavy runtime:

• Backboard Stateful AI Engine: Automatically creates a dedicated Assistant and Thread via https://app.backboard.io/api to synthesize physical outdoor analogies tailored to your repository name and detected files.
• Thinking Machines Tinker Provider: Supports open-weight model sampling (Qwen/Qwen3-30B-A3B) via src/hosted/providers/tinker.ts.
• Strict Privacy: Only top-level file names, extension types, and project domain metadata are analyzed. Your private source code and Git history never leave your machine.

Deploying via render.yaml

1. Connect the repository to Render.
2. Deploy the Static Site (Publish Directory: site) and Web Service (npm run start:hosted), or use render.yaml Blueprint.
3. Add BACKBOARD_API_KEY (and optional TINKER_API_KEY) in your Render Environment Variables or local .env file.

Bundled Offline Catalog

git-grass is offline-first. If no internet connection is available, or if the hosted inference provider is unreachable, git-grass instantaneously switches to the bundled library of curated engineering challenges spanning systems, web, ML, graphics, and audio.

Emergency Commit Bypass

If production is down and an urgent hotfix or security patch must be deployed without taking a break, use Git's standard pre-commit bypass flag:

git commit --no-verify -m "fix: critical production hotfix"

Troubleshooting Guide & FAQ