Gaurav Manek

Agentic AI for Beginners Workshop

Thu, 06 Aug 2026 00:00:00 +0000

If you’re here for the workshop, welcome! Add me on LinkedIn.

If you haven’t already, please sign up for the following — they’ll give you free (or free-to-start) access to the agents and models we’ll be working with:

During the workshop, we’ll be deploying AI agents for:

simple data extraction task and a
multiagent task.

The slides and source code are available under CC BY-SA 4.0 license.

Ready to build? The Build Your Own Agent Workshop is the build-heavy follow-up to this session.

Reading List

When writing prompts, I recommend keeping up-to-date on industry best-practices. Some good places to start:

If you’re looking for skills, start here:

There are plenty of skills for specific tasks and tools. If you can’t find exactly what you need, you can always deploy the Skill Creator skill. Feed it some documentation and examples and it will generate a skill for you. It may be the most important skill of all.

(Be warned: its easy to smuggle malicious code and prompts in with skills. Check them carefully.)

For more general reading:

My AI Platforms Lecture, including open-source as a defensive and offensive maneuver
This CGP Grey video
Sizes of LLMs
Chesterton’s Fence, or in short: “Do not remove a fence until you know why it was put up in the first place.”
The Men Who Killed Google, for how overreliance on metrics (rather than product quality) leads to short-term gains at the cost of long-term goals.
Apodex 1.0, a bet on swarms of small models that verify and rewrite each other’s work — a possible future alternative to scaling one giant model.

As always, turn your critical thinking skills on and carefully engage with the claims each source makes. Test what you can

An Answer-Sheet Scanner

Wed, 08 Jul 2026 00:00:00 +0000

Following the previous experiment on grading answers, I thought I’d play around with even more local VLMs by running one directly in clients’ browsers.

With the help of Fable, I built a purely client-side pipeline that uses a mix of classic computer vision techniques and a VLM to grade multiple-choice questions. Try it: gauravmm.github.io/answer-sheet.

The pipeline is simple. Classical computer vision:

deskews the image,
locates the grid from the answer boxes’ own printed edges, then
classify each cell by how much ink is inside it.
infers the coloration.

The only ML in the product is a small handwriting model for the three header fields.

At first, Fable (at my direction) attempted to use Granite-Docling. It could read the structure perfectly but couldn’t reliably say which column each mark was in. VLMs in general are known to be weak at exactly the spatial-grounding job a dense grid demands. After testing it, Fable switched to a classical pipeline. On its test cases, it scores every mark correctly, in milliseconds, at a fraction of the download.

If I had to use a VLM, I would likely label each cell uniquely, removing the spatial-grounding requirement entirely.

The source, the sheet, and the full spec are on GitHub.

A completed answer sheet, photographed on a phone. [Download it](demo-sheet.webp) and feed it to the app.

One-Shotting a Grading Rig with Fable

Sun, 05 Jul 2026 00:00:00 +0000

Like the rest of the world, I am very impressed by the long-term capabilities of Anthropic’s latest model. Having a little usage to spare, I decided I would try it on a cute little idea that I have been sleeping on.

The idea: a fixed camera and a projector, both pointed down at a paper jig on my desk. Drop a handwritten exam answer into the jig, a local VLM grades it, and the projector draws the marks — ticks, the score, a one-line remark — back onto the paper, registered to the right spot on the page. I wrote a spec, handed it to Fable, and asked it to produce a working MVP. The whole thing came together in a single conversation.

What Fable can do

On its own initiative, Fable did some impressive things that I wouldn’t have bet an AI would be able to do:

Calibrated the jig by superimposing a grid and reading off the coordinates.
Calibrating the projector by projecting dots and differencing frames to find them.
Generating its own synthetic test data with realistic transforms.
Debugging a MacOS window-handling issue.
Figuring out color-channel issues

It worked autonomously for about forty minutes, and had a working prototype. It built the product up by layer by layer, instead of all at once, and built up a set of experiments and tests to validate at each step of the way.

One live grade, end to end: blank the projector and capture, flatten the page with a homography, crop to the known answer box, grade it with a local VLM, render the annotation in paper coordinates, then warp that onto the projector so it lands on the page.

My hands

My contribution to the endeavour was the design and assembly of the jig, some mild discussion in writing the spec, and swapping in pages on request.

