DEV Community: SHWETANK-SAURABH

GhostRepo: A Local Autopsy for Abandoned Repositories, with Gemma Doing the Talking

SHWETANK-SAURABH — Sat, 31 Oct 2026 22:03:22 +0000

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 4: Ghost in the Machine

What I Built

Every abandoned repository has a story, but the people who could tell it have usually moved on. What's left is a stale README, a few hundred commits, and a dependency file nobody has touched in years.

GhostRepo investigates repositories like these on your own machine and helps you plan their resurrection.

Point it at a local repository, choose Summon Ghost, and let it perform an autopsy.

Here's what it does:

Examines programming languages, frameworks, Git history, dependencies, configuration, documentation, and tests. It also runs Ruff on Python code.
Reports verified findings, each backed by evidence, a source file, and its detection method.
Uses a locally running Gemma model to interpret those facts, keeping AI-generated findings separate and clearly labeled.
Builds a prioritized resurrection plan and drafts a new README.
Proposes code changes as downloadable diffs for you to review. GhostRepo never applies patches automatically.

My interpretation of the theme is simple: a quiet repository is a ghost, not necessarily a corpse.

A project with no recent commits might be finished, stable, or simply waiting for someone to discover it. GhostRepo deliberately avoids declaring a project abandoned based on commit age alone.

Demo

GhostRepo is designed as a local-first tool. It doesn't require accounts or a hosted AI service, and its API is intended to remain accessible only locally.

To try it yourself:

Install Ollama.
Pull the model:

ollama pull gemma3:4b

Clone the repository:

git clone https://github.com/SHWETANK-SAURABH/GhostRepo.git
cd GhostRepo

Start the application:

docker compose up --build

Clone a project you want to investigate into workspace/ and open:

http://localhost:3000

See the repository README for complete setup instructions and configuration details.

Code

The complete source code is available on GitHub:

GhostRepo — View Source Code

SHWETANK-SAURABH / GhostRepo

GhostRepo

Every abandoned repository has a story. Let's bring it back to life.

GhostRepo investigates a local repository and helps you prepare a safe recovery plan. Deterministic analyzers collect the facts. A model running on your own machine can then interpret them. Nothing is uploaded, and nothing in the scanned repository is executed or changed.

What it does

Investigates languages, frameworks, Git history, dependencies, configuration, documentation and tests, and runs Ruff on Python code.
Reports verified findings with severity, evidence, source file, confidence and detection method.
Adds AI interpretation from a local Ollama model, kept separate from verified findings and labeled.
Builds a resurrection plan in priority order, with verification steps and rough effort estimates.
Drafts a README from verified facts and marks anything it could not confirm.
Proposes patches as diffs you review and approve before download. GhostRepo never applies them.
Exports reports as Markdown or JSON, with secrets…

View on GitHub

How I Built It

The stack is FastAPI, SQLite, Next.js, and Gemma 3 (gemma3:4b), running locally through Ollama.

One of the most important architectural decisions was this:

The language model never reads the repository directly.

Instead, GhostRepo follows a controlled evidence-based pipeline:

Collect facts: Plain Python analyzers inspect repository metadata, Git history, dependency manifests, configuration, documentation, and tests. They don't execute the repository's code.
Build evidence: The collected facts become structured evidence records with unique IDs. Sensitive values are redacted.
Ask Gemma: The local model receives the evidence as untrusted data and is instructed to cite evidence IDs when making claims.
Validate everything: The application validates the response schema, redacts the output again, checks every evidence reference, and applies additional claim-validation rules.
Present results: Verified findings and AI-generated interpretations appear separately. The model cannot turn an unsupported guess into a verified finding.

If Ollama isn't running, deterministic findings, recovery plans, README drafts, patches, and exports still work.

What Testing the Real Model Taught Me

Testing with mocks was useful, but testing against the actual model exposed problems I hadn't anticipated.

1. Structured output wasn't actually working.

Ollama rejected my original JSON schema with failed to parse grammar. A JSON-mode fallback hid the error and sometimes returned {}, which only became obvious when analyzing larger repositories.

I simplified the schema and added a live integration test that calls the real model without relying on that fallback.

2. The model ignored some of my instructions.

