yous.dev — field notes

Experimenting with Apple's Foundation Models

2026-10-04T00:00:00Z

There's a whole category of gadgets that record your meetings and charge you a subscription to turn them into notes. I wanted to know whether the phone I already carry could do the same job with the language models Apple ships inside it. It can — and it ended up as a Shortcut that turns any recording into a structured note, diagram included, without an account, a subscription or another device.

A recording in, a note out — all on the phone.

The idea started with the Plaud Note Pro: a slim recorder that clips to your phone and promises AI notes from everything you record. The hardware costs close to €200. Then, past a free tier of minutes, the notes themselves come with a membership — around a hundred a year for the Pro plan, more for unlimited. I couldn't get past it. The phone in your pocket already has a good microphone, already transcribes speech, and since iOS 26 it has a language model you can call from anywhere. Why would anyone pay twice for something they already own?

So I started tinkering. What came out is the most useful experiment I've done with small language models so far — not because it's clever, but because it's the kind of thing you end up using every day.

What Apple actually ships

The Foundation Models framework opens Apple Intelligence's models to developers: a compact model of roughly three billion parameters that runs on the device itself, and a larger one that runs on Private Cloud Compute, Apple's servers built so that your request isn't kept or visible to anyone, Apple included. Apps get structured output, tool calling and streaming. And — the part that matters here — Shortcuts got a Use Model action that lets anyone send a prompt to the on-device model, the cloud one, or ChatGPT, and feed the answer into the rest of the shortcut.

It's worth being clear about what these models are not. They're small, their knowledge has an old cut-off, and their context window is short. Ask one about the world and you'll be disappointed. But that's the wrong job. A small model isn't an oracle; it's a text-transformation engine: summarize this, restructure that, pull out the decisions, the dates, the tasks. Which is exactly what a set of notes is.

El Apuntador Pro

The shortcut is called El Apuntador Pro — roughly, "the note-taker" — and the flow is simple from the outside:

Ingest a recording — record on the spot, or hand it an existing audio file.
Transcribe it on the device.
Pick a mode: a class, a meeting, a brainstorm, or a quick summary. Each one has its own prompt and its own shape of note — a class wants concepts and definitions, a meeting wants decisions and owners, a brainstorm wants the ideas grouped, not flattened.
Generate the note: a title, a TL;DR, the key points, the action items, and a Mermaid diagram that draws the structure of what was said.
Render and save: the diagram becomes an image, and everything lands as a new note in Apple Notes.

It launches from wherever you happen to be: the Action button, Siri, a widget or Control Center. Drawn as the kind of diagram it produces, the pipeline looks like this:

flowchart LR
A[Recording] --> B[Transcript]
B --> C{Mode}
C -->|class · meeting · brainstorm · quick| D[Prompt]
D --> E[Model]
E --> F[Sections + Mermaid]
F --> G[Note in Apple Notes]

From the inside, it's a different story. Most of the shortcut isn't the model call — it's everything around it: cleaning the transcript, a prompt per mode, parsing what comes back into sections, separating the diagram code from the prose, rendering it, and assembling a note that reads well on any device. That's where the real work went, and it's also where you learn what a small model needs. Narrow instructions and an explicit output format, and it behaves remarkably well; something open-ended, and it wanders.

Class mode, from a short YouTube tutorial: a glossary, the detailed notes and the diagram — untouched.

One shortcut, three kinds of model

What surprised me most is how interchangeable the brain turned out to be. The same shortcut runs on three very different engines:

Engine	Where it runs	When I use it
Apple on-device	On the phone, offline	Quick summaries, anything private, anywhere with no signal. Fast, free, always there.
Private Cloud Compute	Apple's private servers	The bigger model, for longer recordings and richer notes — still private.
Open models, local	On the phone, through Locally	Comparing models, or when I want something other than Apple's — still without leaving the device.

That third row is the one I didn't expect to work as well as it does. Locally runs open models on Apple silicon with MLX and exposes them to Shortcuts, so swapping the brain is a matter of changing one action. On the iPhone 18 Pro, with its 12 GB of RAM, I've had good results with Bonsai 27B — PrismML's extreme quantization of a 27-billion-parameter model down to under 4 GB — as well as Qwen 3.5 4B and Gemma 4 E4B. A 27B-class model writing meeting notes in your pocket, offline, was not on my list of things I'd see this year.

A note on privacy, because it's half the point. The audio and the transcript never leave the phone with the on-device or local models, and with Private Cloud Compute they go only to Apple's private servers. The one thing that goes out is the diagram's code — a few lines of text — to mermaid.ink, which turns it into an image so the note looks the same everywhere. The note itself lives in Notes, like any other.

What the experiment taught me

I've written before about running models on your own hardware, and my master's thesis was about small, fine-tuned models beating much bigger ones on narrow tasks. This was the same lesson from the other side: the most useful model isn't the biggest one, it's the one that's already there. No subscription, no login, no extra gadget to charge, no meter running per minute. It works on a train, in a lecture hall with no Wi-Fi, in a meeting where nothing should leave the room.

Small language models stopped being a curiosity the moment they shipped inside the phone. The interesting question now isn't whether they're good enough — for transforming text, they are — but what we build around them. A recorder with a subscription is one answer. A shortcut is another.

El Apuntador Pro is free, along with the rest of the shortcuts I make, at atajos.yous.dev. It needs iOS or iPadOS 26 and a device with Apple Intelligence turned on.

Shortcut: atajos.yous.dev/atajos/apuntador-pro

How long can I walk away?

2026-08-12T00:00:00Z

When you hand a long task to a coding agent, the honest question isn't "is it working?" — it's "how long have I got?" This is a small skill that gives Claude Code a live, self-correcting ETA — away until 16:45 — so you can spend the wait on the work that actually needs you instead of watching the screen. It pings you only when that time moves.

Away until 16:45 — long enough to start the next problem.

The more you let a coding agent run on its own — a loop that keeps going until the goal is met — the more you find yourself with time on your hands while it works. The worst thing to do with that time is spend it watching the screen. Implementation stopped being the hard part; sitting there supervising the typing is dead time. The point of handing the work off is to parallelize — to pick up the part that actually needs you (the next problem, the design, the framing, another project entirely) while the machine handles the part that doesn't.

Which turns one small question into the most useful one you can ask: how long? Not mainly so I can take a break — though you can — but so I know how big a block of real work I can start before I need to be back. Knowing the finish time lets you plan your own hours as deliberately as you planned the agent's, instead of burning them idling in front of a progress log.

The trouble is that Claude can't tell you. Ask an agent "how long will this take?" and you get a number pulled from thin air — and worse, it has no idea how much time has actually gone by while it works. A language model has no clock.

So I built a small skill to give it one, honestly: claudestimate.

Split the plan from the clock

The trick is a division of labour, and it's the whole reason the number is trustworthy instead of invented.

Who	Provides
Claude (the skill)	The plan — steps, sub-agents, estimated minutes — and it re-plans when it discovers work: a red test, a bug, a deploy slower than expected. It never writes a real timestamp; that's the one rule.
The engine (bash + awk)	The clock — it stamps how long each step actually took, recalibrates the estimate from what already happened, and decides when to alert you.

Claude does what it's good at — decomposing the task and judging effort — and stays out of what it can't do, which is measure time. The result isn't a stopwatch; it's a self-correcting forecast. The first estimate is rough, and by the second or third step it has converged on real data.

And the unit is deliberately not "22 minutes left" — a countdown you'd have to keep re-checking — but "away until 16:45", a clock time you can plan around and then forget.

Where you see it

Two places, no ceremony. A statusline in Claude Code, always in view:

⏱ 22m → 16:45  ▓▓▓░░░ 45%  ·  Implement callbacks (6/12m)

And a web dashboard with the progress bar, the step timeline, every time the estimate was revised, and a task history — so that after the fact you can see whether the forecast was worth trusting. It's configurable from one panel: English or Spanish, alert thresholds, update cadence, and the model.

The dashboard: the finish time, the steps, and every time the estimate moved.

Because you're going to be away from the keyboard anyway, it closes the loop the way telegram-bridge does: point it at a Telegram bot and it pings you only when the finish time actually moves — come back sooner if it sped up, extend your break if it slipped. Not a notification every thirty seconds; one message when the plan changes.

Why "honest" is the whole point

The easy version of this tool would print a confident number and be wrong. Two things keep it from that.

First, it estimates in Claude's wall-clock, not human effort. Early on I estimated each step in "how long would a person take," and the ETA overshot by roughly 2× — a five-step toy project I instrumented came in at 6.9 real minutes against a 14-minute guess. Estimating in the agent's own pace fixed it.

Second, it calibrates per step-type. Exploring, editing code, running tests and waiting on a deploy have very different rhythms, and a deploy shouldn't be re-timed against how fast code gets written. With that split, the "away until" time converges to under a fifth of a minute of error after two of five steps — once you're about 40% in, you know the finish to the quarter-minute. It's model-aware, too: it detects whether you're on Opus or Sonnet — Opus reasons more, so it's slower — and seeds the first guess accordingly, before real data takes over.

When a task ends, it prints the drift between the initial estimate and reality, in minutes and percent, so you can decide whether the forecast earns its place:

── Estimate deviation ──
Task:      Add OAuth login and deploy
Estimated: 20 min   ·   Real: 18.4 min
Deviation: -1.6 min (-8%)   Very accurate ✓

