DEV Community: Manuel Alejandro Hermoso

Scary Truc: a stranger calls you from inside a maze, and your voice is all they have

Manuel Alejandro Hermoso — Sat, 31 Oct 2026 17:26:31 +0000

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 4: Ghost in the Machine

What I Built

It's past midnight and your phone is ringing. Unknown number.

You answer, and someone is whispering on the line. They woke up somewhere they shouldn't be. They don't know how they got there. The people who came with them are gone, and you're the only one who picked up.

You can't see where they are. You have their voice, a battery that is running out, and a notebook where you draw the maze from what they tell you. The pencil fades. Something else is down there with them. It has no eyes, and it finds them by how they sound. So you talk them through it, left, right, hide, don't breathe, and you keep them calm, because fear is loud.

Scary Truc is that phone call. Gemma plays the person on the line, and it also plays the thing hunting them, which sometimes gets on the phone and speaks to you:

They still bleed for the mistake you called a plan.

Nobody wrote that line. Gemma did, during a call.

There are no buttons to choose from. You talk to them the way you'd talk to a terrified stranger, and Gemma reads how you said it as well as where you said to go. A kind word steadies them. Shouting makes them stumble, refuse, or run down a corridor you never chose. Ask them for a joke and they'll wonder who you really are. Go quiet and they'll beg you to say something, and then they'll choose for themselves, badly.

And they don't know you. Yours is the only number in their phone, and they never saved it. Every so often they stop and ask who you are, or whether you're the one who put them there, and they won't take another step until you answer.

There are six calls, each a hand-made maze after a horror film: The Cave after The Descent, The Woods after The Blair Witch Project, The Cube after Cube, The Tape after Ring, The Hedge after The Shining, and The Ship after Alien. At midnight a bell tolls, the walls move, and what's in your notebook becomes a memory. When the line goes dead, the phone tells you how many steps they were from the way out.

One of my calls in The Cave, in Spanish, ended like this:

I went through the door. I can see the sky. I'm out. Thank you. Who are you?

Demo

Answer the phone. It runs in the browser, and it's best on a phone, with headphones on and the lights off. Tap Talk and speak out loud. It works in English and Spanish.

Play it with Gemma here plays with Gemma, no setup needed (the word is pumpkin). It works until the credit I put on it runs out. Without it, the game still runs, but the caller only knows a few words. To get the real thing, add your own OpenRouter key or your own Ollama under Model on the lock screen.

That's one real call with Gemma as the caller and the Hollow, cut down to about a minute. Everything they say is what Gemma said. The player's lines in this recording are scripted, so that the filming could be repeated.

Code

deeptelar / scary-truc

A horror game played by phone: talk a terrified stranger out of a maze while something hunts by sound. Gemma 4 plays the caller, in your browser. Kotlin Multiplatform, built with Telar.

Scary Truc

Don't trust the voice on the phone.

— scratched into a wall of The Tape

It's past midnight and your phone is ringing. Unknown number.

You answer, and someone is whispering on the line, too fast, too close. They woke up somewhere they shouldn't be. They don't know how they got there. The others who came with them are gone and yours is the only number in that phone.

You can't see where they are. You have their voice, a battery that is running out, and a notebook where you draw the maze from what they tell you. The pencil fades.

Something else is down there with them. It has no eyes. It finds you by how you sound. So you talk them through it, left, right, hide, don't breathe, and you keep them calm, because fear is loud.

Answer the phone. Headphones on, lights off…

View on GitHub

About 6,500 lines of Kotlin, plus 1,800 lines of tests. It's one Compose Multiplatform codebase that builds the web page (Wasm) and a desktop game. The first commit is from October 27.

How I Built It

My first version wasn't scary. It was a top-down maze where you threw treats and tricks to guide four little agents past certain death. It worked, and when I played it, it was boring, predictable and not scary at all. I added real-time pressure, a hunter, a siren at midnight, radio static. It got better and it still wasn't frightening, because I was looking at it from above, safe.

So I threw it away. If the fear comes from not seeing, take the screen away. On day two the game became a phone call with one scared person on the line. The first time I played that version on my phone, just chatting with them was already scary, which all the sirens had never managed.

(Truc started as trick, from trick-or-treat. In Catalan, fer un truc also means to give someone a call. I kept the name.)

The model: Gemma 4, playing three parts. The hosted page uses Gemma 4 31B on OpenRouter, a few seconds a turn. The desktop build uses gemma4:12b in a local Ollama. Gemma does three jobs in a call:

The caller's ears: what you told them to do, and how it made them feel.
The caller's voice: saying what happened as a frightened person would.
The Hollow: the whispers on the line, made from what the caller fears most.

The workflow: a graph that waits for you. A call is a Telar graph. Telar is an open-source Kotlin library for AI workflows that I maintain. It existed before this challenge, and Scary Truc uses it from Maven Central like any other library.