The full source is on GitHub, and Fable’s own unedited writeup on the session is fascinating. It almost (but not quite) thinks like a human would.

The rig grading a real page, hands-free: present the paper, the marks land back on it.

Build Your Own Agent Workshop

Tue, 23 Jun 2026 00:00:00 +0000

If you’re here for the workshop, welcome! Add me on LinkedIn.

This is the build-heavy follow-up to the Intro to Agentic AI session. The basic workshop covered concepts; this one is about shipping. (You don’t have to participate in that to apply for this.)

The slides and source code are available under CC BY-SA 4.0 license. Setup guides and reference material are in the intermediate-agentic-ai-resources repo.

You’ll come in with a team, a real problem, and real data, and leave four hours later with a working agent that someone on your team will actually use next week. Expect a 15-minute talk, then heads-down building with hands-on help.

Teams are product-focused by design: each one pairs engineers with the actual users whose problem is being solved. You have to specify your users and your projects when you apply for this workshop.

Before you apply

We know we’re asking a lot for a 4-hour workshop. The bar is high on purpose: every hour spent upfront understanding the problem and lining up real data is an hour we don’t waste in the room with a half-formed brief. We’ll be bringing together a lot of resources for this workshop, so its important we set ourselves up for success.

We’re capping the first cohort at 8 teams. If you apply now and don’t make it in, you go to the front of the queue for the next round, so it’s worth getting your one-pager in even if you’re not 100% sure your project fits.

Projects

A good workshop project is:

Bounded. The minimally useful user story can be demo-ed in 90 seconds and is buildable by 2 engineers in ~2.5 hours of build time.
Real user in the room. At least one team member personally has the problem the agent solves and will be the demo’s first user.
Real data in the room. 5+ representative examples available on workshop day, from a personal laptop, without violating the constraints below.
Internal-facing. No public users, no anonymous access, no autonomous external actions.
Evaluable. You can describe, in one sentence, how you’d tell if the agent is doing a good job. “It feels right” is not evaluable; “matches the expert’s answer on 8 of 10 known cases” is.
Agentic, not just a prompt. The project requires at least one of: tool use, retrieval, multi-step reasoning, sub-agents, or self-critique. A single-shot prompt-and-response chatbot is not a workshop project.

Note that these are application-agnostic. We’ll accept projects from any area.

Disqualifying properties

A project is disqualified if any of the following are true:

Requires data or systems the team can’t access from a personal laptop on workshop day.
Touches PHI, PII, financial records, security credentials, or anything else where a leak would matter.
Output goes to a customer, patient, regulator, or other external party without a human review step.
Requires training or fine-tuning a model. Frontier models with good prompting and tool use only.
Depends on a specific person who isn’t on the team (“we’ll get input from Legal”).
“Build a platform for X.” Platforms are not 3-hour projects.
Makes autonomous changes on external systems.
Is a trivial RAG over a document pile. You can learn that from LinkedIn.

My goal is to help you avoid these pitfalls that make projects balloon quickly out of scope.

Project ideas

Here are some starting points. You don’t have to pick from this list, but a good project will look a lot like one of these:

#	Name	Description
1	Calendar & todo chatbot	Manages calendar events and todo lists conversationally. Resolves conflicts and reasons about priorities.
2	Market & competitor research	Researches a market landscape and specific competitors. Produces structured briefs with sources.
3	Work instruction check & writeup chatbot	Follows along with a technician as they complete a work instruction, prompts them for details and next steps.
4	Document sorter & summarizer	Sorts and summarizes a document corpus for quick lookup. Surfaces the right passage on demand.
5	Patent research bot	Searches patent databases and parses claims for a target area. Surfaces relevant prior art with citations.
6	Research paper triage agent	Pulls related work from PubMed/arXiv/ChemRxiv and ranks by relevance to the user’s project. Produces a “what’s new and why you care” brief.
7	Experiment protocol checker	Reads a draft protocol and flags missing controls, ambiguous steps, safety issues, and SOP deviations. Embedded user = anyone who’s reviewed a junior person’s protocol and wanted to cry.
8	Safety + SDS assistant	Given a planned experiment, pulls SDS sheets for each chemical and summarizes incompatibilities, required PPE, and waste handling. Catches the spicy combinations before they happen.
9	Test protocol drafter from a requirement	Given a design requirement, drafts a bench test protocol with apparatus, procedure, acceptance criteria, sample size, and applicable standards. Backtest against existing protocols the lab has written.
10	Bench test data analyzer	Pick one type of test the lab runs frequently and build a pipeline to run standard analyses, generate plots, and draft a results section.

