DEV Community: Madhur Mittal

Claude Code Stop hooks: making the agent finish its homework"

Madhur Mittal — Wed, 07 Oct 2026 10:21:34 +0000

Every coding agent I use has the same habit. It does the work, writes a lovely summary, and stops. The summary lives in the chat. The chat scrolls away. The NOTES.md I asked it to keep up to date hasn't been touched since Tuesday.

You can ask nicely in CLAUDE.md, and it will mostly listen. "Mostly" is doing a lot of work in that sentence.

Claude Code has a firmer tool for this: a Stop hook, a script that runs when the agent is about to finish and is allowed to say "not yet". I shipped one in Deiko this week, then shipped a fix for it the same day. The fix taught me the one rule I'd now give anyone writing a Stop hook, so that's where this post is heading. Basics first.

What a Stop hook is, and when it fires

A Stop hook runs when the main agent has finished responding. It doesn't run when you interrupt with Esc. An API error fires a separate StopFailure event, and subagents get their own SubagentStop.

Hooks live in settings.json: ~/.claude/settings.json for all your projects, .claude/settings.json for one repo. There are three levels: the event, a group, and the handlers inside the group. Stop has no matcher (if you add one, it's silently ignored), so the group is just a wrapper:

{
  "hooks": {
    "Stop": [
      { "hooks": [{ "type": "command", "command": "node",
                    "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/notes-guard.mjs"] }] }
    ]
  }
}

Setting args runs the command directly, without a shell, which is what the hooks reference recommends whenever you use a path placeholder like ${CLAUDE_PROJECT_DIR}.

The script gets a JSON object on stdin. For Stop, the parts you'll use look like this:

{
  "session_id": "abc123",
  "transcript_path": "~/.claude/projects/.../00893aaf-....jsonl",
  "cwd": "/Users/you/project",
  "hook_event_name": "Stop",
  "stop_hook_active": false,
  "last_assistant_message": "I've finished the refactor. Here's what changed..."
}

There are a few more fields (permission_mode, background_tasks, session_crons), but these are the ones that matter here.

How "block" keeps the agent going

Print nothing and exit 0, and the agent stops as normal. To keep it working, exit 0 and print this on stdout:

{ "decision": "block", "reason": "Run the tests before you finish." }

reason is required when you block, and it's what Claude reads as its next instruction. You can also block by exiting 2, in which case your stderr becomes the reason. Pick one style per hook.

The trap here is exit 1. Every Unix instinct says 1 means "no", but for a Stop hook it's a non-blocking error: you get a "hook error" notice and the agent stops anyway. Same if your script path is mistyped. A guard with a typo in settings.json doesn't guard anything, so watch the first run.

Also: stdout has to be only the JSON. A shell profile that prints a greeting can land in front of it, and then your block is quietly ignored.

A Stop hook example you can copy

Here's one I'd actually use: don't finish a turn without touching NOTES.md. The interesting part is "a turn". The hook needs to know when this turn started, and Claude Code gives you a documented way to find out: a UserPromptSubmit hook fires the moment you send a prompt. So one script handles both events. On a prompt, it writes down the time. On Stop, it checks whether NOTES.md changed since then.

#!/usr/bin/env node
// .claude/hooks/notes-guard.mjs: runs on UserPromptSubmit and Stop.
import { readFileSync, writeFileSync, statSync } from "node:fs";
import { join } from "node:path";
import { tmpdir } from "node:os";

try {
  const input = JSON.parse(readFileSync(0, "utf8"));
  const mark = join(tmpdir(), `notes-guard-${input.session_id}`);

  if (input.hook_event_name === "UserPromptSubmit") {
    writeFileSync(mark, String(Date.now())); // when this turn began
  } else if (input.hook_event_name === "Stop" && !input.stop_hook_active) {
    const began = Number(readFileSync(mark, "utf8"));
    const notes = join(process.env.CLAUDE_PROJECT_DIR ?? input.cwd, "NOTES.md");
    let edited = 0;
    try { edited = statSync(notes).mtimeMs; } catch {}
    if (edited < began) {
      console.log(JSON.stringify({
        decision: "block",
        reason: "Before you stop: add a line to NOTES.md saying what you changed this turn and why.",
      }));
    }
  }
} catch {} // anything odd: let the agent stop