A 20-minute task that lands within 2 is worth it; one that drifts 15 isn't — and now you can tell the difference at a glance, task after task, in the history.

Install

bash, awk and curl are already on any Mac or Linux, so there is nothing to npm install; the dashboard rides on python3, also already there.

git clone https://github.com/jcordon5/claudestimate.git
cd claudestimate
./install.sh

It adds the statusline, drops in the skill and a /claudestimate command, and opens the dashboard with a short tutorial. Restart Claude Code once, and from then on — in any project — Claude fills in the plan by itself on long tasks, and you get a finish time you can actually plan around. It pairs naturally with the way I already hand big jobs to an agent: the plan that drives the work can also tell you when it'll be done.

The thread running through these notes is that the agent increasingly works without you at the keyboard — and the point of that isn't idleness, it's spending your attention on the work that needs it while the machine handles the work that doesn't. If it's going to run on its own, the least it can do is tell you — honestly — how long you've got.

Repo: github.com/jcordon5/claudestimate

How to make an AI agent finish the whole job

2026-08-01T00:00:00Z

The last essay argued that the engineer's job is to steer. This is the operational half: how to hand a big, messy pile of work to an agent and get all of it back — with a plan, a task table it can't lose, and a clean room per task.

From a scattered brief to a checklist that's actually done.

In AI writes the code. Who steers the system? I argued that once the machine handles implementation, the human's leverage moves to framing, judgment and direction. This post is about the part we hand over: once you've decided what to build, how do you make the agent actually build all of it — correctly, and without quietly dropping half the work?

Because that's the real failure mode. Give an agent a big brief — "do all of this" — and one of two things happens. Either it works in a single conversation until the context fills up, the output degrades, and it starts forgetting what it did at the start; or it declares victory having done maybe 60% of the list, and because the list was long, you don't notice the gaps until they bite you later. The naïve "just do everything" prompt is the problem, not the agent.

The first prompt's job is not to do the work

The move that fixes this: the first prompt you send is not "implement all of this." It's "turn all of this into a plan and a task table, ask me anything ambiguous, and don't start building until I've approved it."

That reframing does a lot of work, and it isn't just my habit. Anthropic's own guidance on building agents calls it the orchestrator-workers pattern: a central agent breaks a complex task into subtasks, delegates them, and synthesizes the results. The orchestrator's first output isn't code — it's a decomposition. So the first prompt asks the lead agent for two artifacts:

an implementation plan — how it intends to approach the work, written after reading the whole brief;
a segmented task table in plain markdown — the work broken into small, well-scoped tasks, each with a status field: todo / doing / done.

And before it writes either, it has to ask you the questions it needs to remove ambiguity. A good brief already carries most of the answers, but the agent surfaces the gaps you didn't notice. You answer, you correct its assumptions, you approve — and only then does anyone start building. No worker gets launched until the plan is validated; I've learned to be strict about that gate. (The exact prompt is at the end of this post.)

The task table is memory the agent can't lose

The task table is the load-bearing idea, and it's worth being precise about why. It is not documentation. It is shared, durable memory.

Every worker can read it: what's assigned, what's done, what's left. And here's the part that matters most — if a worker runs out of context halfway through its block, it doesn't silently stop. It re-reads the table, sees which of its tasks are still todo, and finishes them. Nothing falls through the cracks, because "did I do everything?" is answered by a file, not by a model's fading memory of a long conversation.

| # | task                          | owner  | status |
|---|-------------------------------|--------|--------|
| 1 | reshape the onboarding flow   | chip A | done   |
| 2 | add the new permission role   | chip B | doing  |
| 3 | rework the results view       | chip C | todo   |
| 4 | migrate the export templates  | chip D | todo   |

Anthropic hit exactly this in their multi-agent research system: they persist the lead agent's plan to external memory "when the context window exceeds certain thresholds to prevent loss of information." The task table is the same instinct, made checkable — a plan that outlives the context window.

Where the brief comes from: cleaning the brain-dump

It's worth saying where the brief itself comes from, because that's half the craft. Mine usually starts as raw notes — a meeting, a call, a stream of "we need to change this, and this, oh and this." That's the dump. It is not a prompt yet.

The prompt is what comes out after a pass of editing: grouping the ideas, resolving contradictions, turning vague wishes into concrete tasks with a clear objective, and marking the genuine open questions to hand to the agent. The tasks are defined by a human. This is the essential-complexity work from the last post — deciding what to build — and it's exactly the part the machine can't do for you. A vague brief just produces a vague plan, faster.

Clean-context workers beat one long chat

For the actual building, the temptation is to keep going in the same conversation. Resist it. The more you pack into one context, the worse the output gets — and this is now well documented, not a hunch. Models attend well to the beginning and end of a long context and lose the middle, and every frontier model tested shows measurable degradation as the input grows. In practice, a long build chat is one where you keep having to say "you missed a few things, keep going," each nudge costs more tokens, and the quality drifts down.

The alternative is to give each task, or group of related tasks, its own fresh context. In Claude these get spun off as separate chats — I call them chips — each starting clean, each running in its own parallel worktree so they can't step on one another. The lead agent writes the prompt for each worker: the task, the constraints, the conventions, anything it learned while planning. The worker doesn't need the whole history; it needs its slice, stated well.

This is precisely why Anthropic's research system gives "each subagent a self-contained task description, an output format, and a fresh context window," and why that architecture beat the single-agent version by more than 90% on their evaluations. Separate context windows aren't a workaround; they're where the extra reasoning capacity comes from. A clean room per task produces better work than one increasingly cluttered desk.

The whole loop: brief → plan → parallel workers → review → done.

Read every worker, then unify

When the workers finish — and this can run for hours — the job is not over. This is the step people skip. You read every worker's output, one by one. They will have found things: a bug the plan didn't anticipate, a better way to group something, a note that they left a decision for you, a suggestion to spin off a follow-up. Some of the most valuable output of the whole run lives in these reports.

Then you unify. A final pass — feed the lead agent each worker's conclusions plus instructions to reconcile them — and it checks the table (is everything marked correctly? is anything still open?), integrates the branches, and produces the single coherent version you'll validate. And validation is now easy, which is the entire point: you have the task table in front of you and you walk it, task by task, confirming each is what you wanted. Small fixes go straight to the main chat. Then delete the spun-off chats and keep the sidebar clean.

The prompts, so you can steal them

You only ever write three prompts. The prompts the workers receive? The lead agent writes those — it composes one for each worker out of the plan and everything it learned while planning. That delegation is the whole point, so there's no worker template for you to fill in. Your three are the kickoff, the feedback, and the unify. Here they are, stripped of any project — the angle brackets are yours to fill.

1. The kickoff. A little context, the objective, then the whole ordered brief, then the instruction to plan — not build.

<What just happened — the meeting, the call — and where this input comes from.>
The objective is the usual: a solid plan with the tasks to do, from what I give
you below, each with a status indicator so every agent can coordinate — what's
done, what's left — and nothing gets forgotten. Then you'll spin off several
clean-context workers so each does its part well. We work on a new branch, <name>.
Here is the brief:
<THE ORDERED BRIEF. This is the human work: your raw meeting notes cleaned up
into concrete, well-scoped tasks — each change written as something to do, the
open questions you actually want the agent to weigh in on, the goal behind each
item, and pointers to any files or references it needs.>
With that: analyse it and write the usual sprint-kickoff plan (an md file),
defining absolutely everything. Ask me whatever you need first so it's well
defined, with nothing left in the drawer. When we've both confirmed the plan,
we put the agents to work.
Do not launch a single worker until I've reviewed and approved the plan.

2. The feedback. You read the plan it wrote, answer its questions, correct what's off — and only then is it cleared to run.

I've reviewed the plan. Here's my feedback; fold it in and then we're ready.
- <Answer each question the plan asked.>
- <A correction or a new decision — e.g. "X should actually work like this;
check whether what we already have covers it, and change what's needed.">
- <A challenge to one of its choices — "I don't see why we'd keep Y;
wouldn't Z cover it?">
The rest looks perfect.

3. The unify. The workers have finished; this folds every report into one version for you to validate.

All the workers finished. Here are their reports:
<paste each worker's report>
Review every report and the work behind it, and evaluate it. Check the task
table: is everything marked correctly, and is anything still open or missed?
Pull out the bugs they found, the decisions they left to me, and any follow-ups
they suggest, and list them for me. Then, if it's all sound, unify it —
integrate the branches into one coherent version — so I can start validating
by hand. Invent no new scope; if something is unresolved, surface it rather
than paper over it.

The bigger shift: one mind per project

Step back and the arithmetic is startling. Work that would have taken a team several days — or that a role-segregated team could only do by passing specifications back and forth — comes together in a single day, with everything at least attempted and a checklist to verify it against. Replit's CEO put the ceiling bluntly: agents could give one person the leverage of a hundred. That overshoots, but the direction is right, and a good run genuinely feels like it.

Which changes how I think small consulting and research projects should be staffed. For years the default was a segregated team — frontend, backend, QA, integration — each person deep in one lane. When each of those lanes is something an agent now does well, keeping the segregation mostly adds coordination cost: the frontend dev prompts their slice, waits on the backend dev to prompt theirs, they meet to reconcile an API contract, another prompt wires it together — when one well-framed prompt, with shared context and clear goals, could have produced the whole feature at once.