Minimal technical requirements

Personal laptop, not ITSS-managed. You need to install things without filing a ticket.
- If it’s Windows, install WSL2, uv, and nvm. Use Visual Studio Code.
- If it’s a Mac, install Homebrew or Zerobrew, uv, and nvm. Use Visual Studio Code.
- If it’s Linux, Godspeed to you.
Each person must have a subscription to a frontier model. Active and logged in before the workshop starts.
- Claude Pro and Codex Plus, strongly encouraged.
- Kimi Allegretto, OpenCode Go, Z.AI GLM Lite, etc. acceptable. (Limited support.)
- GitHub Copilot discouraged (poor billing model), Cursor discouraged (lack of direct AI access).
- If you don’t know what to choose, get a month of Claude Pro. My referral code gives you the first week free.
Any API keys or credentials your project needs (internal docs, instrument output folder, etc.) tested and working on workshop day. If you can’t connect to it from your laptop the morning of, you can’t use it.
- Only exception is the calendar, which we can provide a connector for.

Group requirements

Must bring data. At least 5 real examples of whatever your agent will process — protocols, documents, instrument files, questions with known answers, etc. Synthetic examples are fine if real data can’t leave its home system, but they must be representative.
Team of 2-4 people, max 4.
- Minimum 2 engineers with working Python or TypeScript.
- Minimum 1 actual user who would personally use what you build.
- A team member may be either, both, or neither.
Pre-submitted one-pager (see below) reviewed and approved before workshop day.
Stuck for 10 minutes? Raise your hand. No silent struggling.

Application

The application form asks for:

Team name.
2-4 members. For each: name, role (engineer / user / both), and which frontier-model subscription they’re bringing.

You’ll also have to confirm that:

at least 2 engineers with working Python or TypeScript (even at a very basic level is fine),
at least 1 person who would personally use the thing you’re building.
every member, especially non-engineers, have an active frontier-model subscription by workshop day.

Problem explainer

Problem: what’s painful today, one paragraph. Include how often it happens and roughly how much time it eats.
User: who exactly, and which of them is on the team. “Our PMs” is too vague; “Sarah, who is on this team” is right.
Inputs & systems: what data, APIs, or docs the agent needs, and confirmation you’ll have working access from a personal laptop on workshop day.
Happy-path demo: two sentences describing the exact scenario you’ll show at the end.
Success criteria: one sentence describing what counts as success after you leave the workshop. e.g. “Sarah uses it at least once next week without help.”

User stories

3-5 concrete user stories in the form: As [specific person], when [trigger], I want [action] so that [outcome].
1 minimally useful user story marked clearly — this is your build goal for the day.
- If you only ship this one, the day was a win.
- Must be demoable in under 90 seconds.

Data

Describe the 5 real (or representative synthetic) examples you’ll bring. What are they, where do they come from, and is anything sensitive that needs anonymizing first?

Risks

Does your project satisfy all the required criteria and avoid all the disqualifying ones? If not, address it here.
Biggest unknown (in one line).
Anything you need from the host (sample data, an API you don’t have access to, a specific library).

Agentic AI for Beginners Workshop

Mon, 22 Jun 2026 00:00:00 +0000

If you’re here for the workshop, welcome! Add me on LinkedIn.

If you haven’t already, please sign up for the following — they’ll give you free (or free-to-start) access to the agents and models we’ll be working with:

During the workshop, we’ll be deploying AI agents for:

simple data extraction task and a
multiagent task.

The slides and source code are available under CC BY-SA 4.0 license.

Ready to build? The Build Your Own Agent Workshop is the build-heavy follow-up to this session.

Reading List

When writing prompts, I recommend keeping up-to-date on industry best-practices. Some good places to start:

If you’re looking for skills, start here:

(Be warned: its easy to smuggle malicious code and prompts in with skills. Check them carefully.)

For more general reading:

My AI Platforms Lecture, including open-source as a defensive and offensive maneuver
This CGP Grey video
Sizes of LLMs
Chesterton’s Fence, or in short: “Do not remove a fence until you know why it was put up in the first place.”
The Men Who Killed Google, for how overreliance on metrics (rather than product quality) leads to short-term gains at the cost of long-term goals.
Apodex 1.0, a bet on swarms of small models that verify and rewrite each other’s work — a possible future alternative to scaling one giant model.