StateGraph<Call> {
    val listen = node(LISTEN, work = { call -> ears.listen(call) }) { call, heard -> call.copy(heard = heard) }
    val walk = node(WALK) { call -> call.act(mazeOf, haunt) }
    val whisper = node(WHISPER, work = { call -> if (call.whispers(mazeOf(call))) whisperer.whisper(call) else null }) { call, said ->
        if (said == null) call else call.whisper(said)
    }
    val speak = node(SPEAK, work = { call -> voice.speak(call) }) { call, said -> call.spoke(said) }
    START then speak
    conditionalEdge(speak, targets = setOf(listen, NodeRef.END)) { call -> if (call.over) NodeRef.END else listen }
    listen then walk then whisper then speak
}.compile()

The run pauses before listen on every turn, until you say something. The important node is the one with no model in it: walk is plain code. The caller obeys, refuses or bolts. The maze answers. The Hollow hunts. Only then does Gemma get a list of facts and say them out loud.

That's the rule the whole game stands on: Gemma never decides what is true. It decides how it sounds. So the caller can't invent a door that isn't there, and you can't talk them through a wall.

The ears answer with a typed value, not text to parse. This class is the whole contract between what you say and the game:

@Serializable
data class Understood(
    @Description("What the stranger tells you to do now: ahead, left, right, back, stay, hide, mark, take, use, or none")
    val order: String,
    @Description("How the stranger's words make you feel, from -2 (harsh, rushed, scary) to 2 (calm, kind, reassuring)")
    val calm: Int,
    @Description("When the stranger says to do something after that, the next thing ...")
    val then: String = "none",
    @Description("Whether the stranger's words have nothing to do with getting you out alive: a joke, trivia ...")
    val offTopic: Boolean = false,
    // ...
)

val understood = model.ask<Understood>(prompt(call), system = system(call))

"Go right, you're doing great" gives right, calm 2. A bare "left" needs no model at all, so it's instant when something is behind them.

The ghost in the machine. The game keeps a log of each call on the phone, with what I said, what the caller understood, and how the call stood after each turn. I played, exported the log, and read what really happened. These six moments changed the game.

The caller lied to me. In The Woods I said "go right and pick up a stone if you can". The caller answered "I have the stone." There was no stone. Later, with the Hollow two steps away, I told them to throw it. "I don't have any stones. It found me!" Dead. My graph had only run the "go right" part, so no fact said that nothing was picked up, and Gemma filled the silence with what I wanted to hear. A rule in the prompt forbade exactly that, and it wasn't enough. Now both parts of an order run, and what fails becomes a fact. When a model makes something up, first look for the fact you didn't give it.
Buttons killed the conversation. I had added tap options for one-handed play. Reading my own logs, my first four calls were nearly all taps and all ended badly, with the caller reciting menus at me. The call where I got someone out was mostly typed. It was also my third try at that maze, so the buttons weren't the only reason, but the point of the game is that it feels like a conversation. I removed them, and taught the caller to answer me first and report second.
"Don't worry" was a cheat code. My winning call took panic to zero by saying no te preocupes on every turn. Nobody in that situation is at zero. Now the same comfort wears thin while all is quiet, and panic has a floor. My first attempt at this made The Ship impossible: my test guide, which plays perfectly, went from 12 of 12 to 0 of 12. It's 9 of 12 now, and 12 of 12 on the others.
Gemma was gone for a day and I didn't notice. A regular expression that works on the JVM throws in the browser. Gemma failed silently, the game fell back to its script, and every test was green. Now model calls and faults go in the log, and I check model behavior in a real headless Chrome with a real key.
The best input was my own voice. My last call was entirely by microphone, and it worked so well that I made the mic the main key: it's a phone call, so you should speak. It also gives the game its strangest moments. The speech recognition once heard me say a name I never said, and the caller, in the dark, with the Hollow awake, answered: "I'm not Silvia. My name is Sam."
A tester found what I couldn't see. A real player liked it and told me three things. It got too easy, because there was plenty of time to think on every turn. The caller shouldn't explain that a breathing door is bad: say there's a door that breathes, and if someone dies going in, the player will understand. And trust, the main mechanic, was never tested. The log agreed: trust only ever rose, 60 to 87 in one call, and a 33-second pause cost nothing. So thinking now costs battery and nerve, and past a point the Hollow keeps walking. The notes stopped teaching the traps and started talking about the voice on the phone. And the caller now stops and asks who you are. Gemma judges your answer: "I don't know, I'm scared too" convinces them, "just go left" is no answer, and if you keep dodging, they hang up on you. It also remembers what you said. In the call in the recording above, the player said "I'm staying with you", and the Hollow answered:

Staying with you... and the weight of all they lost.

Why Does Open Innovation Matter?