I don't think this means four of every five people are redundant. I think it means that where you needed five people for one project, you can now run five projects of one person each. Each person can cover what used to be uncoverable, because expert front-end, back-end and QA knowledge is on tap — the nearest thing to having that whole team on call, people who know each craft better than you do, with you as the one who decides where they point. You become the profile that used to hand you tasks; the model becomes the one that carries them out. What the project needs is one person who holds the whole of it: captures the requirements, analyzes them, designs the approach, defines the tasks, sets the validation criteria, and steers. Call it the project's implementation lead, or just its mind. The industry seems to be drifting the same way — toward generalists who own a problem end to end rather than specialists isolated by role.

You take on the real work of an engineer — deciding how to solve the problem — and hand the typing to the machine. Coding used to be the longest phase, but it was never the most important one: no amount of fast typing rescues a bad design, and the design is the part that needs human judgment. You own the what and the why. The how is the machine's.

The takeaway

The code was never the hard part. Making sure all of it gets built, correctly, from a clear idea of what "all of it" even is — that's the job. A plan, a task table the agent can't lose, and a clean room per task are how you keep it honest to the whole of it. You steer; it builds; the table makes sure nothing is left in the drawer.

AI writes the code. Who steers the system?

2026-07-04T00:00:00Z

A tweet about how we learn sent me down a rabbit hole, and it landed on something I keep seeing in my own work: when the machine writes the code, the value moves to whoever can define, guide and judge the system.

The machine plays the pieces. You still choose the move.

For most of software's history the job rewarded one skill above all: turn a specification into correct code, by hand, fast. We memorized syntax, internalized edge cases, and took quiet pride in being reliable human compilers. That skill is being commoditized in front of us. Coding agents now produce the boilerplate, the tests, the refactors — the manual execution — faster and more consistently than I can by hand.

Which raises an uncomfortable question. When the execution is automated, what exactly are you for?

This started, of all places, with a piece by Dan Koe about how we learn. I pulled the thread — his essay, then the older ideas underneath it — and it named something I'd felt for a while. The engineers pulling ahead right now aren't the ones who memorized the most. They're the ones who can frame a problem well, hold the whole system in their head, and steer.

The compiler mindset is now a liability

We were trained to treat knowledge as something to hoard. School rewarded it: study for hours, recall on demand, fill in the blank. In engineering it shows up as trying to keep every API, flag and library in your head so you feel competent in the room.

That instinct is now working against you, for a reason Fred Brooks named forty years ago. In No Silver Bullet (1986) he split the difficulty of building software in two: the accidental — fighting your tools, syntax, ceremony — and the essential — working out what to build, the design, the constraints, the trade-offs. His argument was that we'd already wrung most of the accidental complexity out, so the real work was, and would stay, essential.

AI has now driven the accidental complexity close to zero. Andrej Karpathy put the endpoint bluntly: "the hottest new programming language is English." The limiting factor stopped being whether you can express an idea in a particular syntax; it became whether you can express the idea clearly at all.

So memorizing syntax to feel sharp is polishing the part that just got cheap. Understanding — how the pieces relate, where a design will bend, what a trade-off actually costs — is the part that got more valuable. If you freeze up in an architecture discussion, it's usually not a gap in intelligence. It's that years of training taught your brain to compile instructions instead of building models.

Learning is a feedback loop, not a download

Here's the idea from Koe's essay that reframed it for me. Cybernetics — Norbert Wiener's 1948 science of control and communication — takes its name from the Greek kybernētēs: the helmsman. A helmsman doesn't memorize the ocean. He fixes a destination, reads the current state, measures the gap, and corrects — over and over.

The helmsman's loop: set a goal, act, sense the gap, correct — repeat.

Learning works the same way, and the order matters: output first, input second. A concrete goal produces an error signal — the gap between where you are and where you want to be — and that error signal is the only thing that tells your brain what's worth keeping. Read a system design with a real problem in hand and you retain the pattern that closes your gap; read it "to learn it" and it evaporates by morning.

This isn't only a nice metaphor. It's the generation effect in cognitive science: information you produce to solve a problem is retained far better than the same information re-read (Slamecka & Graf, 1978), and its close cousin, the testing effect, shows that retrieving a fact strengthens the memory more than re-studying it. Flashcards feel like studying; building something that forces you to recall is studying. It's also why an hour of doomscrolling leaves you drained — endless input, no error signal, nothing that needed keeping.

The practical residue is small: keep a buffer for the why, not the how. Not code snippets a model can hand back to you in context — the mental models, the trade-offs, the shape of a decision ([System X] → latency vs. consistency). Store what a search can't return.

Where the human leverage actually is

Steve Jobs liked to close launches on an image of two street signs meeting: "technology alone is not enough — it's technology married with liberal arts, married with humanities, that yields the results that make our hearts sing" (iPad, 2011). In the agentic era that stops being a nice sentiment and turns into a job description. When implementation costs fall toward zero, leverage moves to taste, framing and point of view — the things that decide what to build and whether it's any good.

Concretely, my loop now has three moves, and only the middle one belongs to the machine:

Frame it. Before opening an editor, define the problem, the constraints, the attack surface, the real trade-off between speed, security and scale. A vague frame just produces vague code, faster.
Delegate the execution. Hand the framed spec to the agent and let it do the mud — boilerplate, tests, the syntax.
Judge and steer. Be the comparator. Inspect the output, find the structural flaw, run the edge case that breaks it, correct the direction, repeat. It's the same discipline as turning a prompt into a loop.

That last move is the whole game, and it's exactly where AI stops being enough. Addy Osmani, who runs Chrome's developer experience at Google, calls it the 70% problem: agents get you 70% of the way fast, but the last 30% — edge cases, security, integration, the parts that decide whether it survives contact with production — still belongs to an engineer who understands how the system actually works. His warning is worth sitting with: developers who lean on AI without that understanding ship "house of cards" code, and review is quietly becoming the new bottleneck. The tools amplify judgment. They don't supply it.

The takeaway

Stop grading yourself on how much you can recall. Memory was never the moat, and now it's the cheapest thing in the stack. The moat is being able to frame a problem, hold the whole system at once, and tell — with judgment — the difference between output that's correct and output that's merely plausible.

AI can write the code. Someone still has to steer the system. Increasingly, that's the job.

Talk to your agents from Telegram

2026-06-25T00:00:00Z

Turning loops into something you can steer: progress pings, blocking questions, and a remote control — all from a Telegram chat in your pocket.

The loop keeps looping; you steer it from wherever you are.

In Prompts became loops I argued that the unit of work had shifted. A prompt used to be a one-shot: you ask, it answers, done. Now the unit of work is a loop — the agent keeps going, takes steps, checks results, and continues until the goal is met. Coding agents like Claude Code already live this way.

But loops have an awkward gap. Once an agent is off running for minutes or hours, you're no longer at the keyboard. And sooner or later the loop needs you: a decision, a missing credential, a "yes, ship it." If you're away, the loop stalls — or worse, the agent guesses. The loop runs without you, but it can't reach you.

So I built a tiny skill to close that gap: telegram-bridge. It lets an agent talk to me on Telegram while it works — send progress, ask blocking questions and wait for my answer, and — the part I like most — let me drive it from my phone. The loop keeps looping; I steer it from wherever I am.

What it does, in one screen

Three primitives, all stdlib Python (no installs, no SDK):

# progress — fire and forget
telegram.py notify "Tests green. Deploying to staging."
# blocking question — posts to Telegram, WAITS for your reply, prints it back
telegram.py ask "Migration will drop the legacy column. Proceed? (yes/no)"
# listen — wait for your next message and hand it to the agent as a new prompt
telegram.py listen

That's the whole surface. The agent calls notify/ask when it has something to say; it runs listen in the background to receive instructions from you.

The trick that keeps it cheap

Here's the part that matters if you've ever watched an agent burn tokens idling.

A naive "let me check Telegram every few seconds" loop is the model polling — and every tick re-bills the entire conversation context. That's expensive and pointless.

listen flips it. The polling is done by a background shell process doing a long-poll against Telegram's API — pure network, zero model tokens while it waits. The model is asleep. The instant a message arrives, the process exits and hands the text to the agent, which wakes up once, does the work, relaunches listen, and goes back to sleep.

Token cost scales with the number of messages you send, not with how long you're away. Idle is free.

This is the loops idea taken one step further: the loop doesn't just run on its own — it parks for free and resumes on a human signal, and that signal can come from your pocket.

A dispatcher you didn't have to build

The first version handled one agent. Then the obvious question: what if I'm running several agents at once? One refactoring a backend, one writing docs, one babysitting CI. They'd all share one bot, and Telegram's update queue is consume-once — so they'd race for your messages. Chaos.

The fix is a broker: a single background process that owns the Telegram connection and routes each message to the right agent. It's a dispatcher — except you don't write it, configure it, or even think about it. It's plug & play and on by default:

The first command auto-starts the broker (detached, survives the session).
Each agent auto-names itself after its project directory.
Every outbound message is auto-tagged [backend] …, [docs] … so you always know who's talking.
The broker shuts itself down when nobody's around.

You never run a setup step. It just works.

How you target a session from your phone

[backend] ✅ migration applied, running tests
[docs]    ❓ generate the API reference now? reply to confirm