As always, turn your critical thinking skills on and carefully engage with the claims each source makes. Test what you can

How I choose the task a workshop lives on

Sun, 21 Jun 2026 00:00:00 +0000

Last time I wrote about KittenClaw, the teaching harness I built so a room full of beginners could get an agent running end-to-end on free tiers without losing the first forty minutes to setup. The harness solves the plumbing. It says nothing about the harder question, which is what you actually point it at.

That question matters more than the harness does. For a lot of the people in the room, the workshop is their first real contact with an agent. If that contact goes badly, if the task is confusing or fiddly or spits out pages of output nobody can read, they don’t just fail the exercise. They walk away with the quiet conclusion that this stuff is finicky and not for them, and I’ve probably delayed their next attempt by months. The first task is the make-or-break example, and I’ve come to treat it with far more suspicion than the code around it.

So here is the rubric I use to choose it. It is deliberately opinionated, because every one of these rules is scar tissue from a task that went sideways.

Form: remove every excuse not to start

The first job of the task is to have nothing standing between a person and their first result.

No programming background can be required. The moment a task assumes someone is willing to write two lines of python, I’ve cut my enrollable audience by ~80% and added friction for 80% of who’s left. Whatever the task is, it has to be legible to someone who has never opened a terminal. And if it rewards someone who can, that reward has to be optional.

It has to run on cheap or free tiers, and it has to be indifferent to which provider supplies them. I don’t want the exercise to break the day a free tier changes its terms, and I don’t want to be shilling for anyone. The same task should run on whatever model the room can get for nothing.

It has to run in the browser. Every local install is a fork in the road where a third of the room ends up somewhere I can’t help them from the front. And the whole interaction has to be visible, with no step happening on someone else’s server where we can’t watch it. This is the same instinct that made KittenClaw three readable files with its whole memory on disk: if a beginner can’t see it, they can’t learn from it, and they certainly can’t trust it. Finally, a human has to be in the loop. A task that runs to completion on its own is a demo, not an exercise.

Scope: a toy of a real thing

Get the form right and you’ve earned the room’s attention. Scope is how you keep it.

The interaction loop has to be short enough to feel immediate. Change the prompt, change a constraint, and see the outcome in seconds. That tight loop does the teaching. It’s what turns “I read that prompts matter” into “I felt that prompt change the answer.” Anything that puts minutes between a change and its consequence kills the intuition before it forms.

The knowledge base has to be small, fixed, and boring. No loading documents, no managing state mid-exercise, and absolutely nothing proprietary. Data management is friction and proprietary data is risk, and neither teaches anything about agents. The reasoning has to be shallow for the same reason the models are cheap: I don’t want thirty people debugging a subtle chain of logic on a free tier. Short steps, obvious failures.

And the task has to sit in a specific sweet spot. It should be a toy version of a real workflow, close enough that an attendee can see the analogy to a system that would actually earn its keep. But it can’t be so simple that a regex or a spreadsheet would do it. If a non-AI tool solves it cleanly, the exercise teaches that agents are pointless. The whole thing works only if success and failure are both obvious the instant they happen. No rubric, no “well, sort of.” It worked or it didn’t, and everyone can see which.

Two guardrails do a lot of work here. Avoid anything that’s already a solved product, like transcription, document Q&A, or deep-research-over-a-corpus, because the interesting engineering has been done and hidden, and there’s nothing left to feel. And avoid anything a five-line script would nail, for the opposite reason. The task has to live in the gap between “trivial” and “already a product,” which is exactly where the useful agentic work lives too.

Difficulty: one task, every skill level

The last problem is that the room is not uniform. In the same thirty people I’ll have someone who has never used a chatbot sitting next to someone who writes Python for a living, and the task has to land for both.

So the task has to be modular. There’s a version you solve by editing a prompt in plain English, and a version you solve by changing the tools underneath, and the same exercise has to admit both without either group feeling cheated. For the people who finish early (and someone always finishes early), the task needs room for adversarial constraints. A user who won’t commit to an answer, a requirement that the bot collect something it doesn’t obviously need, an edge case that turns a clean solution into a pile of blanks. Realistic difficulty, handed out on demand, so the fast solvers stay in the problem instead of getting bored and skeptical.