I explicitly told Gemma not to treat commit age as evidence of abandonment. It still rated inactivity as critical and occasionally claimed vulnerabilities or abandonment without supporting evidence.

Repeating the prompt more firmly wasn't a solution.

Instead, I added code-level claim policies that reject unsupported conclusions. Live runs subsequently discarded findings such as "Long Inactivity" and "Outdated Dependencies" when the available evidence didn't justify them.

3. Test fixtures looked like leaked credentials.

Some example credentials in test folders were being classified as critical secrets.

I adjusted the detection policy so matches in test and example paths receive lower severity rather than being treated like confirmed production credential leaks.

Security: Treat Every Repository as Untrusted

A repository can contain more than just source code.

For example, its .git/config can specify programs for Git to execute through certain configuration settings.

To address this, GhostRepo overrides Git settings such as core.fsmonitor during Git operations. I also added a hostile Git configuration test to verify that those programs aren't executed.

Ruff runs with --isolated, preventing repository-specific configuration from silently changing the checks.

The broader principle is that repository contents are data to inspect, not instructions to follow.

Current Limitations

GhostRepo is an MVP, and there are some deliberate limitations:

Patches currently add missing project files and .gitignore entries. It doesn't yet propose arbitrary source-code fixes.
Static analysis currently covers Python through Ruff.
Dependency manifests are inspected offline, so GhostRepo cannot confirm whether a package is currently outdated or vulnerable.
Tests are discovered but not automatically executed.
Gemma can still produce incorrect interpretations. A valid evidence citation proves that the evidence exists, not that the model interpreted it correctly.
I've tested gemma3:4b; compatibility with other Ollama models still needs further testing.

Building With an AI Coding Agent

I built GhostRepo with the assistance of a hosted AI coding agent, working from my own project brief and architecture decisions.

That distinction matters: the coding assistant helped build the application, but the open-weight model running inside GhostRepo performs the actual repository analysis.

Why Does Open Innovation Matter?

People revive old code for many reasons, and some of that code is private: a former employer's internal tool, a client project, or a personal side project with credentials still buried somewhere inside it.

Sending an entire repository to a cloud AI API just to understand its current condition isn't always a good trade.

Running Gemma locally changes that.

Repository evidence stays on the developer's machine.
Inference doesn't require an external AI account.
There are no per-token API charges.
Developers can inspect and modify the analysis pipeline.
The model can be replaced with another compatible Ollama model.

I also restricted the configured Ollama endpoint to a local allowlist, so changing a setting can't silently redirect repository evidence to an arbitrary external service.

During a full walkthrough with the real model, I sampled the application's processes 240 times and observed no connections to non-loopback addresses.

That's useful evidence, but not proof of complete network isolation. I haven't yet tested the entire application with the network physically disconnected.

There's another reason open innovation matters here.

A tool designed to resurrect abandoned software shouldn't depend on a proprietary service that might itself disappear someday.

With the model downloaded locally, GhostRepo can continue working without an account, an API subscription, or an external inference service.

One licensing distinction is worth mentioning: Gemma's weights are openly available, but its terms are not an OSI-approved open-source license and include use restrictions. I've documented those terms in the repository and included Apache-2.0-licensed Qwen3 as an alternative worth exploring.

The Spirit of It

Día de los Muertos isn't about declaring people gone. It's about remembering them and keeping their stories present.

That's the philosophy I wanted GhostRepo to embody.

A repository's last commit isn't necessarily its final chapter. There may still be useful ideas, working code, and knowledge worth preserving.

An autopsy usually ends with a cause of death. GhostRepo's ends with a list of what's still there and what someone can do next.

For a final test, I ran GhostRepo on itself, a project that was only hours old.

The result?

Health indicator: 62
Ruff issues: 0
Finding: No license file detected.

The missing license was intentional at that point, but the finding was correct.

I liked that result. A tool that simply flatters its own creator wouldn't be much use when investigating someone else's ghosts.

Sometimes resurrection starts with being honest about what's broken.

Prize Categories

Best Use of Gemma

Gemma 3 (gemma3:4b) runs locally through Ollama and powers GhostRepo's AI analysis. Its output is validated against collected evidence, checked for unsupported claims, and kept separate from deterministic findings.

SlothSort: A Local AI That Tidies Your Downloads Folder and Never Moves a File Without Asking