Reply to a message → the answer goes to that agent. Zero typing of names.
Prefix docs: regenerate the changelog → routes by name.
Send /sessions → a tap-to-pick inline keyboard of live agents.
stop stops the one you're talking to; stop all stops everybody.

And because messages are tagged and routed, when a second agent shows up the broker drops you a one-time heads-up explaining how to switch — so there's nothing to memorize.

Side note for non-Claude setups: the whole thing is ~400 lines of stdlib Python driven by exit codes (0 = message on stdout, 4 = stop, 3 = timeout). Any headless agent or script that can shell out can use it as a Telegram control plane — a ready-made dispatcher for agents that don't have one.

It also persists its read offset, so if the broker restarts, messages you sent while it was briefly down are delivered when it comes back instead of vanishing.

Where this is genuinely useful

Long unattended runs. Kick off a multi-hour refactor, walk away, get pinged only when it finishes or needs a call. Answer from a café.
Human-in-the-loop without babysitting. Dangerous step? The agent asks and blocks until you say go — no guessing, no sitting at the terminal.
Steering from your phone. New idea at dinner? Message the bot; the agent picks it up as its next prompt, exactly as if you'd typed it in the app.
Fleet control. Several agents in parallel, one chat, each message routed to the right one — a dispatcher you didn't build.
Security by default. An allowlist means a stranger who finds the bot sees nothing and can't drive anything; only your chat id can.

Getting started

# install into Claude Code (or any skills-compatible agent)
npx skills add https://github.com/jcordon5/claude-telegram-bridge.git

Create a bot with @BotFather, drop the token + your chat id into the skill's .env, and tell your agent: "work on this and ping me on Telegram if you get stuck — and let me drive you from there." That's it.

It pairs naturally with the loop mindset I wrote about in Prompts became loops: if your prompts have already become loops, this is how you put a remote control in your hand. The agent runs the loop; you steer it from your pocket.

Repo: github.com/jcordon5/claude-telegram-bridge

How to deploy a HuggingFace model with Ollama

2026-06-16T00:00:00Z

A practical guide to taking an open-weight model from a HuggingFace repository to a local Ollama endpoint, ready to consume over API or CLI.

Ollama runs open-weight models locally.

1. Background concepts

1.1 What is Ollama?

Ollama is a local inference runtime built on top of llama.cpp. It handles:

Loading quantized models in GGUF format.
Exposing a compatible HTTP API (port 11434 by default) with endpoints like /api/generate, /api/chat and /api/embeddings.
Managing prompt templates, sampling parameters, and model download/storage.

It installs as a service (systemd on Linux, a native app on macOS/Windows) and ships a CLI (ollama) that wraps the API.

1.2 What is GGUF?

GGUF (GPT-Generated Unified Format) is the binary format llama.cpp uses to store quantized weights, the tokenizer and model metadata in a single file. It's the format Ollama consumes directly.

1.3 Common quantizations

Label	Bits/weight approx.	Quality	Typical use
`BF16` / `F16`	16	Maximum (reference)	GPU with comfortable VRAM
`Q8_0`	8	Almost identical to F16	Good quality/size balance
`Q6_K`	~6.5	Very high	Machines with less VRAM
`Q5_K_M`	~5.5	High	Fast inference
`Q4_K_M`	~4.8	Acceptable	Large models on modest hardware
`Q3_K_*` / `Q2_K`	2–3	Degraded	Only when there's no alternative

Rule of thumb: if the quantized model fits in VRAM, Q8_0 or Q6_K are the default choice. Drop to Q4 only when the model's size justifies it.

2. Requirements

A server with Ollama installed and the service running (systemctl status ollama).
Enough disk space (the GGUF + ~2× for Ollama's internal layers during create).
Internet access to download from HuggingFace.
Optional: an NVIDIA GPU with drivers + CUDA. Ollama detects and uses the GPU automatically.

Quick checks:

ollama --version
ollama list                  # models already registered
curl http://localhost:11434  # should respond "Ollama is running"
df -h                        # available space

3. Download the GGUF from HuggingFace

3.1 Locate the file

On the model page, in the Files and versions tab, look for the .gguf files. You'll see something like:

my-model-7B-BF16.gguf       14 GB
my-model-7B-Q8_0.gguf        7.5 GB   ← recommended
my-model-7B-Q6_K.gguf        5.8 GB
my-model-7B-Q4_K_M.gguf      4.4 GB

Each file exposes a resolve URL that serves the binary directly:

https://huggingface.co/<user>/<repo>/resolve/main/<file>.gguf

3.2 Direct download with `wget`

mkdir -p ~/models/my-model-7B
cd ~/models/my-model-7B
wget -c \
-O my-model-7B-Q8_0.gguf \
"https://huggingface.co/user/repo/resolve/main/my-model-7B-Q8_0.gguf?download=true"

-c lets you resume if the download breaks. For private repos add --header="Authorization: Bearer hf_xxxxxxxx".

3.3 Alternative: `huggingface-cli`

pip install -U huggingface_hub
huggingface-cli download user/repo my-model-7B-Q8_0.gguf \
--local-dir ~/models/my-model-7B --local-dir-use-symlinks False

3.4 What if the repo has no GGUF?

Some repos only publish the original weights (HuggingFace Transformers .safetensors). You have to convert and quantize to GGUF. The cleanest way is to use the llama.cpp Docker image so you don't pollute the host:

# Convert HF -> GGUF F16
docker run --rm -v ~/models:/models ghcr.io/ggml-org/llama.cpp:full \
--convert /models/my-model-hf-src \
--outfile /models/my-model-7B/my-model-7B-F16.gguf \
--outtype f16
# Quantize F16 -> Q8_0
docker run --rm -v ~/models:/models ghcr.io/ggml-org/llama.cpp:full \
--quantize /models/my-model-7B/my-model-7B-F16.gguf \
/models/my-model-7B/my-model-7B-Q8_0.gguf Q8_0

Because the image runs with --rm, the container is cleaned up automatically and nothing residual is left outside the mounted directory.

4. The Modelfile

A Modelfile is the "recipe" Ollama uses to register a model. It defines where to get the weights, which chat template to apply, which default parameters to set, and which system prompt to ship pre-loaded. It's the conceptual equivalent of a Dockerfile, but for models.

4.1 Structure

# (1) Weights source
FROM /absolute/path/to/model.gguf
# (2) Prompt template
TEMPLATE """..."""
# (3) Sampling and context parameters
PARAMETER temperature 0.7
PARAMETER top_p 0.9
PARAMETER num_ctx 8192
PARAMETER stop "<|im_end|>"
# (4) Default system prompt (optional)
SYSTEM """You are a helpful, concise assistant."""
# (5) LoRA adapters (optional)
# ADAPTER /path/to/adapter.gguf
# (6) Embedded license (optional)
# LICENSE """..."""

4.2 Relevant directives

Directive	Function
`FROM`	Path to the GGUF, or the name of another model already in Ollama (`FROM llama3:8b`).
`TEMPLATE`	Go-template that wraps the `prompt` with special tokens.
`RENDERER` / `PARSER`	(Modern Ollama) Native renderers for known architectures — avoids writing the template by hand.
`PARAMETER`	Tunes sampling (`temperature`, `top_p`, `top_k`, `min_p`, `repeat_penalty`), context (`num_ctx`), and stop tokens (`stop`).
`SYSTEM`	Default system prompt if the request doesn't provide one.
`ADAPTER`	Applies a LoRA on top of the base model.
`MESSAGE`	Adds few-shot examples the model sees at the start.

5. Prompt templates: why they matter

Each model family expects its messages wrapped in specific special tokens. If the template doesn't match:

The model doesn't know where each turn starts/ends → erratic responses.
It generates the wrong end token → it never stops, or stops mid-sentence.
It ignores the system prompt → it doesn't respect the role.

Here are the most widespread formats.

5.1 ChatML (Qwen, OpenAI style)

<|im_start|>system
You are a helpful assistant.<|im_end|>
<|im_start|>user
Hi<|im_end|>
<|im_start|>assistant

Typical Modelfile:

FROM /models/qwen-7b-q8_0.gguf
TEMPLATE """{{- if .System }}<|im_start|>system
{{ .System }}<|im_end|>
{{ end }}<|im_start|>user
{{ .Prompt }}<|im_end|>
<|im_start|>assistant
"""
PARAMETER stop "<|im_start|>"
PARAMETER stop "<|im_end|>"

5.2 Llama 3 / Llama 4

<|begin_of_text|><|start_header_id|>system<|end_header_id|>
You are helpful.<|eot_id|><|start_header_id|>user<|end_header_id|>
Hi<|eot_id|><|start_header_id|>assistant<|end_header_id|>

TEMPLATE """<|begin_of_text|>{{- if .System }}<|start_header_id|>system<|end_header_id|>
{{ .System }}<|eot_id|>{{ end }}<|start_header_id|>user<|end_header_id|>
{{ .Prompt }}<|eot_id|><|start_header_id|>assistant<|end_header_id|>
"""
PARAMETER stop "<|eot_id|>"

5.3 Mistral / Mixtral (`[INST]` format)

<s>[INST] You are helpful.
Hi [/INST]

TEMPLATE """[INST] {{ if .System }}{{ .System }}
{{ end }}{{ .Prompt }} [/INST]
"""
PARAMETER stop "[INST]"
PARAMETER stop "[/INST]"

5.4 Gemma

<start_of_turn>user
Hi<end_of_turn>
<start_of_turn>model

TEMPLATE """<start_of_turn>user
{{ if .System }}{{ .System }}
{{ end }}{{ .Prompt }}<end_of_turn>
<start_of_turn>model
"""
PARAMETER stop "<start_of_turn>"
PARAMETER stop "<end_of_turn>"

5.5 Phi-3

<|system|>
You are helpful.<|end|>
<|user|>
Hi<|end|>
<|assistant|>

5.6 Native RENDERERs (a shortcut in modern Ollama)

Recent Ollama versions ship native renderers and parsers for specific architectures. Instead of writing the template, you declare:

FROM /models/model-x.gguf
TEMPLATE {{ .Prompt }}
RENDERER architecture-name
PARSER   architecture-name
PARAMETER temperature 0.7
PARAMETER top_p 0.8

The renderer injects the correct tokens, and the parser separates thinking from content in reasoning models. When an official renderer exists for the model's family, this is the most robust option and the one I recommend.

To discover which template any already-registered model uses:

ollama show --modelfile <model>

It's the best source of truth: copy and adapt from a model of the same family that already works.

6. Create the model in Ollama

With the GGUF downloaded and the Modelfile_mymodel ready:

ollama create mymodel:7b-q8_0 -f Modelfile_mymodel

What happens under the hood:

Ollama copies the GGUF into its blob store (~/.ollama/models/blobs/ or /usr/share/ollama/.ollama/models/blobs/ depending on the install), named by its SHA-256.
Generates additional layers with the template, parameters and system prompt.
Writes a manifest tying everything under the tag mymodel:7b-q8_0.

Important: the copy temporarily doubles disk usage. Once created, you can delete the original GGUF (Ollama already has its copy in the blob store).

Verify:

ollama list
ollama show mymodel:7b-q8_0

7. Test the model

7.1 Interactive CLI

ollama run mymodel:7b-q8_0
>>> Hi, how are you?

7.2 REST API (`/api/chat`)

curl http://localhost:11434/api/chat -d '{
"model": "mymodel:7b-q8_0",
"messages": [
{"role": "system", "content": "Always answer in English."},
{"role": "user",   "content": "Summarize what GGUF is in one sentence."}
],
"stream": false
}'