Horror needs a character who stays in character. I can control that here because every part of it is mine to change: the prompts, the examples Gemma learns its voice from, the model itself.

You can swap the model. The caller speaks the OpenAI API, so any server works: Gemma 4 31B on OpenRouter, gemma4:12b on my own 8 GB GPU, or a friend's proxy. Changing it is a field on the lock screen. I tuned the prompts by measuring what Gemma does, and I can keep doing that because the weights aren't going to change under me without warning.

It doesn't depend on any one service. If a provider disappears, the game keeps working on the next one, or on your own computer. With no model at all it still plays, with a simpler caller. The maze, the Hollow and the rules are code, so the game itself survives its model.

It can run offline. The desktop build talks to a local Ollama, so a whole call can stay on your machine. I checked instead of assuming: I traced every connection during full calls in English and Spanish on gemma4:12b. With Ollama's cloud features switched off (OLLAMA_NO_CLOUD=1), neither the game nor Ollama connected to anything outside my PC. On my 8 GB GPU, the first line takes up to a minute while the model loads, then it's 4 to 8 seconds a turn.

What you say stays yours, with one honest exception. The API key stays in your browser and goes from there straight to the server you chose. The play log stays on the device until you export it, and never holds a key. The exception is the microphone: speech recognition is the browser's own, and most browsers run it on their maker's servers, so on Chrome your voice goes to Google. The desktop build has no microphone.

I didn't run a closed model next to Gemma, so I can't say one would write a worse caller. What I can say is that an open model let me build this the way I wanted: a game anyone can run on their own machine, that outlives any API, with a character I can take apart and fix when it lies to me.

My Agent Session

I built this with Claude Code. I had the ideas, made the design decisions, picked every sound, and tested it on my phone. Claude Code wrote most of the code, ran the measurements against Gemma, and drafted this post with me.

The loop was simple, and it's the part I'd recommend: play a call, export the log, and hand it over with one line about what felt wrong. Then measure the fix against the real model before believing it.

Prize Categories

Best Use of Gemma: Gemma 4 understands the player and voices both the caller and the Hollow, in English and Spanish, through a typed interface, on OpenRouter or locally in Ollama. The maze keeps it honest.

Peresós: a sloth that eats one item of my backlog a day, with Gemma 4 on my own GPU

Manuel Alejandro Hermoso — Sun, 25 Oct 2026 14:42:04 +0000

This is a submission for the Hacktoberfest Open-Source AI Challenge Week 3: Slow and Steady

What I Built

I have a pile. Everyone has one: the message from the landlord I haven't answered, the gym membership I keep meaning to cancel, the friend asking whether Friday still works. None of these takes long. All of them need me to sit down, think for a minute and write something, and that minute is what I keep putting off.

Peresós (Catalan for sloth, and for lazy) is a sloth that lives in my terminal and eats that pile, one item a day.

I feed it whatever I'm avoiding:

peresos feed "From my landlord: the yearly boiler check is due. The technician needs a morning next week when someone is home. Which day suits you?"

It eats files too: peresos feed bill.jpg, or right-click a photo or a PDF and Feed to Peresós. Gemma looks at photos itself. Ollama takes no PDFs, so Peresós reads them on my computer and gives Gemma the text, or pictures of a scan's first pages.

When I change my mind about an item, peresos pile edit 3 opens it in my editor, and peresos pile remove 3 takes it off. In the window, a pencil next to each item does the same.

Once a day I wake it with peresos. It takes the oldest item, and Gemma 4, running on my own machine, prepares the finished version: the reply written as me, the decision with one sentence on why, the note cleaned up, or for a task, only the first five-minute step. Then it waits, and I do the only part that needs me:

y take it: the finished version is saved, and the item leaves the pile for good
n bin it: deciding not to do something also finishes it
l later: back to the bottom of the pile
a another try: Gemma writes a different version, and knows which ones I didn't want
Enter: decide another day. It keeps the item in its mouth until I come back

The rules are what make it lazy in a good way:

One item a day, at most. It is a sloth. A pile of forty things is overwhelming; one thing, already done for you, is a five-second yes.
It never nags. Skip a week and it simply sleeps, then tells you how long, with some pride.
On a lazy day, it is lazier than you. peresos --lazy (or Something easy in the window) lets Gemma pick the easiest item on the pile and say why, then make the laziest version that still finishes it. Given a test pile with a tax return, a family trip, a gym membership and a friend asking about coffee, it picked the coffee: "Just a tiny 'yes' is all it takes, no need to rush." The next lazy wake took the gym and answered "Don't renew. At €45 per month for only 3 visits since June, the cost per visit is €15." Sometimes the laziest answer is not doing it, and it says so. The normal wake still eats the oldest item, so the tax return gets its turn.
It writes a line in its diary after every meal, in its own voice, and grows up as the pile shrinks: a baby that kicks its little legs, a young sloth chewing a leaf, a grown one yawning, and after ten items, a big round sloth asleep on its branch. Clear the whole pile and it climbs on top of its branch and sleeps there, full, until you feed it again.

