touchgrass-cli - a local AI that tells you to close the terminal and go outside

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

What I Built

Every screen-time app I have tried fights screen time with more screen time. Streaks, badges, weekly reports, notifications telling me to check my notifications. I wanted the opposite: a tool whose whole job is to make itself unnecessary.

touchgrass is a tiny command line tool. You tell it how much time you have and how you feel, and an open-weight model running on your own machine writes you a concrete plan to go outside. Then it tells you to close the terminal.

$ python3 touchgrass.py --file examples/tired_evening.txt

*** Lunchtime in the park ***

  1. Walk to the nearest park gate (10 min)
  2. Find a bench or shaded spot to sit and enjoy a meal (15 min)
  3. Enjoy a snack or a light meal (20 min)

why: The park is a great place to take a break from lectures and spend some time outside. It's also a good spot to meet friends or family.

~30 minutes away from the screen (local model (qwen2.5:0.5b via Ollama)).
Now close this terminal and go.```



It is for people like me: students and devs who mean to take a break, open YouTube "for 5 minutes", and lose an hour.

## Demo

Real runs on my laptop, no internet, model served locally by Ollama:

$ python3 touchgrass.py --file examples/energetic_morning.txt

*** Explore the rooftop ***

1. Take a leisurely walk up to the rooftop (20 min)
2. Look out the window, enjoy the view without a phone (10 min)
3. Return to your car and drive back to your place (10 min)

why: The rooftop offers a panoramic view and a fresh start, perfect for a break from screens.

~20 minutes away from the screen (local model (qwen2.5:0.5b via Ollama)).
Now close this terminal and go.```

And when the model server is not running at all, it still works, because a break should not depend on your setup:

$ python3 touchgrass.py --offline "i have 45 minutes and low energy"

*** Slow loop around the block ***

  1. Step outside and walk slowly around the block (15 min, phone stays in your pocket)
  2. Find a tree, bench, or stairs to sit on and just watch the world for 5 minutes
  3. Head back the long way and notice three things you never looked at before

why: Movement and daylight reset your attention better than any feed can.

~45 minutes away from the screen (offline heuristic (model unavailable)).
Now close this terminal and go.```



## Code

Repo: https://github.com/gajit9147-dev/touchgrass-cli

Plain Python 3, standard library only. No pip install, no API keys, nothing to sign up for. The whole thing is one file plus examples and a README.

## How I Built It

The core is local inference on an open-weight model. Your message goes to `qwen2.5:0.5b` (about 400 MB, pulls in a minute) served by Ollama on localhost. The model returns a small JSON plan: a title, three steps, a reason, and how many screen minutes you get back.

Two design choices I liked:

- Small models are honest about being small. The 0.5B model sometimes writes "sip a chai stall" instead of "sip chai at the stall". I kept a few of these in the demo output because they are real, and the plans are still good. If you have the RAM, `--model llama3.2` or `qwen2.5:3b` gives smoother plans.
- Graceful degradation. If Ollama is down or the model returns broken JSON, a built-in heuristic planner (based on your time and energy words) still gives you a real plan. The tool never leaves you staring at an error.

## Why Does Open Innovation Matter?

This project only exists because the model is open-weight. My break plans - how tired I am, when I finish classes, what I do about it - never leave my laptop. There is no account, no analytics, no company storing the fact that I felt drained at 6 pm on a Tuesday. A closed API would mean every low-energy evening goes to someone's server, and the tool would die the day the pricing changes. With a local open-weight model it works on a train, in my hostel with the wifi down, anywhere.

It also means you can open the file, read the prompt, change the coach's personality, and swap the model for a better one next month. That is the whole point of building in the open: the tool belongs to whoever runs it.

## What I Took From It

The best feature is the last line: "Now close this terminal and go." Most software tries to keep you. I wanted to build one that lets you leave.