{
  "hooks": {
    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "node",
      "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/notes-guard.mjs"] }] }],
    "Stop": [{ "hooks": [{ "type": "command", "command": "node",
      "args": ["${CLAUDE_PROJECT_DIR}/.claude/hooks/notes-guard.mjs"] }] }]
  }
}

It's strict: every turn has to end with a note, including "what does this function do?" turns. That's fine for a long autonomous session and annoying for a chatty one. Swap the condition for whatever "done" means to you: a test run's exit code, a changelog line, a file under docs/. Keep the shape.

If you don't need a script at all, Claude Code also supports prompt and agent hooks on Stop, where a model decides whether the work is finished, and a /goal command that does the same for one session. For a fuzzy condition like "are all the tasks done?", that's the better pick. For anything you can check with a file timestamp or an exit code, a script is cheaper and gives the same answer every time.

The infinite-loop trap

Write a Stop hook that blocks whenever a condition isn't met, and sooner or later the condition can't be met. The tests need a database that isn't running. The agent has no write access to NOTES.md. Your hook blocks, the agent tries, fails, stops, your hook blocks again.

That's what stop_hook_active is for. It's true when Claude is already continuing because a Stop hook blocked. Check it first, and let the agent go: you asked once, it tried, move on. Claude Code also has a backstop: after eight blocks in a row it overrides the hook and ends the turn (CLAUDE_CODE_STOP_HOOK_BLOCK_CAP changes the number). Eight rounds of an agent being nagged is still eight rounds of tokens, though. Check the flag.

The example above checks it in the if, and everything else lives inside a try that falls through to "let it stop". A missing timestamp file, a broken stdin, an unreadable path: all of them end the turn normally. A guard that fails closed turns one bad file into an agent that can't finish anything.

A real one: Deiko's report-back hook

Quick context if you're new here (or start with giving Claude Code a memory between sessions): Deiko is a Mac app where you point at things on screen and talk, and it turns that into a brief for your coding agent. Every brief is filed into a task, and each task keeps a note: where it stands, what was decided, what agents reported back. That last part only works if the agent actually reports back, through a save_outcome tool on Deiko's local memory server or by writing an outcome.md file the brief names. The post on building memory has the long version.

Agents forget. So in 0.5.8, connecting memory in Settings also adds a Stop hook to Claude Code. The whole thing is about 70 lines of Node with no dependencies, and it makes four decisions:

Only act on a Deiko brief. Every brief contains one fixed sentence asking for a report, which names the brief's id and the path of its outcome.md. The hook looks for that sentence with a regular expression. No sentence, no opinion.
Check the file, not the conversation. save_outcome writes the same outcome.md the brief points at, so one check covers both routes: was that file modified after the brief arrived? The arrival time comes from the brief's timestamp in the transcript; the other side is the file's mtime.
Block once. If there's no report, it blocks with a reason naming the brief and both ways to save. If stop_hook_active is true, it does nothing.
Never stand in the agent's way. Bad JSON, a missing transcript, an unreadable file: the hook prints nothing and exits 0. That comment is in the code, word for word.

The decision is one function that returns either null or the block object, with file access passed in so tests can fake it:

export function decide(input, { read = (p) => readFileSync(p, "utf8"), mtime = (p) => statSync(p).mtimeMs } = {}) {
  if (!input || input.stop_hook_active || !input.transcript_path) return null;
  let transcript;
  try { transcript = read(input.transcript_path); } catch { return null; }
  const brief = latestBrief(transcript);
  if (!brief) return null;
  let saved = 0;
  try { saved = mtime(brief.outcome); } catch { /* not written yet */ }
  if (saved >= brief.at) return null;
  return { decision: "block", reason: `Before you finish: save what you did for Deiko brief ${brief.id} ...` };
}