And it's yours to dress up: peresos wear sunglasses coffee puts things on it, from sunglasses and a cap to a barretina (the red Catalan cap) or a steaming mug on the branch. Each item is a small drawing function, so adding your own is a good first pull request.

It also has a home. peresos window puts it in the tray, like JetBrains Toolbox: a pixel face in the top bar that shows what it's doing, and a small window with a pixel-art jungle, today's bite and a menu for everything the terminal does. The terminal can close, and the desktop tells me when Gemma is done. The leaves follow the season and the sky follows the weather outside, from fog to snow on its branch. Click the sloth and it answers: a pat and it closes its eyes, a tickle and it laughs, a poke while it chews and it says "Mmf. Mouth full."

An arrow in the title bar folds the window up to the sloth alone, so it can hang there while I work. Folded, the title bar says when a bite waits.

Getting it is one line, on Linux, macOS or Windows:

curl -fsSL https://raw.githubusercontent.com/deeptelar/peresos/main/install.sh | sh

(irm .../install.ps1 | iex in PowerShell.) It brings its own Java, then peresos doctor checks Ollama and Gemma and says what's missing. Where Ollama can't be installed, peresos gemma off still brings one item a day, as I wrote it.

Who gets to be lazier: anyone whose backlog is made of small things that each need a minute of thinking. The sloth does the minute. You do the yes.

Demo

That's a real session on Gemma 4 (12B) in Ollama, with the waiting cut short. First I tell it one fact about me, which it uses from then on: I work from home on Tuesdays and Thursdays. It turned the landlord's question into "Tuesday morning next week works well for me as I'll be at home", without me typing a day. The second peresos on the same day gets "It already ate today. One item a day is plenty."

Code

deeptelar / peresos

A sloth in your terminal that eats one item of your backlog a day. Gemma 4 on your own machine prepares the finished version; you only say yes or no. Built on Telar.

Peresós

A sloth that eats one item of your backlog a day. You feed it what you keep putting off, and Gemma 4, on your own machine, prepares the finished version. You only say yes or no.

Peresós is Catalan for sloth, and for lazy.

Install

# Linux and macOS (Apple silicon)
curl -fsSL https://raw.githubusercontent.com/deeptelar/peresos/main/install.sh | sh

# Windows, in PowerShell
irm https://raw.githubusercontent.com/deeptelar/peresos/main/install.ps1 | iex

It brings its own Java, the peresos command, a menu entry and Feed to Peresós in the right-click menu of photos and PDFs. You also need Ollama:

peresos doctor --fix    # checks everything and pulls Gemma 4 (gemma4:12b, about 8 GB)

peresos update and peresos uninstall do what they say. To build it yourself, see CONTRIBUTING.md.

Use it

peresos about "I work from home on Tuesdays and Thursdays"   # facts

…

View on GitHub

About 5,500 lines of Kotlin, plus 2,400 lines of tests. The tests run the whole workflow against a scripted model, so they need no GPU. On every release, GitHub Actions builds the installers for Linux, macOS and Windows, then installs, updates and uninstalls each one on a fresh machine. A soak test clicks the window's buttons at random through months of simulated days, while a terminal feeds and wakes the same sloth and Ollama stops halfway. It checks the pile, the checkpoint and the screen after every click, and it found four bugs in the window before I did.

How I Built It

The model: Gemma 4, in Ollama, on an 8 GB GPU (an RTX 3070). I use gemma4:12b through Ollama's OpenAI-compatible API. Gemma 4 thinks before it answers by default, and that turned out to be the most important knob:

For preparing the finished version, I let it think. The replies are better, and the 10 to 60 seconds don't matter for something you were going to put off for a week anyway.
For the diary line, I turn thinking off with reasoning_effort: "none". In my test, a three-word answer took 37 seconds with thinking and 4 without.

The workflow: a small graph. Peresós is built on Telar, an open-source Kotlin library for AI workflows that I maintain. To be clear about what's new: Telar existed before this challenge, and Peresós is a new app that uses it from Maven Central like any other library. One thing I did add to Telar this week, because the sloth needed it: images and PDFs in a model call (Attachment, released in 0.1.0-alpha14). Feeding Gemma a photo is one more argument:

model.ask<Bite>(chewPrompt(sloth, plate.text, about()), system = CHEF, attachments = plate.attachments)

A wake is five nodes:

START then wake
conditionalEdge(wake, targets = setOf(pick, chew, NodeRef.END)) { sloth ->
    when {
        sloth.rest != Rest.NONE -> NodeRef.END // already ate today, or nothing to eat
        sloth.lazy -> pick                     // a lazy wake: Gemma picks the easiest item first
        else -> chew                           // a normal wake eats the oldest
    }
}
pick then chew
chew then swallow
conditionalEdge(swallow, targets = setOf(chew, diary)) { sloth -> if (sloth.bite == null) chew else diary } // "another try" loops back
diary then NodeRef.END