SHWETANK-SAURABH — Sun, 25 Oct 2026 21:56:37 +0000

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 3: Slow and Steady.

What I Built

My Downloads folder had files named doc_001.pdf, scan_004.pdf, IMG_8291.jpg, and notes_final_v3.txt. Finding anything meant opening files one by one, figuring out what they contained, renaming them, and dragging them somewhere sensible.

I kept putting it off because sorting files is one of those chores that never feels urgent enough to do.

SlothSort does that chore for you.

Point it at a folder, and SlothSort scans supported files, extracts available text, and asks an open-weight AI model running on your own machine to suggest meaningful filenames and categories. It then presents the complete plan for your review.

Nothing moves until you approve it. Existing files are never intentionally overwritten or deleted, and successful moves can be undone when the original location remains available and the integrity checks pass.

Here are some real suggestions from Gemma 3 4B on my synthetic demo folder:

Before	After
`doc_001.pdf`	`Invoices/Greenfield_Power_Electricity_Bill_October_2026.pdf`
`hw3.docx`	`Assignments/CS101_Assignment_3_Sorting_Algorithms.docx`
`notes_final_v3.txt`	`Notes/Project_Kestrel_Weekly_Meeting_Notes.txt`
`Downloads/download (3).pdf`	`Receipts/Pinecone_Books_Order_Receipt_PB88213.pdf`

These are proposed destinations, not hardcoded mappings. The application generates suggestions from the available file evidence, and you can review or edit them before anything changes.

SlothSort is for anyone with a messy folder full of bills, receipts, coursework, screenshots, and meeting notes. It's also exactly the kind of folder you might not want to upload to a cloud AI.

Demo

🌐 Project page: https://slothsort-two.vercel.app

SlothSort deliberately has no hosted version. It organizes files on the computer where it runs, using a model running on that same computer. A hosted copy would operate on the server's filesystem instead, or require uploading files to the server.

Keeping the application local is part of the product, not an afterthought.

Code

GitHub repository: SHWETANK-SAURABH/slothsort

Clone the repository and run it locally:

git clone https://github.com/SHWETANK-SAURABH/slothsort.git
cd slothsort
pip install -r requirements.txt
ollama pull gemma3:4b
SLOTHSORT_MODEL=gemma3:4b streamlit run app.py

You'll need Python, Ollama, and enough memory to run the selected model. The initial installation and model download require internet access. Once the model is available locally, the core workflow can run without internet access.

How I Built It

Open-source AI at the core

SlothSort is built around local inference rather than a proprietary cloud LLM API.

Model: Google's open-weight Gemma 3 4B, running locally through Ollama. The model is configurable, and the sidebar lets users select models available in their Ollama installation.
Inference: Ollama's local HTTP API at localhost:11434. I use Python's standard-library urllib, so there's no additional SDK or API key.
Structured output: I pass a JSON Schema to Ollama's format option. The model returns a category, suggested filename, explanation, and confidence score. Pydantic validates the response. Malformed responses receive a bounded retry; if that fails, the file falls back to clearly labelled rule-based suggestions and is flagged for review.
Everything else: Streamlit for the UI, PyMuPDF for PDF text extraction, Pydantic for validation, Pillow for image handling, SQLite for the action journal, and pytest for automated tests.

The interesting part: don't trust the model

A small local model can read text like "ELECTRICITY BILL — Amount due: $84.20" and suggest the category Invoices.

But a language model should never be trusted to decide which filesystem operations are safe.

SlothSort separates AI reasoning from file execution:

flowchart TD
    S[Scan files — read only] --> M[Gemma 3 4B via Ollama]
    M -->|Structured JSON| V[Deterministic validator]
    V --> R[User reviews and edits]
    R -->|Explicit approval| E[Safe file executor]
    E --> J[(SQLite action journal)]
    J --> U[Undo supported moves]

Here's how that separation works:

The model only proposes. It returns structured text; it cannot execute commands or modify files directly.
Every suggestion is validated. The category must be allowed, the original file extension is preserved, and unsafe names, absolute paths, path traversal, and reserved Windows filenames are rejected.
Destinations are constrained. The resolved destination must remain inside the folder the user selected.
File contents are untrusted input. Extracted text is clearly delimited, and the system prompt instructs the model to treat it as data rather than instructions.
Prompt injection is part of the demo. My synthetic dataset includes a file that tries to instruct the model to move itself into system32. The model ignored it during my demo run, and the independent path validator is designed to reject an unsafe destination regardless of what the model suggests.
Approval is mandatory. The executor accepts only an approved plan with a fingerprint. If the plan changes after approval, execution is rejected.
Files are checked again before moving. SlothSort rechecks file identity using size, modification time, and SHA-256, and verifies that the destination does not already exist.
Moves are journaled. The SQLite action journal records operations so supported moves can be undone, including after an application restart. Undo also refuses to overwrite existing files.

The key design principle is simple: AI decides what might be useful; deterministic code decides what is allowed.

The bug that taught me something

On my first real run, Gemma named a grocery receipt Maple_Market_Receipt_September_2021.txt.

The receipt said 2026.

It also reported a confidence score of 0.95, just as it did for nearly everything else. That taught me that a model's self-reported confidence isn't a reliable way to decide whether a suggestion is trustworthy.

So I added a grounding check.

Any number in a proposed filename — a year, invoice ID, or amount — must appear in the extracted file text or metadata. For files without readable text, such as images and scans, suggested names are restricted to generic terms and words grounded in the original filename.

If a suggestion fails, SlothSort flags it for review with a message such as:

Check name: "2021" not found in the file.

It's a deliberately simple check, not a complete hallucination detector. But unlike trusting a confidence score, it catches a specific, reproducible class of errors.

Measured, not promised

I created a 29-file synthetic demo dataset containing invoices, receipts, assignments, notes, screenshots, photos, two pairs of exact duplicates, two unsupported files, and a prompt-injection example.

I manually labelled 27 files and ran the evaluation script twice.

Metric	Run 1	Run 2
Gemma 3 4B category accuracy	25/27 (92.6%)	24/27 (88.9%)
Filename-only baseline accuracy	17/27 (63.0%)	17/27 (63.0%)
Malformed model responses	0 of 7 calls	0 of 7 calls
Average planning time	≈3.0 s/file	≈2.2 s/file
Approved moves completed / undone	27/27 / 27/27	27/27 / 27/27
Unsafe-operation probes blocked	12/12	12/12

Twenty-seven labelled files are a sanity check, not a serious benchmark. Results varied between runs even at temperature zero, and the small sample means these numbers shouldn't be generalized to arbitrary folders.

The project also has 62 automated tests, with Ollama mocked so the test suite doesn't require a running model. These include a full UI click-through using Streamlit's AppTest.

The numbers above describe my recorded evaluation runs; the tests and evaluation scripts are available in the repository so others can inspect and reproduce them.

How the work got done

I built SlothSort in a week with the help of an AI coding agent.

I wrote the specification, including the technology stack, safety rules, priorities, and the requirement not to claim functionality before testing it. The agent wrote most of the code, ran tests, and helped with the real-model evaluation along the way.

I made the architectural decisions and checked the results. The commit history documents the progression from the core engine and tests to the UI and documentation.

Why Does Open Innovation Matter?

For SlothSort, open-weight AI is what makes the local-first approach practical.

A file organizer needs to read your files: utility bills with account numbers, receipts, coursework with your name on it, and possibly a lease agreement.

With a cloud LLM API, the excerpts needed for classification would be sent to someone else's server. You'd need an API key, an internet connection, and confidence in the provider's data-handling policies.

With Gemma running locally through Ollama, file content can stay on your computer. SlothSort's model requests go to the local Ollama endpoint rather than a remote LLM service.

That changes the privacy story from a promise about a provider's policies to an architectural choice that users can inspect.

Open weights also provide practical advantages:

No model-provider lock-in. The model can be changed without redesigning the entire application. The evaluation script can be run again to compare supported models.
No per-file API bill. Once the model has been downloaded, inference uses the user's own hardware rather than charging for each API request.
User control. Developers can inspect the application, modify the prompts, change the model, and test the results themselves.
Offline capability. After setup and model download, the core workflow can operate without internet access.

Local inference isn't free in an absolute sense: it consumes hardware resources and electricity, and larger models may require substantial memory. But it removes the need to send document contents to a proprietary inference service.