And there has to be a moment of wow. One beat that teases what comes after the workshop. The one I use is agent-driving-agent: a coding assistant driving KittenClaw, writing a prompt on its own, holding a whole conversation with the bot and then grading the transcript. The triage exercise I ship with KittenClaw is built to pay all of this off at once: a bot that has to gather information it doesn’t itself need because a second agent will. Modular and adversarial at once, in fifteen lines.

None of these rules are clever. They’re just expensive to learn the other way. The harness took a weekend; the rubric took years of teaching.

How to Build Evals for AI Agents

Thu, 04 Jun 2026 00:00:00 +0000

If you’re here from the talk, welcome! Add me on LinkedIn.

The slides are available under CC BY-SA 4.0 license. Feel free to use them for your own purposes.

If you remember nothing else from the talk, remember these three things:

Your test set is your spec. If a behavior isn’t in the eval, it isn’t a requirement. Make the set diverse on purpose — happy path, boring edge cases, known failure modes, adversarial inputs, and “things the agent shouldn’t do”.
Evals are never done. Pull real production traces into your test set every week, or it will drift away from your users.
Evals are not a substitute for good infrastructure. A broken retry loop, a missing timeout, or a tool call without an idempotency key will hurt you more than a 2% accuracy regression. Evals tell you what is wrong; infrastructure decides what happens when something is wrong.

If you want to try out your newfound knowledge on a very simple agentic task, take a look at my AI Triage Bot via KittenClaw. Your coding agent can run the bot interactively and develop both the solution and the evals as it goes. It’s a great sandbox to play in.

Reading List

The eval space is moving fast, but a few pieces have aged well. Start at the top, work down — these are written for builders, not researchers, and assume no ML background.

LLM Evaluation: a Beginner’s Guide by Evidently AI — if “LLM-as-a-judge” isn’t yet a phrase you’d use in a sentence, read this one first. It assumes no ML background and lays out the vocabulary the rest of this list takes for granted.
An LLM-as-Judge Won’t Save The Product — Fixing Your Process Will by Eugene Yan — start here. The closest single piece of writing to the spirit of this talk: the process around your evals matters more than the cleverness of any individual grader. Pairs directly with Lesson 3.
Your AI Product Needs Evals by Hamel Husain — the post that crystallised the field; case-study driven and refreshingly opinionated.
A Field Guide to Rapidly Improving AI Products by Hamel Husain — tactical follow-up, with the look-at-your-data flywheel I gestured at in Lesson 2. Also his article Using LLM-as-a-Judge For Evaluation, which explains the whole process in exhaustive detail.

For more detailed reading:

Task-Specific LLM Evals that Do & Don’t Work by Eugene Yan — secondary reading once the process post lands; a tour of evaluation dimensions with real examples of where each grader breaks.
Simon Willison’s evals tag — a running commentary on what works and what doesn’t in practice. Great for absorbing taste in small doses.
Scaling Up “Vibe Checks” for LLMs by Shreya Shankar (Stanford MLSys #97) — the same lessons in talk form, if you’d rather watch than read.

As always, turn your critical thinking skills on and carefully engage with the claims each source makes. The field is young enough that any “best practice” you read today may be embarrassing in eighteen months. The way you find out is by running the evals yourself.

If you liked my talk, feel free to check out other talks I’ve given. A natural next stop is Infrastructure-based Safety for Your ‘Claw, which picks up where Lesson 3 leaves off.

Small Tools for AI Development

Tue, 02 Jun 2026 00:00:00 +0000

Tools built for AI to use

jqi — structural JSON profiler so an agent can grasp the shape of a huge JSON blob without paying to read all of it. — post · github
mcp_gateway_maker (the MCP filter) — AI-built tool for making MCP proxies with security features: a layer in front of a server that rewrites or blocks each call. — post · github
claudenlos — static analyzer over Claude’s logs that finds, tool by tool, where the tokens actually go. — post · github
zsh-reap — zsh plugin that tracks long-running foreground jobs and lets an agent (or you) restart them from another terminal. — post · github

Watching and orchestrating agents

tasklight — always-on-top desktop overlay (HUD) for watching local AI coding agents work. — post · github
tmux-orchestra — pure-POSIX-shell tmux plugin exposing an orchestra CLI for agent status, notifications, and prompt-published context, rendered in a dedicated sidebar pane. — github

Harnesses you can read

KittenClaw — minimal, readable chat harness for teaching the agentic loop; runs on free tiers. — post · github
benchclaw — ultra-lightweight personal AI assistant / agentic testbed (Telegram and other channels). — github
TeachClaw — in-class teaching assistant students chat with on Telegram. It’s the chat layer over the knowledge bases below, citing every claim through the citation back-pressure system. — github

Knowledge bases agents read from

knowledgebase-agenticai — curated workshop corpus for the agentic-AI lecture; owns the library only, served to the bot over MCP with citations. — github
knowledgebase-businessai — curated reference library for the AI-in-business lecture: ingest scripts, manifests, and a search/fetch_doc MCP server. — github
cute-db — indexes cute-animal images and clips with a vision-language model, stores descriptions in SQLite, and serves keyword search over MCP (a testing/demo corpus). — github

An AI Agent Small Enough to Read

Mon, 01 Jun 2026 00:00:00 +0000

I teach a hands-on workshop on agentic AI for beginners. The concepts are not the hard part — the agentic loop is genuinely simple once you see it — the hard part is the first forty minutes. Thirty people with thirty laptops in thirty different states, and the lesson can’t start until everyone has Python, a model to talk to, and an API key. It can take thirty minutes until the slowest person is ready to learn.

Instead of fighting more complex setup and diluting the workshop content, I’ve built KittenClaw. A minimal chat harness for teaching agentic loops, small enough that a beginner can read the whole thing in one sitting, and light enough to run end-to-end on free tiers. There are three layers to it, and not one of them sends a bill: the runner is a GitHub Codespace on the free allowance; the model driving the agent comes from a provider with a genuine free tier like OpenRouter; and you develop against it with whatever coding harness you already have, which for us is GitHub Copilot.

Small enough to read

The entire runtime is three Python files: the tools, a thin Telegram adapter, and the full agentic loop in plain view. That’s deliberate, because the loop is the thing you came to learn. A beginner can open all three files and follow what happens between typing a message and getting a reply.

The agent’s entire state lives on disk as JSON Lines, letting students inspect and follow exactly what the agent is doing, with nothing hidden. When something goes wrong, you open the file and read exactly what the model saw, in order. Once a student internalizes that the transcript is the whole story, agents stop being magic and start being a program they can reason about.

Setup is a browser tab

Here’s the part I’m proudest of: the entire stack is assembled from free tiers, top to bottom, and nobody in the room spends a cent. The compute is a GitHub Codespace, or GitLab’s equivalent Workspaces, on the free allowance — fork the repo, open it in the browser, and the devcontainer installs Python and uv, syncs the dependencies, and lays out the .env for you before you’ve touched anything. No local toolchain, no “works on my machine,” no Python 2.7 from 2019 lurking on someone’s laptop.

The model is whichever provider you like that has a genuine free tier — Google AI Studio, OpenCode Zen, or OpenRouter — none of which want a credit card to get started. The chat app is Telegram, free, reached by long-polling so it works even in corporate environments with NAT and punitive firewalls. Skill development also can be run in the free tier of a coding assistant — GitHub Copilot or OpenCode Zen. Paste your key and a bot token into the .env, and you’re running.

Bending it into a task

KittenClaw on its own is just a harness. The interesting part is how little it takes to bend it into a real exercise. Its a tiny tool that can be hammered into whatever shape is needed for your teaching scenario. Choosing which shape is its own problem, and a surprisingly load-bearing one — I wrote up the rubric I use to pick the task separately.

The scenario I ship is a medical triage bot: it interviews a patient about their symptoms, classifies them as minor, moderate, or severe, and routes accordingly — book an appointment, escalate to the ER, or close the conversation. What makes it more than a toy is the second agent. A separate reporter bot, implemented as a GitHub Copilot skill, reads the archived conversations afterwards and extracts a structured intake record: name, age, symptoms, triage level. The two agents never call each other. They only share the conversation files.

That constraint is the whole lesson, and it’s one I keep coming back to in my own work: the triage bot has to collect information it does not itself need, because the reporter needs it. Students discover this the hard way, by building a bot that triages perfectly and produces reports full of blanks. From there the failure modes write themselves — a bot that schedules appointments nobody asked for, one that misses an emergency, one that confirms a booking without the date, one that treats a rejected date as a terminal error instead of backpressure to retry against. Each is a small, concrete bug with a real-world analogue, and each is debugged by reading a file.

Putting a smarter model on the other end

Because the whole bot is a command you can script and a file you can read, nothing says the thing on the other end of the conversation has to be a human. You, or your favourite frontier model, can drive a conversation from the shell:

uv run python -m kittenclaw --once "Hello, how are you doing?"

This trick is one that I most enjoy showing students: tell a strong model to role-play someone with chest pain who keeps downplaying it, or who won’t commit to an appointment date, let it hold a full conversation with KittenClaw, and then hand it the resulting transcript and ask how the triage bot did. The same file that is the agent’s memory becomes the test case and the report card.

That closes a loop worth understanding. A small, cheap model runs the task; a smart model invents the awkward patients, plays them out end to end, reads the file, and proposes edits to the prompt and the skills. You can run that cycle dozens of times in the time it takes to hand-write one good test conversation, and the bot that comes out the other side has been hardened against cases you’d never have thought to write. Using a stronger model to improve a weaker one’s instructions is one of the most practical skills in the field right now, and KittenClaw is small enough to show the whole mechanism rather than just describe it — which is exactly why I teach the end-to-end loop on it.

Why the small version teaches better

A framework that hides the loop teaches you the framework. For an application that’s exactly what you want; for a beginner trying to understand what an agent is, it’s backwards. KittenClaw keeps the loop, the tools, and the state all in view and on disk, cheap enough to run that nobody has to ask permission, and small enough that the source isn’t a wall to hide behind. The slides can tell you an agent is “a model in a loop with tools and memory.” It lands a lot harder when the loop is twenty lines you just read, the memory is a file you just opened, and the whole thing — compute, model, chat app, and the second agent besides — has been running on free tiers, in a browser tab, for the price of nothing at all. That last part isn’t a footnote. It means the only thing a student needs to bring to a real multiagent system is curiosity, and that’s the point.

The slides and source for the workshop are on GitHub under CC BY-SA — take them and teach your own.

Restarting Foreground Jobs Without Touching the Terminal

Sat, 23 May 2026 00:00:00 +0000

You’re working with an agent in one terminal while a dev server runs in another. Sooner or later, the agent needs to restart the server, but has no idea how you started it, which terminal it’s in, or what its PID is. So all progress grinds to a halt until you notice that its asked you to do something trivial.

zsh-reap is a tiny zsh plugin that fixes this. Foreground jobs running for at least five seconds are watched, killable, and restartable from any other terminal (including an agent’s Bash tool) like this:

$ zsh-reap list
ID         PID     SHELL   CWD                  UPTIME   COMMAND
1319a-8e   78234   ttys003 ~/work/myapp         0:14:22  npm run dev
138f0-1f   80112   ttys005 ~/work/myapp/api     0:02:11  cargo run --release

$ zsh-reap restart 1319a-8e

The restart lands in the original shell — same $PATH, same $VIRTUAL_ENV, same nvm version, same everything. From the user’s point of view the terminal looks exactly as if they’d hit Ctrl-C and re-typed the line.

Tightly scoped

I built this for a single specific scenario: long-running foreground jobs to kill and restart. A few decisions worth flagging:

Restart only works in the originating shell. The restart runs inside the same live shell as the original invocation and inherits env vars, history, sockets, etc. for free.
Restarts run the whole command string. No changes, nothing else. If you need those, your agent can kill the job and run it again.
Foreground only. Background jobs (&) are already handled by jobs/fg; users have a mental model for those.
Minimal dependencies zsh, ps, pgrep, kill. No jq, no Python.

How does it work?

I’m not sure myself. Your agent could read the spec that my agent wrote up and explain it to you better than I could.

Why this matters

This isn’t a flagship tool. It’s a microscopic zsh plugin that solves one specific friction. The interface is zsh-reap list/restart, and it works the same way from a tmux pane, a script, or a Claude Code Bash tool call.

The shape of the solution is worth repeating: small agent-friendly tools that ease small and specific problems in human-agent collaboration. (jqi, which I wrote up earlier this year, is the same instinct applied to JSON exploration — different problem, same tiny shape.)

I’m betting (along with a large part of the ecosystem) that a large part of the savings that AI delivers is going to come from the proliferation of tools like these.