Three things in there carry the whole idea:

The sloth is one data class, saved after every step. When it last ate, what it's chewing, its meals, its diary: all in a @Serializable Sloth, written to a checkpoint file. Its memory from one day to the next is simply the checkpoint of the last run.
It waits for me by stopping, not by blocking. The graph pauses before swallow. The process ends, the terminal can close, the computer can sleep. The next peresos finds the paused run and resumes it with my answer, without asking Gemma again. For a sloth, a workflow that can wait a day for a human is not an edge case, it's the main feature.
Gemma answers with a typed value, not text I have to parse.

   @Serializable
   data class Bite(
       @Description("REPLY for a message that waits for an answer, DECISION for a choice to make, NOTE for something to keep, TASK for something to do")
       val kind: Kind,
       @Description("A title of at most six words") val title: String,
       @Description("The finished thing, ready to use as it is ...") val finished: String,
   )

   val bite = model.ask<Bite>(chewPrompt(sloth, about()), system = CHEF)

ask gives Gemma the JSON schema of the class and asks again, with the error, if an answer doesn't fit.

One small detail I like: swallow changes the pile and writes the finished file inside an effect, which is saved with the step. If the computer dies halfway through, the sloth never eats the same item twice.

The window runs the same graph through Telar's GraphSession: the run is a StateFlow of snapshots (running, waiting for my answer, done, stopped) that Compose draws, and the buttons call start and resume. The terminal and the window share one checkpoint, so they're two views of the same sloth.

Three lessons from the first runs:

The sloth's voice leaked into my replies. The first reply to a friend ended with "There is no need to hurry." Charming for a sloth, odd from me. Now preparing the finished version has its own instructions, "write as that person, never as an assistant", and only the diary sounds like the sloth.
A good model leaves blanks instead of guessing. Asked for a day for the boiler check, Gemma wrote "Next [Day] morning". That was correct, since it didn't know my week, but it wasn't finished. So I added peresos about: a few facts it uses every time, kept in a local file.
Other people's computers are the hard part. The sloth took a day; installers for three systems took another. The first managed Windows PC still failed: its PowerShell blocked the .NET calls my installer used, so it now uses plain cmdlets, and CI tests that mode. That PC couldn't install Ollama either, which is where peresos gemma off came from.

Why Does Open Innovation Matter?

Look at what's on the pile: a message from a friend in Catalan, my landlord's email, how often I actually went to the gym, a photo of a bill. Together with the facts I gave it about myself, that's a small diary of my life. I would not paste it into a hosted API every day for the convenience of not writing a reply.

With an open-weight model, I don't have to. Gemma 4 runs on my own GPU, and the pile, the facts, the diary and the checkpoints are plain files in ~/.peresos. Nothing leaves my machine, and there's no bill. (Only two things go out, and only when I ask: my town to Open-Meteo for the weather, and peresos update to GitHub. Never the pile.) That also means a slow model is fine: the sloth can think as long as it likes, and nobody is counting tokens.

The open pieces all the way down (Gemma, Ollama, an open-source workflow library) are why this could be a toy I trust with real messages, instead of a demo I'd only feed fake ones.

And a personal opinion, since this is what the theme is about for me: open-source models like Gemma are going to redefine how we think about IoT and small devices, especially self-contained intelligence in offline environments, where privacy and security are key. Devices and programs with these capabilities, that we can interact with, will help people in their daily lives. This is the integration of AI into society that will benefit everyone.

Prize Categories

Gemma: Gemma 4 does all the work, locally in Ollama: typed answers for the finished versions, with thinking on, reading photos and scanned PDFs, and the diary with thinking off.

Hacktoberfest: 13 small, well-described issues in a Kotlin library for AI agents

Manuel Alejandro Hermoso — Fri, 23 Oct 2026 05:46:17 +0000

Hacktoberfest ends on October 31. If you write Kotlin, or want to, and are looking for a pull request that gets reviewed quickly, here are 13 open issues in Telar. Each one says what to build, which files to read first, and when it's done.

What Telar is

An open-source library (Apache 2.0) for AI agents and workflows in Kotlin Multiplatform. A workflow is a small graph: your own data class is the state, each node is a suspend function that returns a copy of it, and arrows decide what runs next. Around that there are checkpoints, pausing for a person's approval, retries, streaming, a tool-calling agent, MCP tools, and models from Claude, OpenAI, Gemini, Ollama, llama.cpp and LangChain4j. It runs on the JVM, Android, iOS, desktop and in the browser.

It's an early alpha, written mostly by one person, which is why your pull request matters here and doesn't disappear in a queue.