A 4B open-weight model isn't necessarily as capable as the largest closed models. For a narrow task like file organization, though, pairing a local model with deterministic validation and explicit human approval makes the trade-off worthwhile.

The Lazy Payoff

On my demo folder, planning 27 files took approximately a minute of model time. My job was to watch the progress bar and then review a single table rather than opening 27 files individually.

I haven't timed myself organizing the same folder manually, so I won't claim a specific number of minutes saved.

The bigger payoff is that I no longer have to put the task off until I have the patience to do it. SlothSort handles the repetitive work, while I retain control over the final changes.

That's the point of Slow and Steady: let the machine handle the boring part, and spend your attention where it matters.

Prize Categories

Best Use of Gemma: SlothSort uses Google's open-weight Gemma 3 4B locally through Ollama. The reported model-evaluation results above come from Gemma.

Built with local AI, deterministic safety checks, and a healthy respect for the art of doing less repetitive work.

ReceiptPilot: a local-first AI receipt assistant for freelancers

SHWETANK-SAURABH — Sun, 18 Oct 2026 22:24:13 +0000

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 2: Side Hustle

What I Built

Every freelancer I know keeps the same folder: phone photos of taxi receipts, PDF invoices from software vendors, and hotel bills scanned at an angle. Once a month, or worse, once a year at tax time, someone types all of it into a spreadsheet. Merchant, date, currency, subtotal, tax, total. One receipt at a time.

ReceiptPilot does that typing. You upload JPG, PNG, or PDF files. An open-weight vision model can read them locally on your own computer. Ordinary code checks the numbers. Then you review every field next to the original document before it becomes a confirmed expense. Confirmed expenses go into a ledger you can filter and export as CSV for your accountant.

The customer is deliberately narrow: a freelancer or two-person business handling somewhere between 20 and 200 receipts a month, who enters them by hand today and doesn't want to send financial documents to another cloud service. The value is less repetitive data entry, fewer manual transcription errors, and more control over sensitive documents.

I can see two ways to charge for it: a paid desktop bundle with the model preconfigured, or a managed installation that an accountant rolls out to their freelance clients.

What it does:

Reads documents with a local open-weight model: Gemma 3 4B through Ollama. Text-based PDFs are read from their embedded text; photos and scans are processed visually.
Checks arithmetic in code, not in the prompt. Amounts are parsed as exact decimals, with both 1.234,56 and 1,234.56 supported, and subtotal plus tax is compared with the total.
Refuses to guess. A date like 03/04/2026 or a bare $ is flagged for you to resolve instead of being silently interpreted.
Catches potential duplicates. It checks identical files, matching invoice numbers, and combinations of total, date proximity, and similar merchant names. It gives you a score and a plain-English reason. You decide what to do; nothing is automatically deleted.
Shows where every value came from: extracted from the document, suggested, or edited by you.
Handles extraction failures gracefully. If extraction fails, the receipt can still be saved so you can retry or enter the details manually.

Demo

Try ReceiptPilot: Open the live application

Source code: GitHub — SHWETANK-SAURABH/ReceiptPilot

The live web application provides a way to explore the interface. The local setup below is the intended way to run the complete application with your own Ollama model.

The dashboard keeps confirmed totals separate by currency:

The ledger supports filtering and CSV export:

To run the application locally, install Ollama, ensure Docker is installed, and run:

ollama pull gemma3:4b
docker compose up --build

Then open http://localhost:3000.

The complete setup instructions and configuration are available in the GitHub repository.

Code

ReceiptPilot on GitHub

The project is MIT licensed and uses a Next.js 16 frontend, a FastAPI backend, and SQLite or PostgreSQL for storage. The repository includes backend and frontend tests, Playwright end-to-end tests, Docker Compose configuration, and a Vercel configuration.

How I Built It

flowchart LR
    U([User]) --> FE["Next.js web app"]
    FE --> API["FastAPI"]
    API --> P["PDF text extraction / page rendering<br/>Image preprocessing"]
    P --> M["Ollama<br/>Gemma 3 4B"]
    M --> V["Code validation<br/>Decimals, dates, arithmetic"]
    V --> D["Duplicate detection"]
    D --> DB[("Database")]
    DB --> FE

The open-weight models

