My coding agent now tells me to go outside, and a 4 GB Gemma writes the message

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

You send one more prompt. The agent answers. You send another.

Then you look at the clock and two hours are gone, your water glass is empty, and you have not looked at anything farther away than your monitor.

A timer is easy to dismiss. It fires in the middle of a thought, and it says the same thing every time. I wanted something that speaks up at the one moment I am already waiting, and says something I have not read a hundred times.

What I Built

agent-recess is a hook for Claude Code and Codex CLI. It measures how long you have been pairing with your agent. After 90 minutes, when the agent finishes a reply, it suggests a break.

The suggestion is written by Gemma 4 running on your own machine through Ollama, and it matches the weather outside your window.

On a clear afternoon:

🌿 Hey, you've been deep in the code for 94 minutes! Take a quick 10-minute walk outside
to get some fresh air and enjoy that clear sky. Go find a corner shop or just take a
moment to look up at the clouds.

When it rains:

🌿 You've been coding for 94 minutes! Since it's a bit wet out, take a quick 10-minute
breather right where you are. Pop a window open, do some big stretches, and grab a
refill of water to reset your eyes.

The whole screen part is three sentences. After that, the tool wants you gone.

A few rules keep it from becoming one more thing to dismiss:

• A gap of 15 minutes counts as a break and resets the streak.
• It only speaks when the agent has finished. It never blocks a tool call or a reply.
• After one suggestion it stays quiet for 30 minutes.
• Sessions in different terminals, and different agents, share one streak.

Demo

That is a real run on my machine at 22:40 on a clear night. Gemma answered in about two seconds.

You can try the generation without installing any hook:

ollama pull gemma4:e2b-it-qat
npm install -g github:spa77k/agent-recess
agent-recess preview 94

preview prints the exact prompt that went to the model, then the suggestion that came back.

I took its advice

I registered the hook in Claude Code and went back to work. At 12:05 pm, 95 minutes into refactoring a Discord bot, the agent finished a reply and this appeared under it:

🌿 Hey, you've been locked in for 90 minutes! Time for a quick reset. Take a five to fifteen minute break right now to stand up, stretch, and get some fresh air.

So I did what it said. I walked to a park near my home and sat there for a while, staring at nothing in particular. I came back feeling better than when I left.

That is the whole feature. The tool spoke for three sentences, and the park did the rest.

Code

spa77k / agent-recess

A Claude Code / Codex hook that notices long coding sessions and suggests a break, written by local Gemma 4 with the real weather.

agent-recess

English | 日本語 | 한국어 | 简体中文

A hook for Claude Code and Codex CLI that notices when you've been pairing with your coding agent for too long — and tells you to go touch grass.

The suggestion is written on your own machine by Gemma 4 running in Ollama, and it fits the actual weather outside:

On a clear afternoon:

🌿 Hey, you've been deep in the code for 94 minutes! Take a quick 10-minute walk outside
to get some fresh air and enjoy that clear sky. Go find a corner shop or just take a
moment to look up at the clouds

When it rains:

🌿 You've been coding for 94 minutes! Since it's a bit wet out, take a quick 10-minute
breather right where you are. Pop a window open, do some big stretches, and grab a
refill of water to reset your eyes

How

…

View on GitHub

It is plain Node.js with zero dependencies. The streak logic is one pure function, so the tests run without a clock, a network or a model.

How I Built It

The hook

Both agents call a command at fixed points in a session and pass JSON on stdin. agent-recess listens to two of them:

Event	What agent-recess does
UserPromptSubmit	Records the time
Stop	Records the time and, if a break is due, returns a message

The state is one small JSON file in ~/.agent-recess/. On a normal turn the hook reads it, writes it and exits in about 30 ms.

One detail is easy to miss. Codex rejects plain text on stdout for Stop, and Claude Code feeds plain text from UserPromptSubmit straight into the model's context. So the hook always prints JSON, even when it has nothing to say. In that case it prints {}.

The model

My first pick was gemma4:e4b. Ollama pulled a 9.5 GB build, and on my 16 GB Mac it took 78 seconds to produce 7 tokens. Nobody waits 78 seconds to be told to stand up.

I switched to gemma4:e2b-it-qat, which is 4.3 GB. The first call after a cold start takes about 7 seconds. Every call after that takes 1 to 3 seconds.

The part where Gemma sent me into the rain

My first prompt listed both options and let the model choose. Walk outside if it is dry, stay in if it is wet.

With rain in the weather data, this is what came back:

Since it is dark and rainy outside, take a 10-minute break to step outside and just watch the rain and the sky.

Poetic, but no.

The fix was to stop asking a small model to make the decision. Code now looks at the weather and picks indoors or outdoors. The model only gets the option that applies, and its job is the wording. Decisions went to the code and voice went to the model. In every weather case I have tried since, the suggestion has matched.

What the model sees

This is the full prompt for a dry night. There is nothing else.

You write break reminders for a software developer who has been pairing with an AI coding agent.
They have been at it for 94 minutes without a real break. Local time: 22:30.
Weather: clear sky, 18.2°C (feels like 17.4°C), precipitation 0 mm, wind 4.6 km/h, dark outside, sunset at 17:16.

Suggest one concrete break: it is dry but dark — a few minutes of night air at the door or on the balcony, or a stretch indoors.
Keep it to 1-3 short sentences, warm and a little playful, no lists, no markdown, no emoji.
Mention the minutes once. Say how long the break should be (5-15 minutes).
Write in English.

No code, no prompts, no file names. The hook never opens the transcript.

Weather comes from Open-Meteo, which needs no API key. The only thing that leaves your machine is the latitude and longitude you put in the config file. If you set none, the suggestion simply ignores the weather.

If Ollama is not running, or does not answer in 12 seconds, you get a fixed sentence instead. A break reminder that hangs your terminal would defeat the point.

Why Does Open Innovation Matter?

This tool watches how long you work. That is exactly the kind of data I do not want to send to someone else's server so it can tell me to drink water.

With open weights, it never has to. The model sits on my disk and the prompt stays on my machine. There is no API key to set up and no cost per reminder, so the tool can afford to say something new every time.

Open weights also let me pick the size. The 9.5 GB build was unusable on my laptop, and the 4.3 GB one answers in two seconds. With a closed API I would get whichever model the provider runs. Here it is one line in a config file, and you can point it at any other model Ollama serves.

The same goes for the rest of the stack. The weather is open data. The hook formats in Claude Code and Codex are documented, which is why one small script can serve both.

Try it

Run agent-recess preview once and read what your own machine writes for today's weather. If you like the tone, the hook config for both agents is in the README.

Then close the laptop for ten minutes.