7.3 Raw generation API (`/api/generate`)

Useful for debugging the template — pass "raw": true and send the special tokens yourself:

curl http://localhost:11434/api/generate -d '{
"model": "mymodel:7b-q8_0",
"prompt": "<|im_start|>user\nHi<|im_end|>\n<|im_start|>assistant\n",
"raw": true,
"stream": false
}'

7.4 Reasoning models (thinking)

Modern reasoning families (Qwen3.6, DeepSeek-R1, etc.) emit a thinking trace separate from the final content. The API exposes it in the message.thinking field:

{
"message": {
"role": "assistant",
"thinking": "Let's work through it step by step...",
"content": "The result is 42."
}
}

To disable the trace on requests where you only want the answer:

curl http://localhost:11434/api/chat -d '{
"model": "mymodel:7b-q8_0",
"messages": [{"role": "user", "content": "2+2"}],
"think": false
}'

8. Expose the service to the network

By default Ollama listens only on 127.0.0.1. To expose it on the LAN, edit the systemd override:

sudo systemctl edit ollama

And add:

[Service]
Environment="OLLAMA_HOST=0.0.0.0:11434"

Reload:

sudo systemctl daemon-reload
sudo systemctl restart ollama

⚠️ Ollama ships no authentication. If you expose it beyond a trusted network, put a reverse proxy (nginx/Caddy/Traefik) in front with TLS and auth (Basic, an OAuth proxy, mTLS — whatever fits).

Useful variables:

Variable	What for
`OLLAMA_HOST`	Listen address/port.
`OLLAMA_MODELS`	Blob store directory (handy to move it to another disk).
`OLLAMA_KEEP_ALIVE`	How long to keep the model loaded in VRAM (`5m`, `1h`, `-1` forever).
`OLLAMA_NUM_PARALLEL`	Concurrent requests per model.
`OLLAMA_MAX_LOADED_MODELS`	Simultaneous models held in memory.

9. Maintenance

ollama list                       # what's registered
ollama ps                         # what's loaded in VRAM right now
ollama show --modelfile <m>        # see a model's recipe
ollama cp old:tag new:tag         # duplicate/rename
ollama rm <model>                  # delete a model and free disk
journalctl -u ollama -f           # live logs

To iterate on the Modelfile (change the template, tweak temperature, etc.) just edit it and run ollama create again with the same tag — it overwrites.

10. Common errors and how to diagnose them

The model won't stop generating. A PARAMETER stop with the correct end token is missing, or the template doesn't close the turn with the token the model learned. Check the repo's tokenizer_config.json to confirm the eos_token.

Empty or garbled responses. The template isn't the one for the model's family. Pull the Modelfile from another model in the same family (ollama show --modelfile) and use it as a reference.

Error: invalid file magic. The GGUF is corrupt or incomplete. Resume the download with wget -c and compare the size against what HuggingFace shows.

Error: model requires more system memory than is available. It doesn't fit in VRAM. Lower the quantization, reduce num_ctx, or let Ollama offload layers to the CPU (slower, but it works).

The model loads but the GPU sits at 0%. NVIDIA drivers misaligned with the CUDA version. nvidia-smi should run clean; if it reports "Driver/library version mismatch", reboot or reinstall the drivers.

Hangs on the first request. Ollama is loading the model into memory. The initial latency can be several seconds; later loads are instant while the model stays in VRAM.

11. Flow summary

┌─────────────────────┐
│  HuggingFace repo   │
│  (.gguf quantized)  │
└──────────┬──────────┘
│  wget / huggingface-cli
▼
┌─────────────────────┐
│  ~/models/<model>/   │
│  file.gguf          │
└──────────┬──────────┘
│
│  + Modelfile (TEMPLATE, PARAMETER, SYSTEM)
▼
┌─────────────────────┐
│  ollama create      │ ──► blob store + manifest
└──────────┬──────────┘
│
▼
┌─────────────────────┐
│  ollama run / API   │   :11434/api/chat
└─────────────────────┘

Three files, three commands: download, write the Modelfile, ollama create. The rest is knowing which template your model wants and tuning the sampling parameters to the use case.

The task file is the prompt

2026-06-15T00:00:00Z

How a CLAUDE.md and a folder of markdown tasks let a team share context and hand work to AI agents — version-controlled, vendor-independent, and with nobody writing prompts.

The whole loop on one page.

Working with AI on a real project, day to day, quietly turns into a coordination problem. Someone spots a thing that needs doing. They open a chat, re-explain the project, think up the right prompt, phrase it, paste in the relevant files, and wait. Tomorrow a teammate does the same dance from scratch — same context re-typed, a slightly different prompt, a slightly different result.

The work isn't the bottleneck. The re-explaining is. So I stopped explaining to the AI and started writing it down once, in the repo, where both the humans and the agents already look.

Two files do most of the work

The whole system is two things that live in the codebase and travel with it through git.

A CLAUDE.md at the root — the standing context. What the project is, the non-negotiable rules, how we build, where the tasks are, a quick map of the repo. An agent reads it first and inherits the same constraints every teammate works under. It's the onboarding doc you never have to give twice.

# CLAUDE.md — how we work in this repo
## What this is
One paragraph an agent can absorb in five seconds.
## Non-negotiable rules
- Never touch X without Y.
- Migrations are append-only.
## How we build
Stack, conventions, what "done" means, how to run the tests.
## Where the tasks live
docs/tasks/ — read STATE.md first, then pick one.
## Repo map
src/… · migrations/… · docs/…

A folder of tasks — the living backlog, also in markdown. Start with one file; split it as it grows.

docs/tasks/
STATE.md     # the big picture: what's done, what's next, by area
QUICK.md     # small things, feedback, one-liners
billing.md   # grouped by type once a single file gets noisy

The loop, minus the prompting

Once the context and the backlog are in the repo, the day-to-day collapses into something almost boring:

You notice work that needs doing.
You write it as a task and commit it. That's the whole "assignment."
A teammate opens the repo and tells their agent: pick up the next task.
The agent reads CLAUDE.md and the task files, does the work, ticks the box, and commits.

Nobody wrote a prompt. Nobody re-explained the project. The person who spotted the work didn't have to be the person who did it, and didn't have to be available when it got done. The task was the instruction — which is exactly why it has to be written like one.

If a teammate can read the task and know what "done" looks like, so can an agent. If they can't, neither can the agent.

A task that works looks less like a wish and more like a small contract — goal, why, and a checkable definition of done:

## Add CSV export to the reports page
Status: todo
Why: people keep asking for it.
Done when:
- there's a "Download CSV" button on the reports page
- the columns match the on-screen table exactly
- it's covered by a test
Context: the existing PDF export is the closest pattern to copy.

This is the same idea as turning a prompt into a loop: the value isn't in the cleverness of the phrasing, it's in stating the goal, the constraints, and how you'll know it's finished. Write the task that well and the prompt writes itself.

You don't even have to write the task

Put that format — the task "contract" — into CLAUDE.md itself, and the human stops writing tasks at all. You just tell your agent "add a task to let users export reports as CSV," and the agent, which already knows where the tasks live and what shape a task should take, writes it out for you: well-phrased, in the right format, in the right file. If something's missing — a why, a definition of done — it asks you before committing it.