The default model is gemma3:4b, served through Ollama. I developed and tested the application on a laptop with an NVIDIA RTX 4060 GPU with 8 GB of VRAM.

I also compared it with qwen2.5vl:7b, which uses the Apache 2.0 license. In my 40-document synthetic evaluation, Qwen was slightly more accurate, while Gemma was faster and required fewer resources.

The measured median processing times were 4.6 seconds per document for Gemma and 6.4 seconds for Qwen. These figures describe my test environment, not a guaranteed performance level on every machine.

Gemma is the default because the goal is to make the application practical on more modest hardware. Qwen remains an alternative. The model interface is separated from the business logic, so swapping models or inference runtimes does not require rewriting the rest of the application.

The design decision that mattered most: the model reads, the code decides

Ollama's structured output constrains the model to a JSON schema in which fields are allowed to be empty. The model does not have to invent a value just because a field exists.

After extraction, deterministic Python code validates the response. It parses amounts as decimals, checks totals, identifies ambiguous dates, and looks for potential duplicates.

Nothing is automatically changed to make the numbers add up. If a total does not match, the application shows a warning and lets the user decide what to do.

That decision mattered during development. In an early test, the model returned a line item as 2 × 9.98 = 9.98. The arithmetic validation caught the inconsistency.

Another model run showed Gemma copying line totals into unit-price fields when a receipt printed only one amount per line. This produced warnings on records that were actually correct, which could eventually train users to ignore warnings.

I revised the prompt and reran the evaluation for both models. The revised evaluation no longer showed that particular source of warning noise. This was a useful reminder that validation logic is only as useful as the quality of the data it validates and the warnings it produces.

Measuring it honestly

I created a labelled set of 40 synthetic documents, including:

Clear receipts and invoices.
Text-based and scanned PDFs, including multi-page documents.
Blurred, skewed, rotated, dark, faded, and low-resolution images.
Missing fields and ambiguous dates.
Planted arithmetic errors.
True duplicates and similar-looking documents that were not duplicates.

Every document went through the actual extraction and validation pipeline.

Evaluation metric	Gemma 3 4B	Qwen2.5-VL 7B
Documents with every field correct	38/40	39/40
Values invented where a field should be empty	0	0
Planted total errors caught	2/2	2/2
False alarms on planted total-error checks	0	0
Ambiguous dates correctly left for the user	4/4	4/4
Duplicates detected	5/5	5/5
Look-alikes incorrectly flagged as duplicates	0/4	0/4
Median processing time per document	4.6 s	6.4 s

The remaining extraction misses were fields left blank rather than incorrect values. The application marks these fields as missing instead of silently filling them with guesses.

There are important limitations. These are synthetic documents, the sample contains only 40 documents, and it does not represent the full variety of real-world receipts. Crumpled paper, unusual layouts, handwritten notes, unfamiliar currencies, and poor scans may produce worse results.

These numbers should be treated as an initial engineering evaluation, not a claim of production-grade accuracy. The dataset, evaluation runner, and raw results are available in the repository so that others can reproduce or extend the tests.

The evaluation also caught errors in my own ground-truth labels. Two labels needed correction because dates such as 01-10-2026 are ambiguous without an agreed date convention. The application had correctly refused to choose between 1 October and 10 January. I corrected the labels and documented the change rather than silently adjusting the results.

Why Does Open Innovation Matter?

Receipts can contain names, partial card details, addresses, and a detailed record of how someone spends their money.

A receipt-processing service built entirely around a closed API can require users to send financial documents to an external provider. With open weights and local inference, ReceiptPilot can run its extraction pipeline on a user's own machine without sending documents to an external AI API.

That makes local operation possible without a per-page AI API fee. It also gives users more control over where their documents are processed.

Open weights made experimentation practical, too. I could run two models on the same dataset, compare their results, and choose a model based on accuracy, speed, and hardware requirements instead of relying on a single provider.

Privacy still depends on configuration. If ReceiptPilot is pointed at a remote Ollama server, documents sent for inference may leave the user's device. A local model alone does not guarantee that every part of a web application is private.

That is why the distinction between a hosted interface and a fully local deployment matters. Users should understand where documents are stored, which server processes them, and whether data leaves their device.

