Introducing git-grass: A Git-Native CLI Tool & Mobile Gateway That Enforces Real-World Outdoor Breaks Before git commit

Sneha Tiwari — Sun, 11 Oct 2026 06:58:33 +0000

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 1: Touch Grass

"Your AI can write the code. It can't touch grass."

🌐 Official Website: https://git-grass.onrender.com
📚 Technical Documentation: https://git-grass.onrender.com/docs/
📦 npm Package Registry: https://www.npmjs.com/package/git-grass
💻 GitHub Repository: https://github.com/sn3hhaa/git-grass

⚡ Quick Install & Setup

npm install -g git-grass
git grass init

What I Built

Modern AI coding assistants (Cursor, Copilot, Claude, Gemini, Antigravity) have 10x'd our coding velocity — which ironically means developers now sit glued to their monitors for hours without a single physical break.

Existing break reminder apps and Pomodoro timers fail developers for three fundamental reasons:

Reflexive Dismissal: Standard desktop notification banners are reflexively clicked away with Esc in 200 milliseconds when you are deep in debugging.
Mid-Flow Interruption: Timers that go off while you are halfway through writing a function break your mental context.
Screen-Based "Breaks": Even when developers step away from their IDE, they immediately scroll social feeds on their phones — offering zero ocular or cognitive recovery.

git-grass is an open-source, zero-cost, Git-native CLI tool, npm package, and mobile Break Gateway built for software engineers and AI-assisted builders. Instead of interrupting you mid-thought with pop-up notifications, git-grass hooks directly into your natural engineering milestone: git commit.

Your AI agent can write the code, pass the linter, and stage the diff — but only a human can step outside and touch grass to unlock the commit.

How It Gets Developers Off the Screen and Into the World:

Git-Native Pre-Commit Gate: When your configured continuous coding interval expires, your next git commit is safely paused while preserving your staged index cryptographic fingerprint (git write-tree).
Project-Aware AI Outdoor Missions: git-grass inspects your repository's domain (systems, web, gamedev, ml, or audio) and generates a 3-step physical observation challenge tailored to what you are building — such as observing real-world street routing & drainage redundancy when building backend systems, or studying natural sunlight contrast and public signage typography when building frontend UIs.
Compact 3x3 Terminal QR & Single Short Link: The CLI spins up an ephemeral session and prints a compact 14-line ANSI QR code alongside a clean, single-line Break Gateway link (https://git-grass.onrender.com/break/?s=...&r=...&c=...).
User-Selected Break Duration & Lock-Screen Walk: You scan the QR code on your phone, select your preferred walk duration (5 min, 10 min, 15 min, or 20 min) right on the mobile UI, tap Start Break & Step Outside, lock your phone screen, and step outdoors.
Outdoor Reflection & Remote Commit Release: Once the countdown timer completes, you answer a 1-sentence observational reflection prompt and submit your commit message directly from your phone. Your workstation automatically verifies your staged tree SHA-1, executes git commit (and optional git push), and unlocks your terminal.

🎯 Project-Aware Outdoor Challenge Examples

git-grass inspects your repository context and selects an outdoor observation task matched to your active engineering domain:

Engineering Domain	Challenge Title	Real-World Observational Mission	Reflection Prompt
DevOps / Systems	Distributed Infrastructure Walk	Observe utility lines, storm conduits, traffic signals, and redundant physical routing.	"What physical routing junction or bottleneck reminded you of backend architecture?"
Frontend / Web	Visual Contrast & Wayfinding Walk	Examine public physical signage, architectural wayfinding, and sunlight glare contrast.	"What design element made a physical sign immediately readable from a distance?"
GameDev / 3D	Real-World Level & Pixel Perspective	Spot 3 elevation shifts, natural choke points, or shadow sightlines in your block.	"Which physical obstacle or sightline could inspire an engaging level mechanic?"
Machine Learning	Pattern & Texture Observer	Observe natural fractal textures, leaf veins, cloud variance, and shadow gradients.	"What distinctive feature made one natural pattern stand out from surrounding noise?"
Audio / Media	Soundscape Explorer	Walk without headphones; identify near, mid-range, and distant ambient acoustic layers.	"Which subtle outdoor sound stood out once you tuned out primary background noise?"

Demo

🌐 Live Website & Interactive Preview: https://git-grass.onrender.com
📚 Live Technical Documentation: https://git-grass.onrender.com/docs/
📱 Live Mobile Break Gateway: https://git-grass.onrender.com/break/?s=demo&r=git-grass&c=systems
📦 npm Package (git-grass): https://www.npmjs.com/package/git-grass

1. CLI Installation & Repository Hook Setup (`npm install -g git-grass` & `git grass init`)

2. Git Commit Gate & Compact `3x3` Terminal QR Code (`git commit -m "..."`)

3. Mobile Break Gateway — Select Break Duration (`5m / 10m / 15m / 20m`) & Domain

4. Mobile Break Gateway — Project-Tailored Outdoor Challenge & Start Break

5. Mobile Outdoor Walk — Active Countdown Timer & Check-In

6. Technical Architecture & CLI Documentation Portal

Code

sn3hhaa / git-grass

A Git-native “touch grass” gate that forces developers to take a real break before committing/pushing code.

🌱 git-grass

"Your AI can write the code. It can't touch grass."

⚡ Quick Install (Official npm Registry)

npm install -g git-grass
git grass init

git-grass is an open-source, Git-native outdoor-break enforcement tool that integrates physical recovery directly into your source control workflow. Explore the documentation and interactive demo on the official website.

When your configured focus interval expires, your next protected git commit is paused. The CLI generates a compact terminal QR code and Break Gateway session. Using repository file structure and manifest metadata, git-grass generates an observational outdoor challenge tailored to your project domain using Backboard Cloud AI, Thinking Machines Tinker open-weight model sampling, Render cloud microservice hosting, or zero-config bundled offline fallbacks.

The developer selects their walk duration on mobile, locks their phone, steps away from their workstation, returns refreshed, completes a short check-in on the phone, and submits their commit message directly from their…

View on GitHub

💻 GitHub Repository: https://github.com/sn3hhaa/git-grass
📦 npm Package: https://www.npmjs.com/package/git-grass
📄 License: MIT Open Source

How I Built It

git-grass is architected in TypeScript (Node.js ESM) with a multi-provider AI challenge engine, an Express-based local LAN session server, a zero-dependency mobile web gateway, and a cloud microservice deployed on Render:

Repository Context Analyzer (src/challenge/context.ts & src/challenge/generator.ts):
- Inspects repository file extensions, directory structure, and manifest metadata (package.json, README.md, shaders, etc.) to classify the codebase into engineering domains (systems, web, gamedev, ml, audio, or general) without ever reading or transmitting private source code.
Cloud AI & Open-Weight Model Pipeline (src/hosted/):
- Backboard AI Integration (src/hosted/providers/backboard.ts): Implements the real 3-step stateful Backboard REST workflow (POST /assistants -> POST /assistants/{id}/threads -> FormData POST /threads/{id}/messages authenticated with X-API-Key) routing to gemini-2.0-flash and open-weight models to synthesize structured, non-repetitive, domain-matched outdoor challenges.
- Thinking Machines Tinker Provider (src/hosted/providers/tinker.ts & src/challenge/generator.ts): Implements an OpenAI-compatible sampling provider (Qwen/Qwen3-30B-A3B-Instruct-2507) for low-latency open-weight model challenge synthesis via Thinking Machines Tinker.
- Render Cloud Backend (render.yaml): Hosted with an in-memory 1-hour TTL response cache and sliding-window IP rate limiter (15 req/min) so developers get zero-config AI challenges with $0 local hardware overhead.
- Zero-Latency Offline Fallback (challenges/fallback-challenges.json): Bundled with curated, domain-specific outdoor challenges so git-grass works 100% offline on airplanes or restricted networks.
Strict Schema Enforcement with Zod (src/challenge/schema.ts):
- Every AI-generated response is validated against OutdoorChallengeSchema and scanned by an anti-screen filter (SCREEN_WORDS blocklist) to guarantee the AI never tells the user to look at a screen, take photos, or type on their phone while walking.
Atomic Git Gate & Security (src/git/):
- Non-destructively wraps existing .git/hooks/pre-commit scripts (# --- BEGIN GIT-GRASS HOOK ---) so linters like Husky or lint-staged remain untouched.
- Uses git write-tree SHA-1 fingerprinting, recursion-safe GIT_GRASS_BYPASS_TOKEN release, and 48-character hex session tokens (crypto.timingSafeEqual) to prevent index tampering while the developer is away.

Why Does Open Innovation Matter?

Developer wellness and source-control tooling sit at the heart of every engineer's daily workflow. Open innovation matters for git-grass for three core reasons:

Verifiable Privacy Around Source Control: No developer should ever install a closed-source binary inside .git/hooks/pre-commit. Because git-grass is 100% open-source under the MIT license, anyone can audit how repository metadata is inspected and verify that zero source code or Git history ever leaves their machine.
Pluggable, Model-Agnostic AI Architecture: By building on open standards, modular provider interfaces (Backboard unified routing, Thinking Machines Tinker open-weight endpoints, local Ollama models, and offline JSON catalogs), and strict Zod schemas, git-grass isn't locked into a single proprietary API vendor. Communities can swap models, fine-tune domain prompts, or run completely offline.
Community-Curated Outdoor Missions: A game developer in Tokyo, a systems engineer in Berlin, and an ML researcher in Bengaluru experience different outdoor environments. Open-sourcing the challenge schemas and fallback libraries lets developers worldwide contribute new domain-specific observation missions.

My Agent Session

Built iteratively using agentic pair-programming for architectural planning, Git hook edge-case verification (recursive commit protection, git write-tree SHA-1 index validation, compact 14-line QR encoding), multi-provider AI integration (Backboard stateful threads + Thinking Machines Tinker open-weight sampling), and automated testing across 51 passing Vitest unit and disposable Git repository integration tests.

Prize Categories

Touch Grass (Main Challenge) — Enforces real-world, screen-free outdoor walks at the git commit boundary using project-tailored physical observation challenges.
Backboard — Powered by Backboard's 3-step stateful Assistant & Thread API (src/hosted/providers/backboard.ts) for context-aware, non-repetitive outdoor challenge generation.
Render — Full-stack deployment blueprint (render.yaml) hosting the git-grass documentation site, mobile /break/ and /b gateway routes, and the rate-limited/cached cloud AI challenge microservice (https://git-grass.onrender.com).
Thinking Machines Tinker — Integrated modular Tinker open-weight model sampling provider (src/hosted/providers/tinker.ts & src/challenge/generator.ts) using Qwen/Qwen3-30B-A3B-Instruct-2507 for structured outdoor mission synthesis.

🧠 Engineering Challenges I Ran Into & How I Solved Them

Preventing Infinite Git Hook Recursion:
- Challenge: Triggering git commit from the mobile check-in endpoint re-invokes .git/hooks/pre-commit, which would normally trap the commit in an infinite loop.
- Solution: I engineered a one-time in-memory GIT_GRASS_BYPASS_TOKEN paired with git write-tree SHA-1 index verification so the released commit passes cleanly while strictly rejecting any mid-break file tampering.
Shrinking Terminal QR Codes to 14 Lines (3x3 Finder Matrix):
- Challenge: Encoding full JSON payloads inside a QR URL produced massive 35-line QR codes that wrapped and broke inside narrow VS Code split terminals.
- Solution: I built a compact /b gateway redirect route and rendered the QR with errorCorrectionLevel: 'L' and margin: 1, compressing the terminal QR code into a crisp 14-line matrix alongside a single-line short URL (?s=&r=&c=) that any phone camera scans in under a second.
Seamless Wi-Fi to Outdoor 5G Hand-Off:
- Challenge: As soon as a developer steps outside their building, their phone disconnects from local Wi-Fi and switches to mobile 5G data.
- Solution: The hybrid gateway (site/break/app.js) seamlessly transitions between local LAN workstation sync and standalone mobile session mode so the walk timer never drops outdoors.

🏆 Accomplishments That I'm Proud Of

Published Live on Both npm & GitHub Packages: Anyone in the world can install git-grass globally in seconds (npm install -g git-grass).
51 Automated End-to-End Tests Passing (Vitest): Comprehensive test suite spinning up real disposable Git repositories and bare remotes to verify hook chaining, staged tree SHA-1 integrity, Backboard stateful threads, and Tinker sampling.
100% Privacy-First & $0 Cost: Source code and Git diffs never leave the developer's workstation.

🔮 What's Next for `git-grass`

Verified Commit Trailers (Git-Grass-Break: 15m): Optional cryptographic commit trailers so engineering teams can celebrate healthy shipping habits in pull requests.
Apple Watch & WearOS Haptic Companion: Glanceable wrist countdowns so your phone stays locked in your pocket for the entire outdoor walk.
Team Wellness Leaderboards (Opt-In): Zero-telemetry team badges for open-source maintainers during high-intensity sprints like Hacktoberfest.

🌱 Try `git-grass` Today!

Next time your AI coding agent generates 500 lines of code in 10 seconds, don't just sit there for another 4 hours - let Git remind you to step outside, breathe fresh air, and reset your eyes.

DEV Community: Sneha Tiwari