What happens to your pull request

The first fix from outside the project came in this week. It was reviewed and merged the same day, and the next morning it was on Maven Central, in 0.1.0-alpha13, with the contributor's name in the release notes.

That's the deal for everyone:

A review within a day or two, with concrete comments, not "LGTM" and not silence.
Your name in the changelog and the release notes of the version that ships your change.
hacktoberfest-accepted on every merged pull request, and the repository has the hacktoberfest topic.
CI runs on your pull request by itself, so you see the result without waiting for anyone.

The issues

A sample: one evening, the public API only

Each of these is a small runnable program, plus a test, that shows one feature. You read a guide, write code that uses the library, and the guide gets a "runnable version" link to yours. You don't need to know the internals.

#73 Go back in a run with history and fork
#74 Merge the states of parallel nodes with mergeRules
#75 Report progress from inside a node
#139 Watch a run with an AgentObserver
#140 Try a failing node again with Retry and timeout
#141 Charge a card once with effect, also when the step runs again

None of them needs an API key: the samples use a scripted model when there is none.

Small and outside the Kotlin code

#77 Make the API reference link back to the documentation site
#79 telar-bom: a bill of materials, so an app names the version of Telar once (Gradle)
#78 Run the agent sample against a provider you have a key for (Groq, OpenRouter, Mistral, DeepSeek, LM Studio, vLLM, ...) and report what works. A comment already helps; a pull request that adds the result to the guide also counts for Hacktoberfest.

Bigger, for when you want something to sink your teeth into

#137 telar-checkpoint-postgres: save runs in PostgreSQL
#138 telar-otel: a span for each call to a model and each tool call
#80 A docs page for people who know LangGraph for Python
#81 Run the JS and Wasm tests of the agent modules in a real browser

How to start

Comment on the issue you want, so two people don't write the same thing. I'll assign it to you.
Set up: a JDK 17 or newer is all you need. Gradle, Kotlin and the rest come with the wrapper.

   git clone https://github.com/deeptelar/telar.git
   cd telar
   ./gradlew :samples:check   # enough for a sample; ./gradlew check for everything

Open the pull request when the issue's "Done when" list is green. CONTRIBUTING.md has the design rules, and questions are welcome on the issue itself.

Changes made with an AI assistant are fine, as long as you understand and have run what you submit.

An AI agent that asks before it pays: human approval for tool calls in Kotlin

Manuel Alejandro Hermoso — Tue, 13 Oct 2026 12:26:00 +0000

Updated Oct 2026 for 0.1.0-alpha12: MCP tools, retries, tracing and a SQLite checkpointer are now in.

An agent that only talks is easy to trust. An agent with a refund tool is not. The model decides when to call it and with which amount, and the same question can get a different answer tomorrow.

I don't think a better prompt solves that. "Never refund without permission" is a sentence the model usually follows, and "usually" is not good enough for money. What solves it is structure around the model: ordinary code that decides where the model may act alone and where it has to wait.

This article builds that in Kotlin, in five steps: an agent, a pause before it acts, a pause that survives a restart, a test without a model, and a rule the model never gets to see. It uses Telar, an open-source library for agent workflows that I am writing. Every example here was compiled and run against the current release, 0.1.0-alpha12.

1. The agent

A tool is a function the model may call. Its input is a @Serializable class, and the library builds the schema the model reads from that class.

@Serializable
data class OrderLookup(
    @Description("The order number, for example \"1001\"") val orderId: String,
)

@Serializable
data class RefundRequest(
    @Description("The order number, for example \"1001\"") val orderId: String,
    @Description("The amount to pay back, in euros") val euros: Int,
)

fun helpDesk(model: ChatModel, pay: suspend (RefundRequest) -> Unit): CompiledGraph<AgentState> {
    val orderStatus = Tool<OrderLookup>("order_status", "Returns what was ordered, what it cost and when it arrived.") { lookup ->
        "Order ${lookup.orderId}: one margherita for 9 euros, delivered 70 minutes late." // your database here
    }
    val refund = Tool<RefundRequest>("refund", "Pays money back for an order.") { request ->
        pay(request)
        "Paid back ${request.euros} euros for order ${request.orderId}."
    }
    return toolAgent(
        model,
        tools = listOf(orderStatus, refund),
        system = "You work at the help desk of a pizzeria. Look an order up before you decide anything about it.",
    )
}

toolAgent is the usual loop: the model answers or asks for tools, the tools run, and their results go back to the model, until it has an answer.

val model = AnthropicChatModel(HttpClient(), apiKey = System.getenv("ANTHROPIC_API_KEY"), model = "claude-opus-5-5")
val agent = helpDesk(model, pay = { payments.refund(it.orderId, it.euros) })

val state = agent.invoke(AgentState("My pizza for order 1001 came 70 minutes late. I want my money back.")).state
println(state.answer)