For this project, open innovation is not just about avoiding a proprietary API. It makes model choice, reproducibility, and local-first deployment practical design options.

What's Next

The next step is validation with real freelancers: processing their own receipts with permission, measuring the time saved, and publishing the results alongside the synthetic evaluation.

After that, I want to work on a one-click desktop build, support tips, fees, and discounts as proper fields, and add export formats for accounting tools such as Xero and QuickBooks.

ReceiptPilot is an attempt to make a small but tedious task easier without forcing users to give up control of their financial documents. There is still work to do, especially around real-world accuracy and usability, but the core workflow is in place.

TouchGrass: a phone referee for outdoor games, with an open-weight Game Master

SHWETANK-SAURABH — Sun, 11 Oct 2026 21:32:13 +0000

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

What I Built

TouchGrass is a referee for outdoor games that lives on your phones, so nobody has to stay behind to keep score.

The idea is simple: everyone should be able to play instead of arguing about the rules, keeping score, or watching the clock. TouchGrass is designed to handle those jobs so friends, families, and youth groups can spend more time playing outside.

The project has a game engine, a multiplayer server, persistent game sessions, and an AI Game Master powered by an open weight model.

The Game Master can propose a twist for a round: a safe zone rule, a bonus challenge, or a little more time. But there is one important distinction: the AI proposes; the game engine decides.

The model never directly changes the game state. Its proposal must pass three checks implemented in ordinary code before it can be applied:

Gemma proposes
      ↓
Schema validation
      ↓
Game legality check
      ↓
Deterministic safety validation
      ↓
Game engine applies the event
      ↓
Players receive the update

If the model is slow, produces malformed output, proposes an illegal event, or is switched off, the game can continue without that AI event.

The project is intended for friends, families, and youth groups who want a reason to go to the park, and for anyone who has ever argued about whether a tag counted.

What works today: Tag and Hide & Seek are playable for 2–4 players, with three rounds and a named winner. Three other games Ice & Fire, Treasure Hunt, and Nature Challenge have their rules defined but are not playable yet. The website labels them as coming soon rather than pretending they are finished.

The browser-based gameplay client is not implemented yet. The game flow has been tested locally through the game server.

Demo

Live website: https://touchgrass-game-master.vercel.app/

The live website presents the project, games, rules, and design. It does not yet support playing a complete game directly in the browser.

Local demo: The game server has been tested locally with multiple players and a real Game Master turn. The recording below demonstrates session creation, player joining, a round starting, and a Game Master event being applied after validation.

Code

GitHub repository: https://github.com/SHWETANK-SAURABH/touchgrass_game_master

The project is MIT licensed. The README contains the commands needed to install dependencies, run verification, start the server, and try the local demo.

How I Built It

The open-source AI at the centre

The Game Master uses three important pieces:

Gemma 3 (4B): An open weight model served locally through Ollama.
Mastra: An open-source agent framework used to structure the Game Master agent.
A replaceable model provider: The application can use Ollama or a compatible model endpoint selected through configuration.

In my local setup, Gemma runs on my own machine. No hosted AI API is required for a Game Master turn in that configuration.

One rule shaped the entire architecture:

The AI proposes. The safety layer validates. The game engine executes.

A language model can be wrong, slow, or creative in ways that are inappropriate for an outdoor game. It should not be responsible for deciding whether an action is legal or whether the game state is valid.

Instead, TouchGrass uses a deterministic game engine. Game events are checked against the rules, and the same valid event sequence produces the same game-state transitions. That makes the core mechanics testable independently of the model.

The model is treated as an untrusted source of suggestions, not as the authority over the game.

What happens during a Game Master turn?

Each turn follows a controlled pipeline:

The agent receives game context. It sees a trimmed view of the current game rather than unrestricted internal state.
It can use two read-only tools. game_history retrieves historical game records, while game_rules provides information about the rules and constraints.
It returns a structured proposal. The response must match the expected schema, which is validated with Zod.
The engine checks legality. An event that is not valid for the current game state is rejected.
The deterministic safety layer checks the proposal. It rejects recognised unsafe event types and options.
The engine applies accepted events. Only validated events can mutate the game state, after which the update is broadcast and persisted.

Tool calls cannot directly mutate game state. Unknown tools are rejected, and tool inputs and outputs are bounded.