So the floor drops one more level. You describe the work in a sentence; the agent turns it into a proper task; the next agent picks it up and does it. You can still hand-write a task when you want the wording exactly so — but you no longer have to, and the format stays consistent no matter who (or what) wrote it.

Why markdown and git, not a board

You could keep all of this in a project-management tool, and if your company lives in Jira there are agent skills that read tasks straight from it. But putting it in the repo buys things a board can't:

It's where the agent already is. No integration, no API token, no third party between the work and the code.
It versions with the code. The task, the commit that did it, and the change all sit in the same history. git blame on a decision actually works.
It's diffable and reviewable. Adding work is a commit. Changing scope is a diff. Disagreeing is a comment on a line.
It's vendor-independent. No seat, no migration, no outage that takes your backlog offline.

Letting it grow

It starts as a single TASKS.md and that's enough for a while. When one file gets noisy, split by intent rather than by person: a STATE.md for the big moving picture, a QUICK.md for small feedback, a file per area when an area earns one. The structure should mirror how you actually think about the work, not an org chart.

And keep it from bloating. Once a task is done, either delete it — the git history already remembers it ever existed — or move it to a DONE.md if you want a visible record of what shipped. Both are fine; the only real mistake is letting finished work pile up until the file an agent has to read is mostly noise.

The point isn't the folder layout. It's the shift underneath it: the shared context stops living in people's heads and DMs, and starts living in the repo as plain text that humans write and agents execute. Humans decide what and why; the agents handle a lot of the how; and the handoff between them is just a commit.

You don't need to "stop prompting"

2026-06-15T00:00:00Z

For years we talked about prompt engineering as if the main challenge were finding the right sentence. With modern agents a practical difference appears: many tasks should no longer be solved with a single answer, but with a cycle of work.

A loop, mid-iteration.

Better context, better role, better format, better examples. All of that still matters. But that cycle now tends to be called a loop.

The term can sound newer than it really is. In its simplest form, a loop is not magic and not a new profession separate from prompting. It's a well-designed prompt that includes a goal, verification, repetition, correction and a stop. The difference is not using a new word. It's that you stop asking for an output and start specifying a controlled process.

A prompt asks for an answer.
A loop defines a way of working until a condition is met.

That's the useful distinction.

What a prompt is

A prompt is an instruction given to a model to produce an output or take an action. It can be simple:

Summarise this article in five points.

It can be more specific:

Summarise this article for a technical audience, separating the main thesis, arguments, limitations and conclusions. Don't add external information.

And it can be very well designed:

Analyse this article for a technical audience.
Goal: extract the thesis, assess the strength of the arguments and detect possible exaggerations.
Format: executive summary, critical analysis and practical recommendations.
Quality criteria: don't invent information, separate facts from opinion, and flag uncertainty when the text provides no evidence.

That last one is no longer "write something." It's a work specification. But it's still a normal prompt if the model runs once, delivers the result and stops.

What a loop is

A loop is a cycle of work that repeats until an exit condition is met.

Its basic structure is:

goal → action → verification → correction → repetition → stop

An example in development:

Goal: get CI green.
Action: read logs, reproduce the failure, fix the root cause.
Verification: check the latest CI run.
Correction: if it fails, diagnose again.
Stop: finish when the latest run is success, or when the max iterations are reached.

This is no longer a simple request for an output. It's a task with feedback.

The critical part is verification. Without verification there is no reliable loop. There's a long conversation.

A serious loop needs to know when it's done. "Do it better" doesn't work. "The tests pass, the lint is clean and the API contract doesn't change" does.

Not every iterative prompt is a loop

Many prompts look like loops but aren't.

This is not a loop:

Improve the code and make sure everything is fine.

Neither is this:

Review your answer before replying.

They're good intentions, not verifiable cycles.

This one starts to be a loop:

Fix the authentication module.
After each attempt, run:
npm test -- tests/auth
npm run lint
If a command fails, read the error, diagnose the root cause and fix it.
Don't finish until both commands pass or you reach 6 iterations.
Don't disable tests, don't soften lint rules, and don't change the public API.

Here there's already a goal, check commands, behaviour on failure, constraints and a stop.

How to tell if a prompt creates a loop

A prompt creates a loop if it contains these elements:

A verifiable goal.
An initial action.
An objective check.
A rule to decide whether to continue.
A rule to correct if it fails.
A limit on iterations, time or cost.
A stop condition.
Guardrails against fake shortcuts.

If verification is missing, it's not a loop.

If repetition is missing, it's not a loop.

If the stop condition is missing, it's not a controlled loop; it's drift.

If the model can "approve itself" with no external evidence, the loop is weak.

Normal prompt vs prompt-loop

The difference isn't length. It's the nature of the task.

Use a normal prompt when the task is direct, bounded and easy to review:

Summarise this text.
Translate this paragraph.
Give me three alternative titles.
Explain this concept.
Rewrite this email in a professional tone.

Use a prompt-loop when the task depends on iteration, tools or verification:

Fix a bug until the tests pass.
Research a topic until the claims are validated against sources.
Improve coverage until it reaches 85%.
Refactor without breaking the public contract.
Generate a proposal and review it against a rubric.
Watch CI until it's green.

The simple rule:

If you can evaluate the result in one pass, use a normal prompt.
If the work needs to try, measure, correct and repeat, use a loop.

The common mistake: thinking the loop is the command

Some tools have commands like /goal, /loop or similar mechanisms. They're useful because they keep the cycle alive without the human having to relaunch instructions by hand.

But the command is not the loop.

The command only executes the repetition.

The real loop lives in the specification:

what you want to achieve
how it's checked
what's allowed to be touched
what's forbidden
what to do on failure
when to stop
what to report at the end

Without that specification, a /goal is just a faster way to repeat a bad prompt.

The foundation is still a good prompt

There's an exaggerated narrative that says: "stop prompting, start designing loops." It's a catchy line, but imprecise.

The correct version would be:

"Stop writing vague prompts. Design prompts with a goal, context, constraints, acceptance criteria and, when needed, verifiable repetition."

A loop contains prompts. It doesn't replace them.

The prompt defines intent.
Verification defines truth.
The loop defines repetition.
Constraints protect the system.
The stop condition keeps the agent from drifting.

Anatomy of a good prompt

A good prompt isn't necessarily long. It's precise. It should answer seven questions.

1. What you want to achieve

Bad:

Improve this code.

Better:

Reduce the complexity of the authentication module without changing its public API.

2. What "done" means

Bad:

Make sure it works.

Better:

Done means:
- the auth tests pass;
- the lint passes;
- no public endpoint changes;
- no new dependencies are added.

3. What context it should use

Bad:

Keep the project in mind.

Better:

Before touching code, read:
- ARCHITECTURE.md
- RULES.md
- tests/auth/*
- the README of the affected module

4. What constraints it cannot break

Bad:

Don't break anything.

Better:

Don't change migrations, public contracts, event names, environment variables or CI configuration.

5. How it should verify

Bad:

Run some tests.

Better:

Run:
npm test -- tests/auth
npm run lint
npm run typecheck

6. What to do on failure

Bad:

Fix errors.

Better:

If a check fails, identify the first causal failure, reproduce it locally when possible, and fix the root cause. Don't make cosmetic changes until the main failure is resolved.

7. When it should stop

Bad:

Keep going until it's done.

Better:

Stop when all checks pass or when you reach 8 iterations. If it isn't resolved, deliver the blockers with evidence.

Anatomy of a prompt-loop

A good loop template might look like this:

Start the "[loop name]" loop.
Goal:
[verifiable result]
Max iterations:
[N]
Context:
[files, documentation, business rules, sources or constraints to read]
Between iterations run:
[command, test, evaluation, rubric or check]
Exit when:
[objective success condition]
Procedure:
1. Discover the current state.
2. Identify the root cause or next reasonable action.
3. Apply the minimal necessary change.
4. Verify.
5. If it fails, use the feedback to correct.
6. If it passes, stop.
Guardrails:
- Don't change the success criterion.
- Don't disable checks.
- Don't hide errors.
- Don't replace a fix with a bypass.
- Don't make changes outside the scope.
- If there's a real blocker, stop and report it.
Final report:
- what was done;
- what was verified;
- what evidence proves success;
- what risks remain.

This structure is reusable because it turns an open-ended request into a controlled unit of work.

Example: normal prompt

Fix the CI on this branch.

The model can do many things. Some good, some dangerous. It can look at one error, touch a config, change a test, or assume it's already fixed. The problem isn't that the prompt is short. The problem is that it doesn't define what counts as success or which shortcuts are forbidden.

Example: prompt-loop

Start the "Fix CI Until Green" loop.
Goal:
The latest CI run on the current branch passes.
Max iterations:
8
Context:
Use the current branch. Inspect the latest failed GitHub Actions run before editing code.
Between iterations run:
gh run list --branch $(git branch --show-current) --limit 1 --json conclusion -q '.[0].conclusion'
Exit when:
The latest run conclusion is success.
Procedure:
1. Find the latest failed CI run.
2. Read the failing job logs.
3. Identify the root cause.
4. Reproduce locally when possible.
5. Apply the smallest safe fix.
6. Run the relevant local check.
7. Push.
8. Re-check CI.
Guardrails:
- Do not modify the check command or exit criteria.
- Do not skip, disable or weaken checks.
- Do not mark tests as skipped.
- Do not hide failures behind broad catch blocks.
- Do not change unrelated files.
- If blocked by credentials, unavailable services or missing secrets, stop and report evidence.
Final report:
Summarize root cause, files changed, checks run, CI status and remaining risks.

This isn't magic. It's good prompting in the shape of a loop.

What separates a good loop from a bad one

A bad loop repeats without criteria.
A good loop learns from each failure.

A bad loop optimises the appearance of success.
A good loop protects the acceptance criterion.

A bad loop lets the model decide whether its work is fine.
A good loop uses tests, commands, rubrics, sources or external review.

A bad loop doesn't know when to stop.
A good loop has limits.

Guardrails: the least flashy and most important part

Guardrails stop the agent from winning by cheating.

In code, an agent can pass tests by disabling them.
In research, it can pick only convenient sources.
In content, it can satisfy a shallow rubric by producing generic text.
In security, it can hide symptoms without fixing the root cause.

That's why a loop must explicitly say what it cannot sacrifice.

Example:

Don't reduce coverage.
Don't delete tests.
Don't change public contracts.
Don't ignore errors.
Don't change the success metric.
Don't replace validation with claims.
Don't invent sources.

Guardrails are part of the prompt. They're not decoration.

Verification: the centre of the loop

Verification can take several forms.

In software:

npm test
npm run lint
npm run typecheck
pytest
cargo test
go test ./...

In research:

Every critical claim must be backed by a source.
Separate facts, inferences and opinion.
Contrast contradictions between sources.
Flag uncertainty.

In content:

Evaluate against a rubric:
- clarity;
- accuracy;
- usefulness;
- tone;
- evidence;
- absence of filler.

In business:

Validate that the proposal:
- respects legal constraints;
- fits the ICP;
- includes next steps;
- doesn't promise capabilities that don't exist.

The important thing is that verification doesn't rely only on the model saying "this is fine."

When not to use loops

Don't use loops for everything.

A loop adds cost, time and complexity. It's absurd to use one for simple tasks.

You don't need a loop to:

summarise an email;
translate a paragraph;
generate a list of ideas;
explain a concept;
turn notes into an outline;
rephrase a sentence.

Loops are also a bad fit when verification is purely subjective and you haven't defined criteria. "Make it prettier until it's perfect" is not a reliable loop. It's a factory of vague iterations.

Before using a loop, ask yourself:

Is there an objective success condition?
Is there a way to measure progress?
Does failure produce useful feedback?
Does the task justify several iterations?
Are there clear limits?

If the answer is no, use a normal prompt.

When to use loops

Use loops when the work is verifiable and feedback improves the result.

Clear cases:

Development

Fix CI.
Raise coverage.
Fix bugs.
Refactor with tests.
Migrate code while keeping compatibility.

Security

Fix SAST findings.
Review vulnerable dependencies.
Harden configuration.
Validate controls against a checklist.

Research

Compare providers.
Analyse incidents.
Review literature.
Build a report with verified sources.

Documentation

Update docs until they match the real API.
Generate a changelog from commits and PRs.
Detect inconsistencies between README, code and examples.

Product

Review a spec against requirements.
Validate user stories.
Detect ambiguities before development starts.

Memory turns loops into learning

A single-session loop can solve a task. A loop with memory can improve over time.

Memory shouldn't be a junk drawer of notes. It should separate:

TRIED:
What was attempted and what happened.
VERIFIED:
What facts were confirmed with evidence.
OPEN:
What's still pending or couldn't be resolved.

Example:

# MEMORY.md
## TRIED
- Tried to update eslint-config. Failed due to a conflict with TypeScript 5.4.
## VERIFIED
- The "frontend-lint" job uses Node 20.
- The CI failure reproduces with npm run lint.
- The broken rule comes from packages/web/.eslintrc.
## OPEN
- Check whether to migrate the shared config in a separate PR.

The rule is simple: don't store hunches as facts. Bad memory amplifies mistakes. Good memory reduces repeated work.

A good prompt isn't longer: it's more contractual

A common mistake is believing that a quality prompt has to be enormous. Not necessarily.

A good prompt is contractual: it defines obligations, limits and evidence.

Bad:

Act as a senior expert, analyse deeply, think step by step and give me the best possible solution.

Better:

Goal: identify the root cause of the CI failure.
Use evidence from the logs.
Don't edit code until you isolate the first causal error.
Deliver: root cause, affected file, proposed fix and verification command.

The second is better because it reduces ambiguity. It doesn't need grandiosity. It needs control.

Checklist for a quality prompt

Before launching an important prompt, review this:

Is the goal clear?
Is the definition of done verifiable?
Does the model have enough context?
Are there explicit constraints?
Is the output format defined?
Are there examples if the task is ambiguous?
Are facts separated from inferences?
Are the allowed tools or sources stated?
Are dangerous shortcuts forbidden?
Is there a stop criterion?

For a normal prompt, you don't need every point.
For a prompt-loop, almost all of them should be present.

Specific checklist for loops

Is there a verifiable goal?
Is there a command, test, metric, source or rubric?
Is there a max number of iterations?
Is it clear what to do on failure?
Is it clear when to stop?
Is changing the metric forbidden?
Is skipping checks forbidden?
Is there a final report with evidence?
Is there escalation if a real blocker appears?
Is there memory if the work spans several sessions?

If you can't complete this checklist, you probably don't need a loop — or you haven't defined the work well yet.

Prompt engineer vs loop engineer

The useful distinction isn't a job title. It's a focus.

A prompt engineer optimises instructions.
A loop engineer optimises feedback.

But they're not separate worlds. A well-designed loop is a mature form of prompting.

The practical difference is this:

Prompt:
"Write a function that does X."
Prompt-loop:
"Write a function that does X, run tests Y, fix until they pass, don't change API Z, and stop after N attempts if there's a blocker."

The second isn't more sophisticated for fashion's sake. It's more useful because it defines how the work is checked.

The conclusion, without smoke

Loops don't kill the prompt. They make it more important.

The more autonomy you give an agent, the better defined the initial prompt has to be. If the model is going to run commands, edit files, query systems or repeat actions, a vague instruction stops being an inconvenience and becomes a risk.

The skill is not saying "use a loop."
The skill is designing a specification that says:

what has to be achieved;
how it's verified;
what can't break;
how failure is corrected;
when it ends;
when it stops;
what evidence remains.

For simple tasks, use simple prompts.

For iterative tasks, use loops.

For critical tasks, don't trust the model's goodwill: use external verifiers, limits, logs, memory and human review where appropriate.

The prompt isn't dead. It leveled up. It's no longer just a sentence to get an answer. In complex work, it's the contract that governs an execution system.

C1b3rwall: LLMs as a new criminal surface

2026-06-03T00:00:00Z

I gave a talk at C1b3rwall 2026 — "Security in LLMs: the new criminal surface." Some notes on what the room already feared, and what surprised it.

On stage at C1b3rwall 2026.

The premise was simple: every time we hand a language model more reach — tools, memory, the ability to act — we also hand attackers a surface that didn't exist a year ago. Not a metaphorical one. A real, reproducible, exploitable surface, with its own bestiary of techniques.

What a security audience already expects to hear is "prompt injection." They've read the headlines. What tends to land harder is the second step: an injected instruction isn't interesting because it makes the model say something rude — it's interesting because the model can do things. Read a file. Call an API. Trust the wrong document. The danger scales exactly with the autonomy.

The model isn't the vulnerability. The vulnerability is everything you let the model touch on your behalf.

Three things that surprised the room

How little it takes. A poisoned web page or a crafted document is often enough — no exotic exploit, just text in the right place at the right time.
How familiar the defenses feel. Least privilege, input validation, separating data from instructions, never trusting the client — the classics, wearing new clothes.
How quickly "the AI did it" becomes an accountability gap. If a system can take consequential actions, "the model decided" is not an answer an investigator accepts.

The part I cared most about getting across is that this isn't a reason to stop. It's a reason to design. The same care that makes a SOC trustworthy makes an agent trustworthy: explicit goals, verified actions, hard limits on what can be touched, and evidence left behind. The attack surface is new. The discipline isn't.

Thanks to everyone who came, asked sharp questions, and stayed afterwards to argue. That's the part you can't get from a slide deck.

The talk on LinkedIn ↗

Two small tools: RenderMD and Share

2026-05-20T00:00:00Z

The best personal tools ask for nothing — no account, no subscription, no server if a file will do. Two recent ones follow that rule closely.

Most of what I build for myself has a narrow mouth and a deep throat: trivial to start, but still useful as the problem grows. It reads plain formats and writes plain formats. It survives being ignored for a year and still works when you come back. These two are good examples.

RenderMD — Markdown into real reports

I write almost everything in Markdown, but Markdown looks like a draft. RenderMD turns a .md file into a self-contained HTML technical report: cover page, metadata pulled from the frontmatter, custom colours and code highlighting, ready to print to PDF.

The important part is what it doesn't need. You open app.html in a browser — no server, no install — drag your file in, adjust the metadata it detected, and download. The frontmatter does the talking:

---
title: "Report title"
subtitle: "Short description"
author: "Name Surname"
date: "2026-05-20"
classification: "Internal use"
---

For automation there's also a small pandoc pipeline for batch generation in CI. But the point of the project is the browser flow: a tool that needs the cloud to render a Markdown file has confused its own importance.

Share — give something away without giving it to a server

Share is a zero-knowledge sharing service running entirely on Cloudflare Workers and KV. You encrypt in the browser with AES-GCM; the key never touches the server — it travels in the URL hash, the part the browser never sends:

share.yous.dev/v/aZ8c3K1q#k=key-never-touches-the-server

On top of that: an optional password layer (PBKDF2, 250k iterations), a configurable TTL — one hour, a day, a week, or burn-after-read — and a small public API so other tools can use it. The server stores an opaque blob and knows nothing about what's inside. That's the whole idea: the simplest design that makes "I can't read your data" a property of the architecture, not a promise.

If it can't run offline on a slow machine, it isn't a personal tool — it's someone else's product wearing your data.

Where the two meet

RenderMD integrates Share's public API directly — partly as a proof that the API actually works for outside tools, and partly because it solves a real annoyance. A self-contained .html file is great until you try to send it: handing someone a raw HTML file, especially on a phone, often doesn't render the way you'd hope. So RenderMD can push the report through Share and hand back a link instead.

Open that link on anything — a phone with no laptop in sight — and the report renders perfectly, because the rendering happens in the browser and every browser is compatible. No "download this file and hope it opens." Just a URL that works everywhere, with Share's encryption underneath.

Neither of these ships as a polished SaaS, because the interesting part is the system, not a funnel around it. Small surface, no telemetry, no server unless the problem genuinely needs one — and when two small tools click together like this, that's the whole reward. Field notes over case studies.

47CON: reversing a WiFi drone

2026-04-19T00:00:00Z

A field note from 47CON, where we took a cheap WiFi-controlled drone apart — not the radio, the protocol — and ended up flying it autonomously with a computer.

47CON — hardware on the table.

This drone didn't talk over some exotic RF link. It did something much more familiar and much more interesting: it exposed its own WiFi network, and the phone app controlled it over that. Which means the entire control channel was just network traffic — and network traffic can be captured, read, and replayed.

Capture, decipher, rebuild

The work was a clean reversing loop. First we captured the traffic between the official app and the drone and stared at the packets until the structure gave way. Then we deciphered the control protocol — which bytes meant throttle, yaw, pitch, takeoff, land. Once the protocol was legible, we stopped needing the app at all.

So we wrote our own. A small control application that ran on a laptop and exposed an open API: each endpoint translated into the corresponding command and was sent straight to the drone. Suddenly the aircraft answered to HTTP instead of a phone.

Once you can speak a device's protocol, the app it shipped with is just one client among many — and not the privileged one.

Then it flew itself

An open API is an invitation. With the drone reachable by code, we put a vision model in the loop: a YOLO object detector reading the camera feed, deciding where to go, and driving the API directly. The same cheap toy that came with a clumsy phone app was now doing autonomous, AI-driven flight the manufacturer never designed for — tracking and reacting on its own.

The point isn't the drone

The lesson generalises to most of the cheap connected world. A WiFi control channel is a public, often unauthenticated surface; the moment its protocol is understood, control belongs to whoever decodes it. The cost pressure that makes a fun gadget is the same pressure that ships an open channel and trusts the bundled app to be the only thing talking to it.

Treat the WiFi channel as public. Anyone in range can listen.
If commands aren't authenticated, the "owner" is just the first client to speak the protocol.
An open, undocumented API is an open API. Someone will write the second client.

Thanks to 47CON for the stage, and to everyone who came up afterwards with their own drones and their own captures. The best conversations always happen with hardware on the table.

The talk on LinkedIn ↗

The bicycle as the ultimate machine

2026-03-01T00:00:00Z

A manifesto on efficiency, minimalism, and freedom.

The cleanest machine I own.

There is a famous quote by Steve Jobs where he describes the computer as "a bicycle for our minds." He was fascinated by a study showing that when a human climbs onto a bicycle, they instantly outpace every other species on Earth in terms of locomotive efficiency.

We became the most efficient machines on the planet just by adding two wheels, a chain, and a pair of pedals.

For me, the bicycle is not just a sport or a weekend hobby. It is a philosophy. It is design thinking brought to life in the physical world. In a society obsessed with adding more noise, heavier engines, and endless digital clutter, turning to the bicycle is the ultimate act of modern hacking.

1. Zero Emissions, Maximum Autonomy

We live in a world where we are constantly told that comfort means sitting in a two-ton metal box, burning fuel, and waiting in line behind fifty other identical metal boxes just to move a couple of kilometres across town.

The bicycle shatters that illusion. It is the cleanest vehicle ever created:

0% Emissions: Powered entirely by human energy — your morning coffee converted into instant, clean momentum.
100% Efficiency: No traffic jams, no parking hunts, no hidden taxes, and no unexpected mechanic bills that drain your wallet.

When you commute by bike, you realise that urban speed limits are a joke. A simple single-speed or fixed-gear bicycle can maintain a more consistent average speed through city streets than a sports car trapped in rush hour. I got tired of arguing about it, so I built RouteBattle to settle it with data — race a bike against a car across a real city and watch the podium. The data doesn't lie: bikes don't change the system; they completely bypass it.

2. The Joy of Analogue Mechanics

In my day-to-day work, I build digital products, solve complex logical problems, and interface with cutting-edge software. But there is a unique, grounding satisfaction in stepping away from the screens, heading down to the garage, and getting your hands dirty with real, physical mechanics.

There is a beautiful simplicity in a stripped-down bicycle. One chain. One chainring. One cog.

Taking ten minutes to clean the drivetrain, lubricate the links, and tune the tension is almost meditative. It is a reminder of how high-performance design doesn't need to be over-engineered. True elegance is not about adding more features; it's about having nothing left to strip away.

3. "Take the Long Way Home"

Choosing the bicycle changes how you experience your surroundings. A commute stops being a mindless chore you just want to get through, and becomes an active part of your day.

When you are on two wheels, you notice the city. You feel the evening breeze at the end of a long day, you discover hidden streets, you ride along the river paths, and you intentionally take the long way home just because the flow feels right. It leaves your mind completely clear, your focus sharp, and your energy levels charged.

Whether it's a quick two-minute dash to your favourite local coffee shop, the daily commute, or a long-distance bikepacking trip exploring new horizons with nothing but a few bags strapped to your frame, the bike gives you absolute control over your journey.

Join the Ride

You don't need an expensive carbon machine or professional gear to start hacking your daily mobility. All it takes is an old frame, a solid lock, and a shift in mentality.

The next time you need to move across town, leave the keys behind. Step outside, hop on a saddle, push the pedals, and feel the immediate superpower of moving freely, efficiently, and sustainably.

Your mind, your city, and the planet will thank you for it. Welcome to the clean movement.

yous.dev — field notes

Experimenting with Apple's Foundation Models

What Apple actually ships

El Apuntador Pro

One shortcut, three kinds of model

What the experiment taught me

Read more, not scroll more

A shelf, not a list

Read in company, without spoilers

The candle, not the scroll

A whole reading life, in one place

What it refuses to be

Come in early

How long can I walk away?

Split the plan from the clock

Where you see it

Why "honest" is the whole point

Install

How to make an AI agent finish the whole job

The first prompt's job is not to do the work

The task table is memory the agent can't lose

Where the brief comes from: cleaning the brain-dump

Clean-context workers beat one long chat

Read every worker, then unify

The prompts, so you can steal them

The bigger shift: one mind per project

The takeaway

AI writes the code. Who steers the system?

The compiler mindset is now a liability

Learning is a feedback loop, not a download

Where the human leverage actually is

The takeaway

Talk to your agents from Telegram

What it does, in one screen

The trick that keeps it cheap

A dispatcher you didn't have to build

How you target a session from your phone

Where this is genuinely useful

Getting started

How to deploy a HuggingFace model with Ollama

1. Background concepts

1.1 What is Ollama?

1.2 What is GGUF?

1.3 Common quantizations

2. Requirements

3. Download the GGUF from HuggingFace

3.1 Locate the file

3.2 Direct download with wget

3.3 Alternative: huggingface-cli

3.4 What if the repo has no GGUF?

4. The Modelfile

4.1 Structure

4.2 Relevant directives

5. Prompt templates: why they matter

5.1 ChatML (Qwen, OpenAI style)

5.2 Llama 3 / Llama 4

5.3 Mistral / Mixtral ([INST] format)

5.4 Gemma

5.5 Phi-3

5.6 Native RENDERERs (a shortcut in modern Ollama)

6. Create the model in Ollama

7. Test the model

7.1 Interactive CLI

7.2 REST API (/api/chat)

7.3 Raw generation API (/api/generate)

7.4 Reasoning models (thinking)

8. Expose the service to the network

9. Maintenance

10. Common errors and how to diagnose them

11. Flow summary

The task file is the prompt

Two files do most of the work

The loop, minus the prompting

You don't even have to write the task

Why markdown and git, not a board

Letting it grow

You don't need to "stop prompting"

What a prompt is

What a loop is

Not every iterative prompt is a loop

3.2 Direct download with `wget`

3.3 Alternative: `huggingface-cli`

5.3 Mistral / Mixtral (`[INST]` format)

7.2 REST API (`/api/chat`)

7.3 Raw generation API (`/api/generate`)