Installing it is the boring part, and I wanted it boring. The Mac app reads ~/.claude/settings.json and refuses to touch it if it won't parse. It finds its own entry by the script's file name, so a moved app replaces its old entry instead of adding a second, and your other hooks stay exactly where they were. It keeps one backup, writes through a temp file and a rename, then reads the file back to confirm. Disconnecting removes only Deiko's entry. That code is here if you're writing an installer of your own.

The bug: homework that was never set

Version one looked for the latest brief anywhere in the transcript.

That sounds right until you have a long working session. I'd pasted a brief into Claude Code early on, not to work on it but to talk about it. We talked, then moved on to other things. Lots of other things.

At the end of every single turn after that, the hook asked for a report on that brief.

Each turn it blocked only once, so nothing looped. But stop_hook_active resets with every new prompt, and the brief was still sitting in the transcript with no outcome written after it. So: block, every turn, forever. The best case is an agent wasting a turn explaining it wasn't working on that. The worst case is an agent that obligingly invents a report for work it never did and files it into that task's memory.

The fix shipped in 0.5.10, on 30 September. Here's the heart of the diff:

// 0.5.8: remember the last brief seen anywhere
const m = MARKER.exec(text(entry.message?.content));
if (m) found = { id: m[1], outcome: m[2], at: Date.parse(entry.timestamp) || 0 };

// 0.5.10: every real prompt resets it, so only the latest one counts
if (entry.type !== "user" || entry.isMeta) continue;
const body = text(entry.message?.content);
if (!body || body.startsWith("Stop hook feedback")) continue;
const m = MARKER.exec(body);
latest = m ? { id: m[1], outcome: m[2], at: Date.parse(entry.timestamp) || 0 } : null;

The new rule: the hook only cares about the latest thing you typed. If that's a brief, check for a report. If it's anything else, the brief isn't this turn's work and the hook stays out of it.

The skips matter as much as the rule. In Claude Code's transcript, a lot of entries are marked as coming from the user that you never typed: tool results, meta entries like system reminders, and the hook's own feedback. Once "latest wins", every one of those would wipe out the brief. A tool result arriving mid-turn would make the hook think you'd moved on. So tool results drop out (only text content counts), meta entries drop out, and anything starting with "Stop hook feedback" drops out.

Scope it to the current turn

Here's the general version, for any Stop hook: a Stop hook should judge this turn, not the whole session.

"Were the tests run?" means since the last prompt, not ever. "Was NOTES.md updated?" means since this turn started, not since Tuesday. Whatever condition you check, anchor it to the moment the current prompt arrived, and make sure the anchor is a prompt a person actually sent.

There are two ways to find that moment. The documented one is a UserPromptSubmit hook that records it, like the example above. It also receives the prompt text, so you can decide right there whether this turn is one you care about. Deiko's hook reads the transcript instead, which keeps it to a single entry in settings.json. The cost is depending on the transcript's format, which isn't a published API, and the docs warn the file can lag behind the conversation. The prompt that started the turn is written early, so it's there by the time Stop fires. I'd still parse it defensively, which is why every bad line is skipped rather than fatal.

How to test a Stop hook

Keep the decision in a pure function and the stdin plumbing in a few lines at the bottom. Then you can test the function with a fake transcript, built in the test as a few JSON lines:

test("a brief pasted earlier and then talked about does not nag later turns", () => {
  const t = (...entries) => entries.map((e) => JSON.stringify(e)).join("\n");
  assert.equal(latestBrief(t(brief1, later)), null);
  assert.equal(latestBrief(t(brief1, toolResult, meta, feedback)).id, "20260929-100000");
});

Deiko's six tests use node:test and nothing else. They cover blocking once and never twice, a fresh report against a stale one, a chat with no brief, garbage on stdin, and the bug above. Write the bug's test before the fix. Watching it go red is oddly satisfying.

Then do one end-to-end check with the real CLI, because a perfect function behind a mistyped path is a disabled hook. In a scratch folder, save the settings from the example as hook-settings.json and run:

claude -p "Add a comment to the top of app.js" \
  --settings hook-settings.json \
  --permission-mode acceptEdits \
  --debug-file hook.log

-p runs one prompt without the interactive UI, --settings loads your hooks for just this run, acceptEdits lets the agent write files without asking, and the debug log records which hooks matched, their exit codes and their output. Pass if NOTES.md exists afterwards and hook.log shows your Stop hook ran. All four flags are in the CLI reference.

If you've written a Stop hook that went wrong in an interesting way, I'd like to hear it. I'm @Deiko_App on X.

Stop hook not working? The usual causes

Most broken Stop hooks fail in one of five ways. Start Claude Code with claude --debug and the log at ~/.claude/debug/<session-id>.txt shows what each hook printed and how it was read.

It never fires. Type /hooks and check it’s listed under Stop. If it isn’t, the settings file is in the wrong place (.claude/settings.json for a project, ~/.claude/settings.json for everything) or isn’t valid JSON: no trailing commas, no comments. Stop takes no matcher, so a matcher won’t help. It also doesn’t fire when you interrupt Claude, and an API error fires StopFailure instead.
“Stop hook error” with a JSON validation message. Your output parsed as JSON but doesn’t fit the schema: a field at the wrong level, or a decision other than "block". To let the agent stop, print nothing at all.
“Stop hook error” with a parse message. The output started with { but wasn’t valid JSON, usually a quote inside the reason. Build it with JSON.stringify or jq, never by gluing strings together.
The JSON is ignored, with no error. Something printed before it, often an echo in your shell profile, so stdout no longer starts with { and Claude Code reads it as plain text. Wrap that echo in an interactive-shell check, or run the hook in exec form with "args": [] so no shell is involved.
It keeps blocking, then gives up. Claude Code overrides a Stop hook after eight blocks in a row and ends the turn with a warning. Read stop_hook_active and let the agent go when it’s true. And if your hook blocks on every turn, check that it’s judging the current one.

All of this is in the official hooks troubleshooting guide, which is worth a bookmark.

tl;dr Print {"decision":"block","reason":"..."} to keep the agent going. Check stop_hook_active so you ask once. Let every failure end the turn. And judge only the current turn: anchor your check to the latest prompt a person actually sent.

Questions people ask

How do I stop a Claude Code Stop hook from looping forever?

Read stop_hook_active from the JSON on stdin and let the agent stop when it is true. It is true when Claude is already continuing because a Stop hook blocked. Claude Code also overrides a Stop hook after eight blocks in a row, but you don't want to rely on that.

Should a Stop hook exit 2 or print JSON?

Either blocks the stop. Exit 2 uses your stderr as the reason. Exit 0 with {"decision": "block", "reason": "..."} on stdout gives you structured control. Pick one per hook. Exit 1 does not block: Claude Code treats it as a non-blocking error and the agent stops.

Does a Stop hook run when I press Esc?

No. Stop runs when the main agent finishes responding, not when you interrupt it. API errors fire a separate StopFailure event, and subagents fire SubagentStop.

Do I need a script, or can a prompt decide?

Claude Code also supports prompt and agent hooks on Stop, where a model decides whether the work is done, and a /goal command for one session. Use a command script when the check is deterministic, like a file's modification time or a test exit code.

Why is my Claude Code Stop hook not working?

Run /hooks to check it is registered under Stop, make sure the settings file is valid JSON in the right place, and start Claude Code with claude --debug to see what the hook printed. The most common silent cause is extra output, such as a shell-profile echo, before the JSON.

What does “Stop hook error: JSON validation failed” mean?

Your hook printed a JSON object that does not match the Stop hook schema, such as a misplaced field or a decision other than "block". The agent stops anyway. To block, print {"decision":"block","reason":"..."}; to let it stop, print nothing.

I open-sourced my Mac app for talking to coding agents. Here's how it works

Madhur Mittal — Wed, 30 Sep 2026 18:44:56 +0000

I've spent two months building Deiko, a Mac app for talking to coding agents, and today it's open source under MIT. Here's what it does and how the interesting parts work.

The two problems

Coding agents can't see what you're looking at. So you type a paragraph describing a screen they never saw, take a screenshot, attach it, then explain which part of it you meant.

And they forget. Every new chat with Claude Code, Cursor or Codex starts from zero, so on Friday you explain Tuesday's bug again, including the fix that already didn't work.

Showing instead of typing

Double-tap Right Option and talk. While you talk, you point at things with the cursor, or hold Left Option and draw around a region. Deiko records your voice, crops the screen around each point, reads the accessibility label under the cursor (a button's title, a cell's value) and notes the window and page titles.

When you stop, a small Node pipeline turns that into a brief. The interesting step is alignment: each word you said is matched to what you were pointing at when you said it, so "this price" and "that button" resolve to the right crop. Secrets are redacted before anything is written, and if a credential is visible in a screenshot, that screenshot is withheld and the brief says so.

A coin appears. Drop it on your agent's window and the brief is pasted and sent.

Remembering, without a vector database in the cloud

Every brief gets filed into the piece of work it continues, or starts a new one. Filing runs in two steps:

On your Mac: a keyword score (BM25) over each task's text, blended with a meaning score from EmbeddingGemma running on-device through ONNX. That gives a shortlist.
A small judge: the shortlist, with each task's title and recent summaries, goes to Jev, a small model that answers whether the brief is the same work, points back to earlier work ("remember the pricing fix? in that task…"), or is new.

Clear matches join, close calls ask "Same work?" on the card, and nothing you placed by hand is ever moved. The next brief on that task carries a note of where it stands and what was decided.

Agents that report back

Deiko ships a local MCP server with five tools: search_briefs, list_tasks, get_task, get_brief and save_outcome. Agents can look up earlier work when they need it, and when they finish a brief they save what they did, decided and left open, which feeds the task's note.

Agents don't always remember to save, so for Claude Code there's a Stop hook: if the agent is about to finish the turn a brief arrived in without saving, it's asked once to do so. It never asks twice in a row, and it stays quiet in chats that aren't a Deiko brief.

Privacy you can check

Screenshots, OCR and accessibility text never leave the Mac. Your voice goes to Whisper (with your own Groq key, through Deiko's relay, or not at all with Apple's on-device recogniser), and filing sends titles and summaries to Jev through the relay, which keeps nothing. Until today you had to take my word for that. Now the relay's code is in the repo.

What's in the repo

apps/macos: the Swift menu-bar app
packages/core: the Node pipeline and the MCP server
packages/alignment: word-to-pointer alignment (TypeScript)
services/relay: the relay (AWS Lambda)
evals: the filing, search and memory evals I use to check changes

Try it

curl -fsSL https://deiko.app/install.sh | sh

macOS 14+ on Apple silicon. Free, with two hours of hosted transcription a month; your own Groq key or on-device transcription works with no limit.

Repo: https://github.com/maddy30445r/deiko

There are a few good first issues open for Hacktoberfest (Zed support, README translations, a Homebrew tap). Issues and feedback are very welcome, especially about where the gesture gets in your way.

Security note: it asks for Accessibility, Screen Recording and Microphone access and captures only while a session runs (a red bar shows). Screenshots never leave your Mac. It isn't notarized by Apple yet, so read the install script first: https://github.com/maddy30445r/deiko/blob/main/scripts/install.sh

I spent a week teaching my Mac app to remember what I meant last Tuesday

Madhur Mittal — Fri, 25 Sep 2026 22:48:31 +0000

This happens to me about four times a day.

I find a bug. I explain it to my coding agent. We fix half of it. Three days later the other half turns up, and I'm explaining the whole thing again from scratch to an agent with the memory of a goldfish.

"No, not that price. The one on the pricing page. Remember? We tried the cache thing? It didn't work?"

It doesn't remember correctly.

So last week I gave my app a memory. This post covers that week: how I stumbled onto Jev, the homework I did on how other apps remember things, the moment my own board embarrassed me, and the small filing algorithm I ended up with.

Wait, what's Deiko?

Deiko is a Mac app I'm building. You double-tap a key, point at things on your screen and talk. Deiko turns that into a brief: your words, screenshots of what you pointed at, and the exact text that was on screen. Then you drag it onto Claude Code, Cursor or whatever agent you use, and it gets pasted in.

Every brief also lands on a board. That board is where the problem was hiding.

The problem with a pile

After a few weeks of use, my board was a pile. Eleven briefs from one design demo sat there as eleven loose cards. Three briefs about the same $99 price bug had, as far as Deiko knew, nothing to do with each other.

Each brief knew everything about its own moment and nothing about the one before it. What I wanted was easy to say:

Talk about the same bug on Tuesday and on Friday. Deiko knows it's the same bug, and Friday's agent knows what Tuesday's agent already tried.

Easy to say, anyway.

Enter Jev

Jev kept turning up on my X feed. It's a model from TypeSafe AI that does one narrow thing oddly well: you give it some facts and a typed question like "is this X?", and it gives you back a probability. You don't get an essay or a "Great question!", just a number.

That's exactly the shape of my problem. "Does this new brief belong to that old task?" is a yes/no question with a confidence attached. It's also cheap: TypeSafe's docs list $0.042 per million input tokens, and output is free. Sorting one brief costs me about a tenth of a cent.

So I went to sign up, full of momentum, and got this:

Whoops, we're full - check https://x.com/typesafeai for more information!

They had paused signups two days after opening them. Cool. Great. Love that for me.

Luckily the same model is resold at the same price through a few gateways, so I wired in Vercel's AI Gateway, OpenRouter and Cloudflare, and the week carried on.

Homework: how does everyone else do this?

Before writing any code I did the thing I usually skip: I read how other tools remember things. I skipped the landing pages and read the mechanisms: the docs, the source where I could, and the GitHub issues where people complain.

Where I looked	What I took
Claude Code's memory, Cursor's memories	Keep one running note per piece of work, with "where it stands now" at the top and a hard size cap
Mem0, Letta, Zep	Tools that classify every memory from scratch get the most "why did it merge these?!" complaints. Use cheap, exact clues first, and ask a model only when it's actually ambiguous
Obsidian, Notion, Granola	When a person files something by hand, that choice is final
Gmail threading	Exact clues beat fuzzy guesses. Email has a reply header; Deiko has the page or file you were looking at
Sentry's issue grouping	Clean up an error before you match it, so "line 42" and "line 43" count as the same crash
Search engines	Blend keyword search with meaning search, because each one catches what the other misses

One bug report stayed with me: a memory tool had saved the same memory 808 times, because it kept re-learning whatever it had just put into the prompt. Lesson noted: never learn back what you injected.

Three versions in one week

v1: chains. Each brief pointed at the one it continued. The result looked like beads on a string, and it barely helped. The eleven demo briefs were still eleven cards.

v2: tasks. Now a brief belongs to a task, and a task belongs to a project. Deiko keeps a note for each task: where it stands, what was decided, what was tried. When the agent finishes, it writes its outcome back into that note. To pick the task, I showed Jev a shortlist of 8 and asked "which one is this most like?"

I shipped it, re-sorted my real board and opened it up feeling rather proud.

The part where my own board embarrassed me

A question about a signup chart ("so here in week 32 chart...") was filed under Pricing, at 86% confidence.
A mic check, which was literally me saying "testing, testing, can you hear me", was filed as real work. Under Pricing too, naturally.
Every brief lived in a project called "Deiko", including the ones that had nothing to do with Deiko.

When I dug in, every mistake was mine, not Jev's.

I asked a question that always has a winner. "Which of these 8 tasks is it most like?" is like asking "which of these 8 people is your cousin?" when none of them is. Someone gets picked anyway.
Nothing asked "is this even a request?" So "hello hello" got filed like a bug report.
My shortlist favoured recent work over related work. Pricing was always in the running because I'd touched it recently.
One wrong join made the next one worse. I described each task by its newest brief. Once the mic test joined Pricing, Jev saw Pricing described as "they are testing the microphone". It snowballed.
I was ignoring my best clue. Chrome tells Deiko the page name ("Signups — build", "Pricing — build"). I saved it and never used it.

I was giving Jev a multiple-choice quiz when it's at its best with yes or no.

v3: a very careful librarian

v3 files a brief the way a careful librarian files a note.

1. Is it a note at all? Jev answers "is this a real request?" Mic checks, greetings and thank-yous go to a pile called mic checks & scraps.

2. Read the labels. Before any AI gets involved, Deiko reads exact labels off what it already recorded: the page, the file, the project, the error, the ticket number. Each one is tidied so two visits match. "(3) Signups — build" becomes "Signups". "/users/8812" becomes "/users/*". An error loses its line number (thanks, Sentry). Titles that don't name a real page, like "New Tab" or "Dashboard", don't count.

3. Cast a wide net. Up to 20 tasks get a seat at the table:

An exact label match gets a seat outright, unless that label is on more than 5 tasks. Looking at you, index.tsx.
Time words like "yesterday" or "last week" get a few seats. So do "kal" and "pichle hafte", because I narrate half my briefs in Hinglish.
The remaining seats go to a blend of keyword search (BM25) and meaning search. The meaning part is a small model that runs on your Mac (Microsoft's harrier-oss-v1-270m, about 200 MB, around 70 ms a brief), so "the graph thing" still finds your chart work even when no word matches.

Recency gets no seats any more. It only breaks ties.

4. Ask yes or no, once per task. In one request, Jev answers "is this the same piece of work?" for each of the 20 tasks. Every task gets its own probability, and they don't have to add up to 100%. The question says plainly that the same app or the same topic isn't enough.

5. Look twice at the finalists. The one or two tasks that scored 35% or more each get a private second request containing just the new brief and that one task, so nothing else can sway the answer. It asks the same question again, plus one more: are these different, related but separate, or the same work?

6. Decide in boring code. Jev only gives numbers. The rules that turn numbers into decisions live in my code, in one place, with tests:

export const GATE = 0.5;  // below this, it's a mic check
export const JOIN = { first: 0.6, second: 0.4, gap: 0.2, recent: 0.5, recentMs: 30 * 60e3 };
export const ASK = 0.35;  // between this and a join: ask the human

A brief joins a task only when the second look says "same", round one is at 60% or more, and that task is 20 points ahead of the runner-up.
Work from the last 30 minutes on the same page or file joins a little more easily. Old tasks never get that break, so they can't quietly swallow new work.
A different ticket number (ENG-142 against ENG-150) never joins.
For a maybe, the brief starts on its own and its card asks "Which one?" with the likely tasks as buttons. One click fixes it.
Related but separate work gets a "Related to Pricing" link instead of a merge.

Plot twist: Jev is shy

My design doc said "join when the second look is 90% sure". Sensible and principled.

It joined nothing. Zero briefs.

Before building v3 I had made a test set from my own board: real briefs, each labelled by hand with where it belongs. Every change had to beat the previous run. On the ten briefs that truly belonged together, Jev's one-on-one "yes" sat between 0.43 and 0.88. It said "same" every single time. It just wouldn't say it loudly. Meanwhile, every brief that really was new had its best match at 0.23 or lower.

So the numbers in that snippet came from my data, not from a hunch. If you take one thing from this post, make it this: build the test set first. I was confidently and completely wrong about the thresholds.

Where it stands now: 28 of the 33 labelled briefs land where I'd put them by hand, and about one real brief in nine gets a "Which one?" card. I watch that second number closely. If it creeps past one in four, people start clicking anything to make the card go away, and then memory is worse than no memory.

Letting the agent dig for itself

Filing will sometimes be unsure, so the agent shouldn't have to depend on a single guess.

When a brief joins a task, the agent is told: this carries on from "Pricing display bug", where it stands, and the last few briefs, one line each. When it's only a hunch, the prompt says so: possibly related, not confirmed. The whole memory section stays under 20 lines.

There's also a small memory helper, an MCP server that runs only on your Mac, with three tools: search_briefs, get_task and get_brief. Say "like the chart thing from last week" and your agent can go and find it itself. One button in Settings sets it up for every agent Deiko finds on your Mac.

The search covers everything on your Mac, but it hands back much less, because the answers go to your agent's cloud model. You get your briefs, the agents' notes and the screenshots you kept. Screenshots you removed stay removed, audio never leaves, and anything that looks like a secret is scrubbed first. That last rule isn't hypothetical: our security audit once found a live API key in text Deiko had captured from the screen.

What it feels like now

On Thursday you point at the pricing page and say "the price still shows $99 after I edit it". Your agent tries a cache fix. On Monday you point at the same page: "still broken."

Deiko files Monday's brief under Pricing display bug. Monday's agent gets the note saying the cache fix was tried and didn't work, so it starts from there instead of from zero. You didn't have to explain anything twice.

Things I'd tell myself a week ago

Ask yes or no, never "pick one". A pick-one question always has a winner.
Use exact clues before fuzzy ones: page names, file names, ticket numbers.
Describe things by what you're sure of, never by whatever came in last.
Keep the decision in your own code, with the numbers in one place.
Build the test set before the feature. Your thresholds are wrong.
When you're unsure, ask the human once, with buttons.

Try it

Deiko runs on macOS 14 or later, and Pro is free until 24 October 2026.

curl -fsSL https://deiko.app/install.sh | sh

The site if you want more info -

Deiko: show, don’t type

Point at anything on your screen and say what should change. Deiko throws your coding agent a brief with the screenshot attached.

deiko.app

If you've built memory for anything, I'd love to hear what broke for you, and which of my thresholds you think will age worst. Leave a comment below.

I am tired of taking screenshots and explaining them to Claude code while working.

Madhur Mittal — Thu, 17 Sep 2026 18:21:24 +0000

Okay so a little context first,
I work in an SDE role and work in multiple windows at once like i have many apps open in my mac.
I faced a problem of screenshotting everything and explaining the context and their relations to claude code again and again like for little UI changes and such or any bug.
I got this idea and started working on it , made a swift app which will track cursor and when your press a hotkey it starts only then and when you hold a hotkey it will draw over the areas your point with your cursor and you can keep talking while explaining what you need like you would to a real colleague. The voice timings come from whisper and they get attached with the cursor positions and screenshots and form a full event files.
those get stored as context everytime you do some actions like draw a circle , point to anything or something like that.
and at the end we generate a context using those events that you can just drop to any AI agent of your choice like claude,cursor,codex etc. and it just starts working on it right off the bat.

A bit on how it works
The hard part was never the screenshot. It's the word "this".

"Add a status key to this response" means nothing on its own. It only works if you know what "this" was aimed at. So while a session runs I keep two streams: where the cursor settled, and what you were saying at the time. Then I have to figure out which settles were actually pointing at something and which were just my hand sitting on the trackpad. Cursor position alone can't tell you that.

What worked was watching for the pointing words. If "this" or "here" lands on a settle, that settle was a pointing act. If a settle sits in the middle of silence, it was nothing. That binding is most of the app.

For the screenshot side I use AXUIElementCopyElementAtPosition against a system-wide element, which gives me whatever is under the cursor plus its accessibility label and window title. SCScreenshotManager crops the pixels and Vision runs OCR on the crop. So the brief ends up carrying the name of the thing you pointed at and not just a picture of it, which is usually what the agent was guessing at anyway.

There are no accounts. The trial is keyed to a hash of the machine's platform UUID rather than anything in preferences, so deleting a plist doesn't get you a fresh one. Screenshots, OCR text and the brief never leave the Mac. The audio is the only thing that goes anywhere and it's gone as soon as the text exists.

Here is the producthunt page for more context on it:

producthunt.com

And below is the site to get it:

Deiko: show, don’t type

Point at anything on your screen and say what should change. Deiko throws your coding agent a brief with the screenshot attached.

deiko.app

I am thinking of providing a free version with BYO option and a lifetime subscription for around 40ish dollars.
Need some advice and people who face this problem and what do they generally use to solve it?