This works, and it pays whenever the model thinks it should. That is the part to fix.

2. Pause before the tools run

The agent is not a black box. It is a graph of two nodes, model and tools, with an arrow back from one to the other. And a graph can be told to stop before a node:

val config = GraphConfig(
    threadId = "ticket-42",
    checkpointer = MemoryCheckpointer<AgentState>(),
    interruptBefore = setOf("tools"),
)

Now invoke returns GraphResult.Interrupted each time the model has asked for tools and none of them has run yet. The calls that wait are in the state, with their names and their inputs:

suspend fun answer(
    agent: CompiledGraph<AgentState>,
    question: String,
    config: GraphConfig<AgentState>,
    approve: suspend (List<ToolCall>) -> Boolean,
): AgentState {
    var result = agent.invoke(AgentState(question), config)
    while (result is GraphResult.Interrupted) {
        val refunds = result.state.messages.pendingToolCalls().filter { it.name == "refund" }
        result = if (refunds.isEmpty() || approve(refunds)) {
            // Nothing risky, or a person said yes: run the calls.
            agent.resume(config)
        } else {
            // A person said no: answer the call yourself. A call that already has a result is not run.
            agent.resume(config) { state ->
                state.copy(messages = state.messages + refunds.map {
                    ChatMessage.ToolResult(it.id, it.name, "A person declined this refund.", isError = true)
                })
            }
        }
    }
    return result.state
}

Three things happen in that loop:

Lookups pass without a question. The code decides which tools need a person, by name. Nobody is asked to approve reading an order.
A yes runs the call as the model wrote it. approve gets the calls, so your screen can show refund {"orderId":"1001","euros":9} before anyone clicks.
A no goes back to the model as a result. The model reads "A person declined this refund." and writes the customer an answer that fits. The conversation stays whole.

The difference from a prompt is where the guarantee lives. The refund function is not reached unless approve returned true. The model cannot talk its way past an if.

3. The pause survives a restart

A person may answer in a minute or after lunch, and the server may be deployed in between. Telar saves a checkpoint after every step, so the only change is where it is saved:

val config = GraphConfig(
    threadId = "ticket-42",
    // One JSON file per thread. AgentState is @Serializable, so nothing else is needed.
    checkpointer = FileCheckpointer(Path("checkpoints"), KotlinxStateSerializer<AgentState>()),
    interruptBefore = setOf("tools"),
)

After a restart, lastResult reads where a thread stopped without running anything:

when (val result = agent.lastResult(config)) {
    is GraphResult.Interrupted -> showApproval(result.state.messages.pendingToolCalls()) // still waiting for a person
    is GraphResult.Completed -> showAnswer(result.state.answer)
    null -> showEmptyForm() // this ticket has never run
}

agent.resume(config) then continues in the new process, from the step where the old one stopped.

One thing to know before you rely on this for payments: a tool call that finished is saved with the step, so resuming after a failure or a restart gives it its saved result instead of paying twice. A call that was cut off in the middle, by a crash during the payment itself, can run again. Give a side effect like a refund an idempotency key, for example made from the order number.

There are checkpointers for memory, files, the browser's localStorage, and SQLite through SQLDelight on every platform. Checkpointer is a small interface, so a server database is one class away; PostgreSQL is an open issue if you want to help.

4. Test it without a model

ChatModel is an interface with one function, so a model that follows a script is a lambda. This one looks the order up, asks for the refund, and then answers according to what came back:

val scripted = ChatModel { request ->
    val results = request.messages.filterIsInstance<ChatMessage.ToolResult>()
    ChatResponse(
        when (results.size) {
            0 -> ChatMessage.Assistant(toolCalls = listOf(ToolCall("call-1", "order_status", buildJsonObject { put("orderId", "1001") })))
            1 -> ChatMessage.Assistant(toolCalls = listOf(ToolCall("call-2", "refund", buildJsonObject { put("orderId", "1001"); put("euros", 9) })))
            else -> ChatMessage.Assistant(if (results.last().isError) "I am sorry, I cannot refund this order." else "Your 9 euros are on their way.")
        },
    )
}

And the property that matters becomes a unit test that runs in milliseconds, with no key and no network:

@Test
fun aRefundThatAPersonDeclinesIsNotPaid() = runTest {
    val paid = mutableListOf<RefundRequest>()
    val agent = helpDesk(scripted, pay = { paid += it })
    val config = GraphConfig(checkpointer = MemoryCheckpointer<AgentState>(), interruptBefore = setOf("tools"))

    val state = answer(agent, "My pizza for order 1001 came 70 minutes late. I want my money back.", config, approve = { false })

    assertEquals(emptyList(), paid)
    assertEquals("I am sorry, I cannot refund this order.", state.answer)
}

The model is the part you cannot predict. Everything around it is plain Kotlin on an immutable state, and you test it the way you test any other Kotlin.