If the model produces malformed output or the proposal fails validation, the game does not apply the invalid event.

This design lets the AI contribute creativity without giving it control over the rules.

The rest of the stack

The project uses:

TypeScript in a monorepo
Next.js 16 for the website
A WebSocket game server for multiplayer sessions
MongoDB for persisted game sessions
Mastra for the Game Master agent
Gemma 3 (4B) through Ollama for local inference
Zod for structured-output validation
Sentry integration and application-level observability
An automated evaluation suite for Game Master behaviour

The repository has more than 2,000 automated tests, including 35 scripted Game Master evaluation scenarios. The goal is to make changes measurable rather than relying only on whether a prompt sounds better.

The production server currently uses a single process multiplayer architecture. It is not designed for multiple independent game server instances sharing the same database.

Things I learned the honest way

1. The model saw something it should not have.

During development, a game join code leaked into the model's view through a historical game record. The model did not need that information. I traced the issue to the history view and corrected the redaction.

That experience reinforced an important lesson: limiting the model's authority is not enough. The information it receives must also be limited to what it needs.

2. Small models can be cautious.

In my tests with Gemma 3 (4B), the Game Master frequently chose to extend the round. That is a legal and safe option, but repeated use makes the game less varied.

A smaller model can be useful for a controlled task, but its behaviour still needs evaluation. The next challenge is to encourage more variety without weakening the validation rules.

3. Safety rules have limits.

The safety validator is a set of deterministic rules. It can reject hazards that it recognises, but it does not know the park where players are standing, the traffic nearby, or the actual conditions around them.

It does not make outdoor play automatically safe. Players still need to use their judgement and follow local safety rules.

4. A successful model response is not the same as a successful game event.

The model can return valid JSON and still suggest something that is illegal in the current game. Structured output solves only one part of the problem.

Keeping schema validation, engine legality, and safety validation separate made those failure cases easier to test and reason about.

Why Does Open Innovation Matter?

Three things became easier because I could run and inspect an open-weight model.

I could inspect the model's inputs and outputs

Because Gemma runs locally through Ollama in my development setup, I can inspect what goes into the model and what comes back.

That helped me discover the join-code leak and correct the model's input.

Open weights do not automatically guarantee privacy or security, but they give developers more control over the inference environment and make it easier to investigate model behaviour.

The evaluation suite gives me a repeatable baseline

The Game Master evaluation suite contains 35 scripted scenarios covering expected outcomes and failure stages.

Running these tests against a fixed model version makes comparisons more meaningful when I change prompts, tool descriptions, or safety rules. It does not eliminate model variability, but it gives me a repeatable baseline.

Local inference avoids per-turn hosted AI charges

In my local configuration, the Game Master runs through Ollama without making a per-turn call to a hosted AI provider.

That can make experimentation more accessible to developers, families, and youth groups who do not want a usage-based AI bill.

It is important to distinguish local inference from a completely offline application: dependencies and model weights must be installed first, and other services may still need network access.

The broader benefit is freedom to experiment. Someone else can add a game, replace the model, improve the evaluation suite, or translate the safety rules without needing permission from a closed API provider.

Prize Categories

Best Use of Gemma

Gemma 3 (4B) acts as the Game Master. Through Ollama, it receives game context, can consult read-only tools, and proposes a single game twist as structured JSON.

The architecture is built around what a small open-weight model can contribute ideas while leaving legality and execution to deterministic code.

Best Use of Mastra

The Game Master agent is built using Mastra. Its two read-only tools, game_history and game_rules, provide additional context before it proposes an event.

The application does not give the agent unrestricted control over the game. Its output must pass the existing schema, engine-legality, and safety checks before any change is applied.

What's Next?

The immediate priorities are to build the browser-based gameplay client, make the remaining three games playable, and improve the variety of Game Master events without compromising the safety boundary.

I also want to make the project easier for open-source contributors to extend through better game definitions, more evaluation scenarios, accessibility improvements, and localisation.

I built TouchGrass with help from an AI coding assistant, including assistance with implementation and this article. The architectural decisions, testing, and decisions about what the project can honestly claim remain my responsibility.

The central idea is simple: use open-weight AI to make games more interesting, but never let the model become the referee.

Let the model suggest. Let code check. Let everyone play.