DEV Community

Sneha Tiwari
Sneha Tiwari

Posted on

git-grass — A Git-Native Pre-Commit Gate That Forces Developers Outside

#devchallenge #hf26challenge

Hacktoberfest Open-Source AI Challenge Week 1: Touch Grass Submission 🌿

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

What I Built

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

Modern AI coding assistants (Cursor, Copilot, Claude, Gemini) have 10x'd our coding velocity — which ironically means developers now sit glued to their monitors for hours without a single physical break. Standard desktop break reminders fail because we reflexively click "Dismiss" in milliseconds, and "phone breaks" just mean scrolling feeds on a smaller screen.

git-grass is an open-source, Git-native outdoor-break enforcement tool 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.

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

  1. Git-Native Pre-Commit Gate: When your configured focus interval (e.g., 60 minutes) expires, your next git commit is safely paused while preserving your staged index fingerprint (git write-tree).
  2. Project-Aware AI Outdoor Missions: git-grass inspects your repository's domain (Systems/Infra, Web/Frontend, GameDev/3D, ML/AI, or Audio/DSP) 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.
  3. Cryptographic Terminal QR Bridge: The CLI prints an ANSI QR code in your terminal linked to a mobile Break Gateway.
  4. Lock Screen & Step Outside: You scan the QR code on your phone, tap Start Break, lock your phone screen, and step outside for a minimum 10–15 minute walk.
  5. Outdoor Reflection & Remote Commit Release: Once the 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.

Demo

  • NPM Package: npx git-grass start / npm install -g git-grass
  • Live Website & Interactive Documentation: (Paste your deployed Render Static Site URL here)
  • Hosted Cloud AI Service: (Paste your deployed Render Web Service URL here, or leave GitHub link)

Terminal Gate Experience: 

$ git commit -m "feat: implement distributed rate limiter"

🌱 git-grass

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

A break is required.

Minimum duration: 15 minutes
Your staged changes are preserved.

Scan the QR code to receive
your outdoor challenge:
  █████████████████████████████████
  ████ ▄▄▄▄▄ █▀▄█▄ ▀█ █ ▄▄▄▄▄ █████
  ████ █   █ █ █ ▀█ ▄ █ █   █ █████
  ████ █▄▄▄█ █▀█▀ █▄▀ █ █▄▄▄█ █████
  █████████████████████████████████

Git commit paused. Workstation will resume after outdoor break check-in.
Enter fullscreen mode Exit fullscreen mode

Code

GitHub logo 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."

License: MIT Node.js Version TypeScript Tests Passing Website

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 terminal QR code that opens an offline-resilient mobile web experience. Using repository metadata, git-grass generates an observational outdoor challenge tailored to your project domain using a Render-hosted AI backend powered by Backboard (Gemini 2.0 Flash), Thinking Machines Tinker provider architecture, or zero-config bundled offline fallbacks.

The developer locks their phone, steps away from their workstation for at least 10 minutes, returns refreshed, completes a short check-in on the phone, and submits their commit message directly from their yard or doorway. The local CLI safely validates staging integrity and executes the commit.

🚨

…
View on GitHub

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:

  1. Repository Context Analyzer (src/challenge/generator.ts):
    • Inspects repository file extensions, directory structure, and manifest metadata (package.json, Cargo.toml, pyproject.toml, shaders, etc.) to classify the codebase into engineering domains (systems, web, gamedev, ml, audio, or general) without ever reading or transmitting private source code.
  2. Cloud AI & Open-Weight Model Pipeline (src/hosted/):
    • Backboard AI Integration (src/hosted/providers/backboard.ts): Uses the Backboard API (/assistants & /threads/messages) routing to gemini-2.0-flash and open-weight models to synthesize structured, domain-matched outdoor challenges.
    • Thinking Machines Tinker Provider (src/hosted/providers/tinker.ts): Implements a modular OpenAI-compatible sampling provider architecture for open-weight model experimentation 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 so developers get zero-config AI challenges with $0 local hardware overhead.
    • Zero-Latency Offline Fallback (challenges/fallback-challenges.json): Bundled with 12 curated, domain-specific outdoor challenges so git-grass works 100% offline on airplanes or restricted networks.
  3. Strict Schema Enforcement with Zod (src/shared/schemas.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.
  4. 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 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:

  1. 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.
  2. Pluggable, Model-Agnostic AI Architecture: By building on open standards, modular provider interfaces (Backboard unified routing, Thinking Machines Tinker open-weight endpoints, and local 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.
  3. 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), multi-provider AI integration, and automated testing across 51 Vitest unit and disposable Git repository integration tests.

Prize Categories

  • Touch Grass (Main Challenge)
  • Backboard — Powered by Backboard's unified assistant & thread API (src/hosted/providers/backboard.ts) for context-aware outdoor challenge generation.
  • Render — Full-stack deployment blueprint (render.yaml) hosting both the git-grass documentation static site and the cloud AI challenge microservice.
  • Thinking Machines Tinker — Integrated modular Tinker provider (src/hosted/providers/tinker.ts) for open-weight LLM challenge synthesis.

Top comments (0)