5. Rules go in code, not in the prompt

Some rules have no exceptions. Say orders older than 30 days are never refunded. You could write that into the system prompt and hope. Or the model never sees those orders.

toolLoop is the same agent as a part of a graph of your own, with the conversation in a state you define. model, orderStatus and refund are the ones from step 1:

data class Complaint(
    val orderId: String,
    val text: String,
    val daysAgo: Int,
    val messages: List<ChatMessage> = emptyList(),
    val reply: String = "",
)

val desk = StateGraph<Complaint> {
    val tooOld = node("too_old") { it.copy(reply = "Orders older than 30 days cannot be refunded.") }
    val send = node("send") { it.copy(reply = it.reply.ifEmpty { it.messages.last().text }) }
    val agent = toolLoop(
        model = model,
        tools = listOf(orderStatus, refund),
        // Where the conversation is in your state, and how to add messages to it.
        messages = { it.messages },
        append = { complaint, new -> complaint.copy(messages = complaint.messages + new) },
        firstMessage = { "Order ${it.orderId}: ${it.text}" },
        then = send,
    )

    conditionalEdge(START, targets = setOf(agent, tooOld)) { if (it.daysAgo > 30) tooOld else agent }
    tooOld then send
    send then END
}.compile()

An old order takes the arrow to too_old, and the model is not called at all. No tokens, no risk, and a test that proves it.

compile() checks the drawing before anything runs. A node that nothing leads to, or an arrow to a node that does not exist, fails there and not in production at the fourth step of a run.

Where this runs

All of the above is Kotlin Multiplatform. The core depends only on kotlinx-coroutines, and the same graph runs on the JVM, Android, iOS, desktop, and in the browser as JS or Wasm. The models are Claude and anything with the API of OpenAI (OpenAI, Gemini, Ollama, Groq and others) on Ktor client, and any LangChain4j model on the JVM.

To see graphs like these run without writing code, there is a small game in the browser in which every stage is a Telar graph. It needs no account and no API key.

What is missing

Telar is an early alpha, and I would rather say so here than have you find out:

The API can still change before 1.0.
A message holds text only: no images or files yet.
A long conversation is sent to the model in full every time.
Tracing has spans for runs and nodes, but not yet for each model call and tool call.
The full list is on the roadmap.
If you need a complete agent platform today, Koog from JetBrains is the safer choice. The site has a comparison with Koog, LangGraph4j and LangChain4j.

Telar is for the case this article is about: the workflow around the model is the hard part, and you want it to be ordinary, typed, testable Kotlin.

Try it

// build.gradle.kts. `@Serializable` needs the plugin kotlin("plugin.serialization").
implementation("dev.deeptelar:telar-agent:0.1.0-alpha12")
implementation("dev.deeptelar:telar-anthropic:0.1.0-alpha12")       // or telar-openai: OpenAI, Gemini, Ollama, ...
implementation("dev.deeptelar:telar-checkpoint-file:0.1.0-alpha12") // step 3
implementation("dev.deeptelar:telar-serialization:0.1.0-alpha12")   // step 3
implementation("io.ktor:ktor-client-cio:3.6.0")                     // any Ktor engine

Code: https://github.com/deeptelar/telar
Documentation and tutorial: https://deeptelar.github.io/telar/
The guides behind this article: Agents with tools and Human-in-the-loop

It is early, which makes this the best time for feedback. If something in the API looks wrong to you, open an issue or tell me in the comments.

DEV Community: Manuel Alejandro Hermoso

Scary Truc: a stranger calls you from inside a maze, and your voice is all they have

What I Built

Demo

Code

deeptelar / scary-truc

A horror game played by phone: talk a terrified stranger out of a maze while something hunts by sound. Gemma 4 plays the caller, in your browser. Kotlin Multiplatform, built with Telar.

Scary Truc

How I Built It

Why Does Open Innovation Matter?

My Agent Session

Prize Categories

Peresós: a sloth that eats one item of my backlog a day, with Gemma 4 on my own GPU

What I Built

Demo

Code

deeptelar / peresos

A sloth in your terminal that eats one item of your backlog a day. Gemma 4 on your own machine prepares the finished version; you only say yes or no. Built on Telar.

Peresós

Install

Use it

How I Built It

Why Does Open Innovation Matter?

Prize Categories

Hacktoberfest: 13 small, well-described issues in a Kotlin library for AI agents

What Telar is

What happens to your pull request

The issues

A sample: one evening, the public API only

Small and outside the Kotlin code

Bigger, for when you want something to sink your teeth into

How to start

Links

An AI agent that asks before it pays: human approval for tool calls in Kotlin

1. The agent

2. Pause before the tools run

3. The pause survives a restart

4. Test it without a model

5. Rules go in code, not in the prompt

Where this runs

What is missing

Try it