Stavros' Stuff

How I write software with LLMs

Tue, 10 Mar 2026 11:58:51 +0000

I don't care for the joy of programming

Lately I’ve gotten heavily back into making stuff, and it’s mostly because of LLMs. I thought that I liked programming, but it turned out that what I like was making things, and programming was just one way to do that. Since LLMs have become good at programming, I’ve been using them to make stuff nonstop, and it’s very exciting that we’re at the beginning of yet another entirely unexplored frontier.

There’s a lot of debate about LLMs at the moment, but a few friends have asked me about my specific workflow, so I decided to write it up in detail, in the hopes that it helps them (and you) make things more easily, quickly, and with higher quality than before.

I’ve also included a real (annotated) coding session at the end. You can go there directly if you want to skip the workflow details.

The benefits

For the first time ever, around the release of Codex 5.2 (which feels like a century ago) and, more recently, Opus 4.6, I was surprised to discover that I can now write software with LLMs with a very low defect rate, probably significantly lower than if I had hand-written the code, without losing the benefit of knowing how the entire system works. Before that, code would quickly devolve into unmaintainability after two or three days of programming, but now I’ve been working on a few projects for weeks non-stop, growing to tens of thousands of useful lines of code, with each change being as reliable as the first one.

I also noticed that my engineering skills haven’t become useless, they’ve just shifted: I no longer need to know how to write code correctly at all, but it’s now massively more important to understand how to architect a system correctly, and how to make the right choices to make something usable.

On projects where I have no understanding of the underlying technology (e.g. mobile apps), the code still quickly becomes a mess of bad choices. However, on projects where I know the technologies used well (e.g. backend apps, though not necessarily in Python), this hasn’t happened yet, even at tens of thousands of SLoC. Most of that must be because the models are getting better, but I think that a lot of it is also because I’ve improved my way of working with the models.

One thing I’ve noticed is that different people get wildly different results with LLMs, so I suspect there’s some element of how you’re talking to them that affects the results. Because of that, I’m going to drill very far down into the weeds in this article, going as far as posting actual sessions, so you can see all the details of how I develop.

Another point that should be mentioned is that I don’t know how models will evolve in the future, but I’ve noticed a trend: In the early days of LLMs (not so much with GPT-2, as that was very limited, but with davinci onwards), I had to review every line of code and make sure that it was correct. With later generations of LLMs, that went up to the level of the function, so I didn’t have to check the code, but did have to check that functions were correct. Now, this is mostly at the level of “general architecture”, and there may be a time (next year) when not even that is necessary. For now, though, you still need a human with good coding skills.

What I’ve built this way

I’ve built quite a few things recently, and I want to list some of them here because a common criticism of LLMs is that people only use them for toy scripts. These projects range from serious daily drivers to art projects, but they’re all real, maintained projects that I use every day:

Stavrobot

The largest thing I’ve built lately is an alternative to OpenClaw that focuses on security. I’ve wanted an LLM personal assistant for years, and I finally got one with this. Here, most people say “but you can’t make LLMs secure!”, which is misunderstanding that security is all about tradeoffs, and that what my agent tries to do is maximize security for a given amount of usability. I think it succeeds very well, I’ve been using it for a while now and really like the fact that I can reason exactly about what it can and can’t do.

It manages my calendar and intelligently makes decisions about my availability or any clashes, does research for me, extends itself by writing code, reminds me of all the things I used to forget and manages chores autonomously, etc. Assistants are something that you can’t really explain the benefit of, because they don’t have one killer feature, but they alleviate a thousand small paper cuts, paper cuts which are different for each person. So, trying to explain to someone what’s so good about having an assistant ends up getting a reaction of “but I don’t need any of the things you need” and misses the point that everyone needs different things, and an agent with access to tools and the ability to make intelligent decisions to solve problems is a great help for anyone.

I’m planning to write this up in more detail soon, as there were some very interesting challenges when designing it, and I like the way I solved them.

Middle

Maybe my naming recently hasn’t been stellar, but this is a small pendant that records voice notes, transcribes them, and optionally POSTs them to a webhook of your choice. I have it send the voice notes to my LLM, and it feels great to just take the thing out of my pocket at any time, press a button, and record a thought or ask a question into it, and know that the answer or todo will be there next time I check my assistant’s messages.

It’s a simple thing, but the usefulness comes not so much from what it does, but from the way it does it. It’s always available, always reliable, and with zero friction to use.

Sleight of hand

I’m planning to write something about this too, but this one is more of an art piece: It’s a ticking wall clock that ticks seconds irregularly, but is always accurate to the minute (with its time getting synced over the internet). It has various modes, one mode has variable tick timing, from 500 ms to 1500 ms, which is delightfully infuriating. Another mode ticks imperceptibly more quickly than a second, but then pauses for a second randomly, making the unsuspecting observer question their sanity. Another one races to :59 at double speed and then waits there for thirty seconds, and the last one is simply a normal clock, because all the irregular ticking drives me crazy.

Pine Town

Pine Town is a whimsical infinite multiplayer canvas of a meadow, where you get your own little plot of land to draw on. Most people draw… questionable content, but once in a while an adult will visit and draw something nice. Some drawings are real gems, and it’s generally fun scrolling around to see what people have made.

I’ve made all these projects with LLMs, and have never even read most of their code, but I’m still intimately familiar with each project’s architecture and inner workings. This is how:

The harness

For the harness, I use OpenCode. I really like its features, but obviously there are many choices for this, and I’ve had a good experience with Pi as well, but whatever harness you use, it needs to let you:

Use multiple models from different companies. Most first-party harnesses (Claude Code, Codex CLI, Gemini CLI) will fail this, as companies only want you to use their models, but this is necessary.
Define custom agents that can autonomously call each other.

There are various other nice-to-haves, such as session support, worktree management, etc, that you might want to have depending on your project and tech stack, but those are up to you. I’ll explain the two requirements above, and why they’re necessary.

Multiple models

You can consider a specific model (e.g. Claude Opus) as a person. Sure, you can start again with a clean context, but the model will mostly have the same opinions/strengths/weaknesses as it did before, and it’s very likely to agree with itself. This means that it’s fairly useless to ask a model to review the code it just wrote, as it tends to mostly agree with itself, but it also means that getting a different model to review the code will lead to a big improvement. Essentially, you’re getting a review from a second set of eyes.

Different models will have different strengths and weaknesses here. For example (and this is very specific to today’s models), I find Codex 5.4 pretty nitpicky and pedantic. This isn’t something I want when I want to get code written, but it definitely is something I want for a review. The decisions Opus 4.6 makes correlate quite well with the decisions I would have made, and Gemini 3 Flash (yes, Flash!) has even been very good at coming up with solutions that other models didn’t see.

Everyone has a different opinion on what model suits them for which job, and models tend to alternate (e.g. I used Codex as my main model back in November, switching back to Opus later). To get the best results, you need a mix of all of them.

Agents that call each other

The workflow I use consists of different agents, and if the harness doesn’t have the ability to let agents talk to each other, you’ll be doing a lot of annoying ferrying of information between LLMs. You probably want to cut down on that, so this is a very useful feature.

My workflow

My workflow consists of an architect, a developer, and one to three reviewers, depending on the importance of the project. These agents are configured as OpenCode agents (basically skill files, files with instructions for how I want each agent to behave).

I use multiple agents (rather than using just one for everything) for three reasons:

It allows me to use an expensive model (Opus) for planning and generating a detailed plan but a cheap one (Sonnet) for the actual writing of the code. That just saves on tokens versus having Opus do the whole thing.
It lets me use different models to review the code, which does increase quality because different models will catch different things when reviewing.
It lets me use agents with different capabilities (e.g. one might have read-only access to the code, whereas the other might have write access to).

I don’t think using two agents with the same model and the same capabilities makes much sense, as I think it’s something like one person pretending to wear different hats, but I haven’t studied this extensively.

I also tend to write the skill files by hand, as I find it doesn’t really help if you ask the LLM to write a skill. It would be like asking someone to write up instructions on how to be a great engineer and then gave them their own instructions and said “here’s how to be a great engineer, now be one”. It obviously won’t really make them better, so I try to write the instructions myself.

If you want to try this yourself, you can download my agent files.

The architect

The architect (Claude Opus 4.6, currently) is the only agent I interact with. This needs to be a very strong model, typically the strongest model I have access to. This step doesn’t consume too many tokens, as it’s mostly chat, but you want this to be very well-reasoned.

I’ll tell the LLM my main goal (which will be a very specific feature or bugfix e.g. “I want to add retries with exponential backoff to Stavrobot so that it can retry if the LLM provider is down”), and talk to it until I’m sure it understands what I want. This step takes the most time, sometimes even up to half an hour of back-and-forth until we finalize all the goals, limitations, and tradeoffs of the approach, and agree on what the end architecture should look like. It results in a reasonably low-level plan, with a level of detail of individual files and functions. For example, tasks might be “I’ll add exponential backoff to these three codepaths of these two components in this file, as no other component talks to the LLM provider”.

I know that some people in this step prefer to have the LLM write out the plan to a file, and then they add their feedback to that file instead of talking to the LLM. This is a matter of personal preference, as I can see both approaches working equally well, so feel free to do the reviews that way if it suits you more. Personally, I prefer chatting to the LLM.

To clarify, in this step I’m not just prompting, I’m shaping the plan with the help of the LLM. I still have to correct the LLM a lot, either because it’s wrong or simply because it’s not doing things the way I’d do them, and that’s a big part of my contribution, as well as the part I get joy from. This direction is what lets me call projects mine, because someone else using the same LLM would have come up with a different thing.

When I’m satisfied that we’ve ironed out all the kinks (the LLM is very helpful at this, asking questions for what it doesn’t know yet and giving me options), I can finally approve the plan. I’ve asked the architect to not start anything until I actually say the word “approved”, as a few models tend to be overeager and go off to start the implementation when they feel like they understood, whereas I want to make sure I’m confident it understood.

Then, the architect will split the work into tasks, and write each task out into a plan file, usually in more detail (and at a lower level) than our chat, and call the developer to start work. This gives the developer concrete direction, and minimizes the high-level choices the developer can make, as the choices have already been made for it.

The developer

The developer can be a weaker, more token-efficient model (I use Sonnet 4.6). The plan shouldn’t give it much leeway into what it can do, and its job is strictly to implement the changes in the plan. When it’s done, it reports back to the architect, who calls the reviewers to review the work.

The reviewers

Each reviewer will independently look at the plan and diff of the feature that was just implemented, and critique it. For this step, I will always use at least Codex, sometimes I’ll add Gemini, and on important projects I’ll add Opus as well.

This feedback goes back to the architect, who judges whether the feedback should be addressed, or if it’s inconsequential enough that it can be skipped. I’ve found that Opus is very good at choosing the right feedback to implement, sometimes ignoring feedback because it’s too pedantic (i.e. hard to implement and unlikely to be a problem in practice). Obviously, when I use objective assessments like “very good”, I really mean “I agree with it a lot”.

The overall approach

This way of working means that I still know every choice that was made above the function level, and can use that knowledge in subsequent runs. I often notice the LLM recommend things that might be good in another codebase, but either won’t work or are suboptimal in my codebase, which shows that the LLM has some blind spots when researching the code. I will often say “no, you should do this using Y”, at which point the LLM realizes that Y actually exists in the code and is a better way than the one it recommended.

Failure modes

On the flip side, when I’m not familiar enough with the technology to be on top of the architecture, I tend to not catch bad decisions that the LLM makes. This leads to the LLM building more and more on top of those bad decisions, eventually getting in a state where it can’t untangle the mess. You know this happens when you keep telling the LLM the code doesn’t work, it says “I know why! Let me fix it” and keeps breaking things more and more.

That’s a real failure mode that has happened to me too many times now, which is why I ended up with this workflow. For this reason, I try to understand things as much as I can while planning, even if I’m unfamiliar with the specific technology. If I manage to steer the LLM well, it saves a lot of trouble later on.

A real session

Here’s an annotated transcript from a real session where I add email support to Stavrobot. I’ve trimmed the tool calls and verbose bits, but the conversation and decision-making process is exactly as it happened.

I start by telling the LLM what I’d like to implement, at a very high level. Sometimes I’ll give it more detail, especially if I already have an idea of how I want the implementation done.

Me:  I'd like to add email support to this bot. Let's think through
     how we would do this.

The bot reads the code and finds all the relevant bits, and asks some questions.

LLM: Good overview acquired. Here's what I see and the questions we
     need to resolve:

     ## Current pattern

     All channels follow the same flow: inbound webhook/listener →
     enqueueMessage(message, source, sender, attachments) → LLM
     processes → LLM calls send_*_message tool to reply. Channels are
     either in-process (Telegram webhooks, WhatsApp via Baileys) or
     separate containers (Signal bridge). Email would be a new channel
     following this same pattern.

     ## Key design questions

     1. Inbound — how does email arrive?
        - IMAP polling (simplest — poll a mailbox on a timer, works
          with any provider)
        - Webhook from a transactional email service (SendGrid/Mailgun
          inbound parse — requires that service)
        - Run an SMTP server (most complex, requires DNS/MX setup)

     2. Outbound — how do we send?
        - SMTP client (works with any provider — Gmail, Fastmail,
          self-hosted)
        - Transactional email API (SendGrid/Mailgun API)

     3. What's your actual use case? This affects several decisions:
        - Full bidirectional conversation (reply to emails, maintain
          threads)?
        - One-way notifications from the bot?
        - Processing incoming emails (e.g., forwarded emails,
          digests)?

     4. Architecture — separate container or in-process?
        Signal uses a bridge container because signal-cli is a heavy
        Java process. Email libraries are lightweight, so in-process
        (like Telegram) is viable. But the AGENTS.md rule about not
        adding runtimes to the app container doesn't apply here since
        it's just TypeScript/Node.

     5. Email-specific concerns:
        - How to handle HTML emails? Strip to plain text? Pass a
          markdown conversion to the LLM?
        - Thread tracking — match replies to conversations by
          In-Reply-To/References headers, or treat each email
          independently?
        - Attachments — needed?

     What's the scenario you're envisioning? That'll narrow this down
     fast.

In this session, I came with just a bit of an idea that hadn’t been thought through yet. The LLM helps by asking specific questions, where I decide which way I want the implementation to go:

Me:  1. Email will arrive from a webhook, yes. I will create a
     Cloudflare Email worker that will forward the entire body of the
     email via webhook. It'll upload a JSON version of the message:

     {"from":"me@mydomain.com", etc}

     2. SMTP client

     3. Full bidirectional conversation, yes. This will be the same as
     how interlocutors work with the other transports, if someone sends
     an email to the bot, it will be ignored unless they are set up as
     an interlocutor. The owner can also send emails or forward emails
     for processing.

     4. In-process, since this will be a webhook.

     5. Markdown conversion, yes. Let's treat each email independently
     for now, and then we can change that if necessary. Attachments are
     needed, they should work like any other platform, the agent will
     receive them as files.

     The scenario I'm envisioning is both being able to correspond with
     people over email via subagents (like the bot currently does with
     Signal/Telegram/Whatsapp) and the owner being able to forward
     emails (e.g. a confirmation email for a booking) for the bot to
     process and ingest the info. Does this make sense? What edge cases
     can you foresee, or is there something you're worried about?

The LLM shapes the plan, giving it more detail:

LLM: This makes sense and fits cleanly into the existing channel
     pattern. Here are my observations and the edge cases I see:

     ## Concerns and edge cases

     1. MIME parsing is non-trivial. Plain text emails are easy, but
        real-world emails are multipart MIME (HTML+text alternatives,
        inline images, attachments, nested multipart parts, various
        character encodings). We should use mailparser (from the
        Nodemailer project) to parse the raw RFC 2822 message
        server-side rather than trying to handle this in the worker.
        This means the worker payload can be minimal — just from, to,
        and raw.

     2. Webhook authentication. The endpoint must be public (Cloudflare
        can't do a browser login), but we need to prevent anyone from
        POSTing fake emails. Simplest approach matching the Telegram
        pattern: generate a random secret on startup, but since we
        can't call back to Cloudflare to register it, we'd configure a
        shared secret in config.toml and have the worker send it as a
        header. The endpoint validates it.

     3. Outbound emails need a subject line. Every other channel is
        subject-less, but email requires one. The send_email tool needs
        a subject parameter that the LLM provides. This is a new thing
        for the agent to handle.

     4. HTML-only emails. Some emails have no plain text part at all.
        mailparser can extract textAsHtml which we'd convert to
        markdown. The html-to-text library handles this well, or
        mailparser itself provides a .text property that does basic
        HTML stripping.

     5. From address identity. For outbound SMTP, the from address must
        match what the SMTP server allows. This is a config value. If
        someone emails bot@mydomain.com, the reply should come from
        that address.

     6. Forwarded emails for processing. When the owner forwards an
        email, the original sender's address will be in the forwarded
        body, not in the from field (which will be the owner's
        address). The LLM will need to understand this contextually —
        no special code needed, the forwarded content will just be in
        the message body. This should work naturally.

     7. Attachments on outbound. The existing send_*_message tools
        support attachments via file paths. send_email would need the
        same, using nodemailer to attach files. This is
        straightforward.

     ## Proposed design

     Worker simplification:
       // Only send what we need — parse everything from raw
       // server-side
       const payload = {
         from: message.from,
         to: message.to,
         raw: rawEmail
       };
       // Add auth header
       headers: {
         "Authorization": "Bearer <secret>",
         "Content-Type": "application/json"
       }

     Config (config.toml):
       [email]
       smtp_host = "smtp.example.com"
       smtp_port = 465
       smtp_user = "..."
       smtp_password = "..."
       from_address = "bot@mydomain.com"
       webhook_secret = "some-random-secret"

     Inbound flow:
       - POST /email/webhook (public route, validated by webhook_secret
         header)
       - Parse raw with mailparser → extract subject, text body (with
         HTML fallback → markdown), attachments
       - Format message to LLM as: Subject: ...\n\n<body>
       - Save attachments via saveAttachment()
       - enqueueMessage(message, "email", senderEmailAddress,
         attachments)
       - Add "email" to GATED_SOURCES, add email handling to
         isInAllowlist()

     Outbound flow:
       - New send_email tool with params: to, subject, body
         (markdown), attachments (optional file paths)
       - Convert markdown body to HTML for the email (with plain text
         fallback)
       - Send via nodemailer SMTP transport
       - Interlocutor identity service: "email", identifier: email
         address

     New dependencies: mailparser, nodemailer, html-to-text (or we can
     rely on mailparser's built-in text extraction and skip
     html-to-text initially — we can add it if the quality is
     insufficient).

     Files touched:
       - src/email.ts — new file: webhook handler, MIME parsing,
         inbound processing
       - src/email-api.ts — new file: SMTP sending via nodemailer
       - src/agent.ts — add send_email tool definition
       - src/config.ts — add EmailConfig interface and load it
       - src/index.ts — add /email/webhook route, whitelist it in
         isPublicRoute()
       - src/queue.ts — add "email" to GATED_SOURCES
       - src/allowlist.ts — add email channel handling
       - config.example.toml — add [email] section

     Explicitly not doing (YAGNI):
       - Email threading / In-Reply-To headers (you said treat
         independently)
       - CC/BCC handling
       - Bounce handling
       - Read receipts
       - Rate limiting
       - Email signature stripping (LLM can handle this contextually)

     Does this look right? Anything you'd change before I write it up
     as tasks?

I reply with a few things that I see it has missed. This requires me to know the architecture well, and following this process keeps me up to date with all the changes at a moderately low level.

Me:  Make sure to update the README.md and config.example.toml as
     well. Also remember to change the email allowlist page to not
     validate E.164 for these

The LLM updates the plan and asks any final questions.

LLM: Good, now I have the full picture. Here's the updated agreement:

     ## Requirements

     1. Inbound email via Cloudflare Email Worker webhook → POST
        /email/webhook (public, authenticated by shared secret)
     2. Outbound email via SMTP (nodemailer) through a send_email tool
        (with to, subject, body, optional attachments)
     3. Gated channel — email added to GATED_SOURCES, allowlist, and
        interlocutor identity system (service: "email", identifier:
        email address)
     4. Allowlist UI — new "Email allowlist" section in the settings
        page; validates email format (not E.164)
     5. Allowlist data — Allowlist interface gains an email: string[]
        field; backend validation accepts email addresses
     6. Owner config — owner.email in config.toml, auto-seeded into
        allowlist like the other channels
     7. MIME parsing — use mailparser to extract subject, text body
        (HTML fallback), and attachments from the raw RFC 2822 message
     8. Message format to LLM — Subject: <subject>\n\n<body> so the
        agent sees what the email is about
     9. Config — new [email] section: smtp_host, smtp_port, smtp_user,
        smtp_password, from_address, webhook_secret
     10. Update config.example.toml, README.md

     ## Constraints

     - In-process (no new container)
     - Email is optional — if [email] is absent from config, no email
       functionality loads (like the other optional channels)
     - Follow existing patterns exactly (webhook handling like
       Telegram, allowlist like WhatsApp/Signal, tool definition like
       other send tools)

     ## Success criteria

     - Can receive an email via webhook, have it processed by the LLM,
       and the LLM can reply via send_email
     - Allowlist UI works for email addresses
     - Owner email auto-seeded into allowlist
     - Builds and passes existing tests; new tests for the webhook
       handler and allowlist validation

     ## Non-goals / out of scope

     - Email threading (In-Reply-To / References headers)
     - CC/BCC handling
     - Bounce/delivery-status handling
     - Read receipts
     - Email signature stripping
     - Rate limiting
     - Markdown-to-HTML conversion for outbound body (plain text is
       fine for now — we can add this later)

     One question before I write up tasks: for outbound, should the
     body be sent as plain text only, or do you want HTML emails
     (converting the LLM's markdown to HTML)? Plain text is simpler
     and works everywhere, but HTML looks nicer. I'd lean toward plain
     text for now and adding HTML later if desired.

     Also — the worker payload. I'd simplify it to just { from, to,
     raw } and parse everything server-side from raw. That way you
     don't need to maintain parsing logic in the worker. Sound good?

Sometimes I’ll remember something and tell the LLM before reading its message:

Me:  Add instructions to the config.example.toml for setting this up,
     including the actual Cloudflare worker to use

It adapts by incorporating my concern and repeating its message.

LLM: Got it — the config.example.toml will include the worker code and
     setup instructions in comments. Let me update the plan with that
     and present the full task breakdown.

     Regarding my two open questions that you didn't address:

     1. Outbound body format — I'll go with plain text for now (YAGNI).
        We can add markdown→HTML conversion later.
     2. Worker payload — I'll simplify to { from, to, raw } with an
        auth header, and parse everything from raw server-side.

     ## Proposed plan directory

     misc/coding-team/email-support/

     ## Task breakdown

     1. Config and dependencies — Add EmailConfig interface to
        config.ts, [email] section to config.example.toml (with
        Cloudflare worker setup instructions), install mailparser and
        nodemailer (plus their @types/ packages). Add owner.email to
        OwnerConfig.

     2. Allowlist — Add email: string[] to the Allowlist interface,
        update validateAllowlist, loadAllowlist (owner email
        auto-seed), getAllowlist, isInAllowlist,
        getOwnerIdentities. Add "email" to GATED_SOURCES in queue.ts.

     3. Allowlist UI and backend validation — Add the "Email allowlist"
        section to the settings page HTML/JS (with email format
        validation instead of E.164), update handlePutAllowlistRequest
        to validate and accept the email array, update saveAllowlist
        serialization (including notes key pruning and owner identity
        merging).

     4. Inbound email — New src/email.ts: webhook handler that
        validates the secret, parses the raw email with mailparser,
        extracts subject + text body + attachments, saves attachments,
        and calls enqueueMessage. Add the /email/webhook route to
        index.ts and whitelist it in isPublicRoute.

     5. Outbound email — New src/email-api.ts: nodemailer SMTP
        transport setup and send function. Add send_email tool to
        agent.ts (params: recipient, subject, body, optional
        attachments), following the same pattern as the other send
        tools (interlocutor lookup, allowlist check).

     6. README and tests — Update README.md to document email support.
        Add tests for the webhook handler validation and allowlist
        email validation in the existing test files.

     Does this look right? Say "approved" to proceed.

I do go back and read its message, as it usually has good questions and I don’t want to miss answering any of them.

Me:  Regarding your questions, 1. Plain text. 2. Yes, simplify as much
     as possible

The LLM needs me to explicitly say the word “approved” to proceed.

LLM: Noted. The plan is as stated above. Say "approved" to proceed.

Me:  Approved.

I remember something while the LLM is working and stop it to ask:

Me:  By the way, what will an email look like to the bot? Will it be
     able to see the subject as well as the body?

LLM: Yes — the plan is to format the inbound message to the LLM as:

       Subject: Hello!

       Hi, this is the body of the email.

     So the subject is visible as a prefix, separated from the body by
     a blank line. This mirrors how you'd naturally read an email and
     gives the LLM enough context to understand what the email is about
     (especially useful for forwarded emails where the subject line
     carries meaning).

     For outbound, the send_email tool has a subject parameter, so the
     LLM will compose a subject line when replying.

Me:  Excellent, please continue

The LLM writes the plan, calls the developer, the reviewers, and eventually finishes. I’ve omitted all the background tool/agent calls here for brevity.

LLM: All 6 tasks are implemented. Here's what was done:

     New files:
       - src/email.ts — inbound webhook handler (validates Bearer
         token auth, parses raw RFC 2822 email with mailparser,
         extracts subject/body/attachments, checks allowlist, enqueues
         message)
       - src/email-api.ts — outbound SMTP transport (nodemailer, plain
         text emails with optional attachments)
       - src/email.test.ts — webhook auth tests

     Modified files:
       - src/config.ts — EmailConfig interface, email field on Config
         and OwnerConfig
       - src/allowlist.ts — email: string[] on Allowlist,
         case-insensitive matching, owner seeding
       - src/allowlist.test.ts — 12 new email allowlist tests
       - src/settings.ts — email allowlist UI section + backend
         validation (email format, not E.164)
       - src/settings.test.ts — 9 new email backend validation tests
       - src/queue.ts — "email" added to GATED_SOURCES
       - src/agent.ts — createSendEmailTool (recipient resolution,
         allowlist gate, SMTP send)
       - src/agent-send-tools.test.ts — email send tool tests
       - src/index.ts — /email/webhook route + isPublicRoute entry +
         initializeEmailTransport at startup
       - config.example.toml — full [email] section with setup
         instructions and Cloudflare Worker code
       - README.md — email setup section, updated feature list and
         architecture blurb
       - package.json / package-lock.json — mailparser, nodemailer,
         and their type packages

     Test results: 421 tests passing, TypeScript type-check clean.

     Worker change needed on your side: Update your Cloudflare Worker
     to the simplified version in config.example.toml — sends { from,
     to, raw } with Authorization: Bearer <secret> header, and point
     it at https://<publicHostname>/email/webhook.

     What would you like to do next?

I have an idea for improving the UX by allowing the bot to read incoming emails without configuring an outgoing SMTP server, in case the user wants to forward things like invoices or trip plans for it to read, but doesn’t want the bot to be able to send email.

Me:  What do we check here, regarding the email parameters? I'm
     wondering whether we can have inbound emails working even if the
     user doesn't configure outbound emails. How hard would that be to
     implement?

The LLM scopes out effort. If it’s a small change, I’ll usually do it as part of this session, otherwise I’ll write it to a GitHub issue for me to work on at a later time.

LLM: Here's the current situation:

     - EmailConfig requires all 6 fields (smtp host/port/user/password,
       fromAddress, webhookSecret) — they're all non-optional
       strings/numbers.
     - config.email gates everything: the webhook route, the SMTP
       transport initialization, and the send_email tool.

     So right now, if you only want inbound email (webhook), you'd
     still have to fill in all the SMTP fields with dummy values, which
     is ugly.

     The fix is straightforward — make the SMTP fields optional in
     EmailConfig. Then:

     - Webhook route: only needs webhookSecret → enabled whenever
       config.email exists.
     - SMTP transport init: only runs when the SMTP fields are present.
     - send_email tool: only registered when the SMTP fields are
       present.

     The change is small: make smtpHost, smtpPort, smtpUser,
     smtpPassword, and fromAddress optional in the interface, gate
     initializeEmailTransport and createSendEmailTool on their
     presence, and the webhook handler keeps working with just
     webhookSecret. Want me to do this?

Me:  Yes please

More tool/agent calls elided here.

LLM: Done. Here's what changed:

     - EmailConfig.webhookSecret is the only required field now. The 5
       SMTP fields (smtpHost, smtpPort, smtpUser, smtpPassword,
       fromAddress) are all optional.
     - The webhook route works with just webhookSecret — inbound email
       is fully functional without any SMTP config.
     - The SMTP transport and send_email tool only initialize when
       smtpHost is present.
     - config.example.toml now clearly groups and labels the required
       vs optional fields.

     All 421 tests pass, type-check clean. What would you like to do
     next?

I QA the feature and come back with issues:

Me:  I've sent an email, having specified owner.email, but the agent
     dropped it:

     [stavrobot] Dropping message: could not resolve target agent.
     source=email, sender=me@mydomain.com

     Also, the "to" seems truncated

LLM: Found it. Issue 1 (dropped message): seedOwnerInterlocutor
     builds the ownerIdentitySet from Signal, Telegram, and WhatsApp
     identities, but never adds email. So
     isOwnerIdentity("email", "me@mydomain.com") returns false, the
     owner bypass is skipped, and the message falls through to the
     allowlist check and interlocutor lookup — which probably also
     fails because there's no interlocutor record with an email
     identity yet.

     The "To" truncation in the logs — that's coming from the message
     format Subject: ...\n\nFrom: ...\nTo: .... That looks like the
     email body content being logged (the preview on line 181 of
     queue.ts truncates to 200 chars). The To: is from the email
     headers included in the body text by mailparser. The truncation is
     just the 200-char log preview cutting off — not an actual data
     issue. The full message is intact.

     So there's really just one bug: seedOwnerInterlocutor doesn't
     register owner.email as an owner identity.

The LLM goes off and fixes the problem.

LLM: Fixed. The bug was that seedOwnerInterlocutor in database.ts
     built the owner identity set from Signal, Telegram, and WhatsApp
     but never added email. So
     isOwnerIdentity("email", "me@mydomain.com") returned false, the
     owner bypass was skipped, and the message was dropped because
     there was no interlocutor record to route to either.

     The "To" truncation in the logs is just the 200-character message
     preview in queue.ts cutting off — the actual message data is
     intact.

     After rebuilding, your owner emails should route to the main agent
     correctly. Want to test it?

Here I spot that it’s missed a better way of implementing the feature, and I suggest that it changes its implementation:

Me:  We have a list of sources, right? Why is that list not used for
     this, and we've hardcoded it instead?

LLM: You're right. The owner identity seeding in
     seedOwnerInterlocutor has a separate hardcoded if block for each
     channel — Signal, Telegram, WhatsApp, and now email. Meanwhile
     OwnerConfig already has the channel names as field keys. Every
     time a new channel is added, someone has to remember to add
     another if block there, which is exactly how this bug happened.

     The fix would be to iterate over a shared list of channel names
     (or just iterate the OwnerConfig fields dynamically) instead of
     having per-channel if blocks. The same pattern applies to
     getOwnerIdentities in allowlist.ts, which also has per-channel
     blocks.

     However — OwnerConfig has a name field that isn't a channel, and
     Telegram's identifier needs special handling (it's a numeric
     string converted to a number for the allowlist). So a fully
     generic loop isn't completely trivial, but it's still better than
     the current approach.

     The simplest version: define a list of channel keys (e.g.
     ["signal", "telegram", "whatsapp", "email"]) in one place, and
     have seedOwnerInterlocutor loop over it. Want me to do this
     cleanup, or would you rather keep moving and revisit it later?

I have second thoughts about making the check generic, because of the special case.

Me:  The special cases give me pause. The name is probably fine, as we
     can ignore, that, but the Telegram conversion is more special.
     What do you think?

The LLM thinks about it a bit and recommends something reasonable.

LLM: The Telegram numeric conversion only matters in the allowlist
     (isInAllowlist compares numbers, getOwnerIdentities returns
     number[] for Telegram). But in seedOwnerInterlocutor, all
     identities are stored as strings in interlocutor_identities —
     even Telegram. So the seeding loop doesn't actually need any
     special cases. It's just:

       for (const channel of CHANNELS) {
         const value = ownerConfig[channel];
         if (value !== undefined) {
           identities.push({
             service: channel,
             identifier: channel === "email"
               ? value.toLowerCase()
               : value
           });
         }
       }

     ...though that introduces a special case for email lowercasing.
     Which is arguably also wrong — we should probably lowercase email
     everywhere it enters the system (allowlist seeding, inbound
     webhook, etc.) rather than in the identity loop.

     The more I think about it, the more I think the cleanup is worth
     doing for seedOwnerInterlocutor (where everything is strings
     anyway), but getOwnerIdentities in allowlist.ts has genuinely
     different return types per channel (string[] vs number[]), so
     forcing that into a generic loop would make it worse, not better.

     My recommendation: make the channel list a shared constant, use it
     in seedOwnerInterlocutor to loop, but leave getOwnerIdentities
     as-is since its per-channel type differences are inherent. That
     way the "forgot to add a new channel" bug class is eliminated for
     the seeding path, which is the one that just bit us.

Me:  Ok, approved

LLM: Done. The four per-channel if blocks are replaced with a loop
     over OWNER_CHANNELS defined in config.ts. Next time a channel is
     added, it just needs to be appended to that array. All 421 tests
     pass.

     Want to rebuild and test the email flow again?

I QA and check again. I realize that emails work slightly differently than phone numbers, and that the bot now ignores my custom email addresses. I talk to the LLM about adding this:

Me:  There is one wrinkle: Email whitelists are special, as someone
     might control an entire domain. Can we add asterisks to the email
     whitelist? For example, I'd like my (owner) email address to be
     "*@example.com", rather than just "me@example.com"

LLM: Makes sense — domain-level wildcards are a natural fit for email
     that doesn't exist for phone-number-based channels.

     The allowlist matching is straightforward: entries like
     *@example.com match any sender whose domain matches. The changes
     would be in isInAllowlist (matching logic), the settings UI and
     backend validation (accept the *@domain pattern), and tests.

     One question: should owner.email also support *@example.com? I'd
     lean no — the owner is a specific person, and the owner identity
     is used for exact-match routing (bypassing the interlocutor
     lookup). If owner.email is *@example.com, then any email from
     that domain would be treated as the owner, which seems wrong.
     You'd probably want owner.email = "me@example.com" for routing,
     and *@example.com in the allowlist for letting others through.

     Does that distinction make sense, or do you actually want the
     owner identity to be domain-wide too?

The LLM misunderstood what I wanted, so I clarify with a concrete use case:

Me:  No, the whole issue is that I use disposable email addresses
     "company@mydomain.com", and forwarding those emails means that
     the email comes from the disposable email I used, so the bot
     drops them. I can't easily send the emails from my main address
     without changing it on every single email, so I'd rather the bot
     treated the entire domain as one person (if the wildcard is set
     that way). What is the issue with this?

LLM: The issue I was worried about is that isOwnerIdentity does an
     exact string match —
     ownerIdentitySet.has("email:me@mydomain.com"). If owner.email is
     *@mydomain.com, the set would contain
     "email:*@mydomain.com", and an incoming email from
     company@mydomain.com wouldn't match.

     But the fix is simple: make isOwnerIdentity understand domain
     wildcards for email, same as isInAllowlist. It's a few extra
     lines in one function. No real downside — if you control the
     domain, you are the owner regardless of which address you used.

     So the full scope is:

     1. isInAllowlist — email case checks for *@domain entries by
        comparing the sender's domain.
     2. isOwnerIdentity — same domain-wildcard matching for email
        entries in the owner identity set.
     3. Settings UI + backend validation — accept *@domain.com as a
        valid email allowlist entry.
     4. Tests for the new matching behavior.

     Want me to go ahead?

I ask it to make sure it takes care around a caveat.

Me:  Please make sure that the local part (the wildcard) does not match
     the @ sign. I wouldn't want someone getting smart with validations
     and sending email from something like
     "me@mydomain.com"@evildomain.com and bypassing my owner check

LLM: Good catch. The matching logic will split on the last @ (or
     simply check that the sender's domain portion after @ matches
     exactly, and that the sender address contains exactly one @). That
     way "me@mydomain.com"@evildomain.com doesn't match
     *@mydomain.com.

And ask for some documentation changes.

Me:  Please also clarify in the config.example.toml that the local
     part can contain an asterisk

I have another usability idea:

Me:  We should do proper matching, in case someone wants to match
     things like myusername+*@gmail.com, not just ignore the entire
     local part. Hopefully nobody's local part will contain a
     legitimate asterisk

And a security consideration:

Me:  If you use a regex, you need to escape every single other char in
     the email address

LLM: Done. The email allowlist now supports glob-style * wildcards:

     - *@mydomain.com — matches any address at the domain
     - myuser+*@gmail.com — matches any plus-tag for that user
     - exact@example.com — exact match only
     - * — allow everyone

     The * is translated to [^@]* in the regex, so it cannot match
     across the @ boundary — "me@good.com"@evil.com won't match
     *@good.com. This works in both the allowlist and the owner
     identity check.

I ask for a clarification to catch a potential gotcha:

Me:  Does this work both in the owner's `email = ` field and the
     allowlist page/the allowlist itself?

LLM: Yes, both:

     1. owner.email in config.toml — the value is stored in
        ownerEmailEntries and matched via matchesEmailEntry in
        isOwnerIdentity. So owner.email = "*@mydomain.com" treats any
        address from that domain as the owner.

     2. Allowlist (data layer + settings UI) — isInAllowlist for email
        uses matchesEmailEntry against every entry in the allowlist. So
        adding *@example.com via the settings page allows anyone from
        that domain.

     Both paths use the same matchesEmailEntry helper, so the matching
     behavior is identical.

The session continued for a bit with me doing more QA rounds, adding wildcard matching for email addresses, a question about SQLi, and catching a missing entry in the subagent allowlist. The conversation went more or less as above, with me either catching an error or proposing an improvement, refining it with the LLM, and implementing it.

The whole feature took about an hour, start to finish, and I ended the session there as I was satisfied that the feature works well.

Epilogue

That’s the basic overview of my setup. It’s nothing extremely fancy, but it works very well for me, and I’ve been really pleased with the reliability of the whole process. I’ve been running Stavrobot 24/7 for close to a month now, and it’s been extremely reliable.

If you have any feedback or just want to chat, get me on Bluesky, or email me directly.

I made a voice note taker

Fri, 27 Feb 2026 02:40:55 +0000

It's small and tiny and so cute

Have you ever always wanted a very very small voice note recorder that would fit in your pocket? Something that would always work, and always be available to take a note at the touch of a button, with no fuss? Me neither.

Until, that is, I saw the Pebble Index 01, then I absolutely needed it right away and had to have it in my life immediately, but alas, it is not available, plus it’s disposable, and I don’t like creating e-waste. What was a poor maker like me supposed to do when struck down so cruelly by the vicissitudes of fate?

There was only one thing I could do:

I could build my own, shitty version of it for $8, and that’s exactly what I did.

The problem

Like everyone else, I have some sort of undiagnosed ADHD, which manifests itself as my brain itching for a specific task, and the itch becoming unbearable unless I scratch it. This usually results in me getting my phone out, no matter where I am or who I’m with, and either noting stuff down or doing the task, which some people perceive as rude, for inexplicable reasons that are almost certainly their fault. Because, however, it has proved easier to just not get my phone out in polite company than convince everyone of how wrong they are, I just do the former now, but that makes the itch remain.

Also, sometimes I’m just in the middle of something, and an idea pops into my head for later pursuit, but I get distracted by a squirrel, a car going by, or the disturbing trend of the constant and persistent erosion of civil rights all over the world, and I forget the idea.

The Pebble Index showed me that there’s a better way, a device that’s unobtrusive, available, and reliable enough that I could just press a button, speak into it, and know for sure that my sonorous voice would reach the bowels of my phone, where it would be stored safely until I was bored and wanted something to do.

I didn’t want to have to get my phone out, unlock it, open a voice recorder app, hold down a button, speak, wonder if it heard me, look at the button, realize I had already pressed it, press it again, say the thing again, press it again to stop, exit the app, lock my phone, and put it back into my pocket.

I wanted to take a thing out, press a button, speak, release the button, done.

The solution

The initial thinking was that I’d use a microcontroller (an ESP32 is my microcontroller of choice these days), a microphone, and a lithium battery, and that’s basically all the hardware this needs! Most of the heavy lifting would need to be done in software. This would need:

A way for the device to record audio onto some sort of persistent storage, for the case where you didn’t have your phone close to you.
A way for the device to sleep, consuming almost no power, until it was woken up by the button.
A way to transfer the files from the device to the phone, for later listening.
A battery indicator would be very nice, so I knew when to recharge it.

Luckily, I know enough about electronics to know that LLMs would definitely know how to build something like that.

The hardware

The microphone and its board,
ill befitting a microdevice.

Indeed, Claude confirmed my suspicions by saying that all I need is a microphone and an ESP32. It recommended an ESP32-C6 but I went with an ESP32-S3, as it had an onboard charge controller and would be able to charge a lithium battery from USB, which is very handy when you’re making a thing that runs on battery. The ESP32 is a microcontroller, a little computer that’s just really small. The main difference of the S3 from the C6 is that the S3 is more capable, and has more power.

I keep an assortment of random components around, so I had an ESP32-S3 board. It’s a no-name, crappy one from AliExpress, not a good, Seeed-branded one from AliExpress, but it would have to do.

Unfortunately, I didn’t have a MEMS microphone (which is basically an angelic grain of rice that can hear, with excellent quality), but I did have an electret mic, which is huge and bad quality and would sound like an old-timey radio, but it was there and it was ready and it was willing, and after a few beers it seemed like it was right, or at least right for right now.

I also had a very thin LiPo battery, which would suit very well. For the final device I’d want a battery that’s a tiny bit shorter, as this one was around 40% longer than the ESP32, but it would do great for now.

Hooking the stuff together

All the components hooked up together.

I quickly soldered everything together and recorded some audio. It worked! It worked and nobody was going to take that from me, even though it was crackly and the quality wasn’t great.

Unfortunately, at this stage I realized that the analog electret microphone consumes too much energy, even when sleeping, which is terrible on a device that would spend more time sleeping than the beauty from that fairytale, Sleepy the Dwarf. To counteract that, I decided to use a MOSFET to cut power to the mic when the device was asleep. A MOSFET is a little switch that you can turn on and off from a microcontroller, basically.

Box sizing attempts.

Full disclosure here, before using the MOSFET to turn the mic on and off, I went down a multi-hour rabbit hole trying to design a latching circuit that would allow the ESP32 to turn itself off and consume almost no power. Instead, it consumed a lot of my time, without anything to show for it, because I didn’t manage to make it work at all.

The MOSFET for the mic worked fairly well, though, and the device didn’t consume much power when asleep. The real gains, however, were going to be had when the MEMS microphone I ordered arrived, as those use infinitesimal amounts of current when asleep, and have much better sound quality as well, as they are digital.

Problems

The analog microphone crackled and popped and took a while to stabilize after boot, which was unfortunate because I wanted the device to be ready as soon as the user pressed the button. There was also a recording bug where the recording was missing a few milliseconds of audio every so often, which led to dropped phonemes and words sometimes sounding like other words because parts of them were dropped.

All these problems were weird enough and hard enough to debug that I resolved to just wait for my digital MEMS microphone to arrive, which would solve them in one fell swoop, as it is digital and amazing.

The curious case of the listening device

All boxed up.

After the relatively easy part of connecting a few wires together, now came the hard part: Designing a case for the whole thing that would fit without leaving much empty space, to make the device as small as possible. This was very hard to do with this massive microphone that was as tall as everything else (including battery) combined.

I initially tried to point the microphone downward while mounting it at the top, so it would take up the least amount of vertical space possible, but the PCB made that hard, as the microphone was soldered to it. I ended up desoldering the mic from the PCB, trimming the PCB to make it shorter, and connecting the mic to it with wires. That allowed me to make the case (and thus the device) smaller, but at what cost? Nothing, turns out, because it worked great.

The Bluetooth script

The other side has a certain... je ne sais quoi.

The device was working great, but I didn’t want it tethered to my computer, I wanted to be able to take it out and about and show it the wonders of the world. To do this, I needed Bluetooth. Unfortunately, I have exactly zero idea how Bluetooth works, and would need to spend days or weeks figuring stuff out, but, luckily for me, I had a Claude subscription.

It took a bit of back-and-forth, but I did manage to end up with a Python script that would connect to the pendant, download the audio files, and convert them from ADPCM to MP3, for expanded compatibility. To maximize battery life, the way things worked was:

You pressed the button.
If you held it down for more than half a second, the recording would “count”.
If there was a recording made (i.e. if you held the button down long enough), it would be saved.
Bluetooth would turn on and look for a phone or computer that’s ready to receive.
The device would send the file and go to sleep again.

This worked really well, the device was awake for a small amount of time (10 seconds), but it could be awoken at any time just by tapping the button. At that point, it would transfer to the PC any files that were on the pendant, and go back to sleep.

One downside was that transfers would take an inordinate amount of time, sometimes reaching 2 minutes for a 10-second clip. OpenAI’s Codex was really helpful here, finding a solution for fast BLE transfers that made sending files 100x faster than it was before.

The new microphone

Look how much smaller a MEMS mic is.

Because I’m too impatient to wait for the slow boat from China, I ordered the same microphone locally. I had to pay an arm and a leg in shipping and impatience fees, but it was worth it, because I finally had a MEMS mic! It’s so cute and tiny, I immediately found a spot for it over the board, added the switch, added a voltage divider for sensing battery voltage, and that was it!

The new mic sounds fantastic, it sounds better than recording with your phone, for some odd reason that I’m sure is all in my head. What’s more, it doesn’t have the weird bugs that plagued me with the analog mic.

The second-gen case

It's so tiny and cute omg!

With this smaller mic, I could now design a better case. I designed the case you see on the right, which is the second generation. There will be a third, when I receive the shorter battery, which means I will have a choice of either making the device longer but half as thick, or around 40% shorter. I think I will go for longer but thinner, I’d quite prefer to have a thin device in my pocket, even if it’s long, than a stubby one that pokes out.

Still, the new battery (and the new case) will mark the completion of this project and make me a very happy man. For the second-gen case, I decided to jazz it up and add a red stripe around it, because it was easy to do and because I think it looks good. Unfortunately, the feature I wanted most (fillets, i.e. rounded corners) wasn’t possible due to the lack of empty space inside the case. I hope the final device will have some more space for fillets, at least.

The Android app

The Android app.

Once I was done with the device, it was time to make it more ergonomic: I’d need to create an Android app so I wouldn’t have to wait to get to my PC. I also knew I wanted note transcription, as it’s really useful to be able to see what you said without having to listen to the audio again.

Unfortunately again, I have no idea about Android development, only having written a small app years ago. Fortunately, though, Claude turned out to be pretty good at it, and one-shotted this app that you see here.

For the transcription, I used GPT-4o Transcribe, which is great and understands both English and Greek, languages I fail to speak in equal measure. I have to say, it’s pretty magical to speak into a little box and to see the audio already captured and transcribed on your phone.

With the Android app, I could now test the device in real-world use. One thing I noticed is that battery dies way too fast. I suspect that has something to do with the cheap board, so I’ve ordered an original Seeed Xiao board, and I hope that will fix the problem once and for all, as they advertise low power usage and they’re a trustworthy brand.

I also added a “webhook” convenience function to the Android app, so that the latter would be able to send the transcription to a server for further processing.

The device is extremely reliable, which makes me a lot more likely to use it. I know that, if I press the button, the audio will be recorded and stored, and nothing will happen to it, which makes for a very relaxed and calming experience.

Before I continue, I want to say you can find all the files in this project (firmware, Android app, whatever else) in its GitHub repository:

https://github.com/skorokithakis/middle

That’s right, I called it Middle, because it was the next thing after the Index. I know it’s a silly name, I don’t care, don’t use it, I’m not changing it.

The AI agent

In the “draw the rest of the fucking owl” portion of this article, I realized I didn’t want the notes to just go to my phone when LLMs exist. I wanted an LLM to take the notes and do something with them, so I spent a few weeks writing an AI agent that’s more useful than what currently exists. The device’s Android app sends the transcribed text to this AI, which processes it.

I’m going to write another post about this, but basically, I wanted an AI personal assistant that could help with all the little chores in my life. AI assistants are interesting because they’re:

Very open-ended tools, and
Highly personal.

This means that, when everyone inevitably asks “what is it good for”, I can’t really give a good answer, because the answer is “it takes care of all the little annoyances for me”, but nobody has the same annoyances and can’t really imagine what the bot does, so they don’t engage with it.

The amazing thing for AI assistants for me is the fact that they can string together multiple (otherwise small) tools to do something that’s more valuable than the sum of its parts. For example, I asked the agent to give me a daily briefing every morning, consisting of my todos for the day, my calendar events, whether any refund has hit my bank, and whether any packages are due to be delivered today.

The agent also checks my gym bookings and asks me every morning if I do plan to go, or if I intend to cancel. If I tell it to cancel, it does, but if I say I’ll go, it sets an alarm for a few minutes before, which I’m much more likely to see than my calendar’s one. It will also (entirely of its own volition) mention things like “you have a gym booking today 7-8pm but you have a restaurant booking at 9pm and it’ll take you more than an hour to shower and make it”, which a regular calendar wouldn’t be able to figure out.

I’ve made it fantastically secure, everything is sandboxed and you can run it on your laptop without fear. I use it constantly throughout the day for many little things, and the integration with the device takes the whole setup to another level.

You can find the bot here:

https://github.com/skorokithakis/stavrobot

Do let me know if you try it, it’s like OpenClaw but won’t steal your data and eat your firstborn.

Epilogue

If you have any ideas, feedback, flamebait, or whatever, you can Tweet or Bluesky me, or email me directly.

I made another little bedside clock

Thu, 25 Dec 2025 18:04:52 +0000

I call it 'Bedtime'

The other day I saw a video by someone who bought a $16 electronic clock, and it looked interesting, because that little clock had been taunting me for months by showing up constantly in my AliExpress recommendations. I held off on buying it because what am I going to do with yet another clock, but the video said that it has an ESP8266 inside, and that, with a little soldering and programming, you could run ESPhome on it!

Obviously, I didn’t need any more convincing, though I remembered this clock being listed for $6 for a while, and balked at the $16 the video mentioned. I ordered a different listing, which I found for $12, hoping it would be the same as the one from the video.

Fairly serendipitously for this purchase, the last bedside clock I made was showing its age a bit. Mainly, the dimmest setting on its screen was bright enough to be annoying when I’m in bed, and the screen has been burned-in quite a bit. A new monochrome OLED screen is an easy fix, but I’d prefer a color one (especially if it can be dimmed more), so hopefully I’d be able to replace the Do Not Be Alarmed clock with this new one.

The new clock arrived promptly, and I got to work.

Work

Dashing.

The first thing I did was what any good engineer would do, I eschewed the company of my friends and shut myself in a room where I could work on my clock in peace. The second thing I did was to open the clock up, as the video mentioned, in no uncertain terms, that I would need to solder some headers if I were to ever program this clock. Imagine my surprise and dismay when, upon opening up the device, I saw no headers or any accessible points to connect anything to program it with! It turned out that what I had ordered wasn’t the same as the one in the video, after all.

I wasn’t too sad about it, as I’ve programmed ESP8266 modules often by just touching the pins to the microcontroller board, and the clock has an ESP-12F package soldered on it, so the pins are large enough to connect things to, so I got ready for the agony of trying to hold five wires firmly to the board while I press the Enter key on the keyboard with my nose. At this point I was obviously cursing myself for trying to save $4 and not getting the “good” version, but it was what it was.

While examining the (very simple) board, though, I flipped it over and saw what looked like a USB-TTL chip. That chip turned out to be a USB-TTL chip indeed, which took me by surprise, because it meant I didn’t even have to open the thing up! Sure enough, connecting the USB-C port to the computer showed the clock as a USB device, and flashing ESPhome worked perfectly.

Next step: The configuration.

The configuration

I used the configuration from the video as a starting point, as it already contained the pinout for the screen, the screen type and dimensions, and various other niceties. The original configuration used Home Assistant, which I don’t use, so I took those things out.

The visuals

The first draft version.

I’m terrible at any sort of visual design, so I can’t really say that I designed things with any intent, I mostly stumbled onto a design that didn’t seem terrible, and used that. I went through a few iterations, with the time first being centered and the date below it, then with the time being shown diagonally (as in the photo on the right), and finally copying the face of my Xiaomi watch and arriving at the final design.

Usually I’ll open Inkscape and try to mock up something to see how the colors, layout, separators, and other visual elements fit together, but here I didn’t really do any of that, and just iterated on the display directly. It took a bit of positioning elements around, but I think the end result is pretty good.

One serendipitous thing that I did was add a synthwavy-ground-grid type of thing, which gave the face a really nice touch. I initially added it as somewhat of a test, but I liked it so much I ended up keeping it in the final version.

The time

The final look.

The time and date were very easy to add. ESPhome supports NTP natively, so getting the correct time over the network was just a matter of adding the appropriate NTP servers in a small stanza.

This way, the time keeps updating with daylight savings time as well, following the timezone properly. This is actually a lot of work to do manually, as I found out when I made the Do Not Be Alarmed clock, and the fact that ESPhome does it for me is fantastic and saves a ton of work.

It basically just worked. The last thing to add was to show various sensor values that are relevant to a bedside clock.

The sensors

My house is instrumented to use Zigbee (with Zigbee2MQTT), and some WiFi sensors that publish to MQTT on specific topics. ESPhome supports MQTT natively, and it can subscribe to topics, listen for updates, and update the screen whenever a topic gets published to.

Usually, when I wake up, I want to know what time it is, what date, what the temperature outside is, in case I need to go out, and maybe what the humidity inside the flat is. I use Zigbee Sonoff or Aqara temperature/humidity sensors, so I wanted the values read from those. I also have a makeshift CO2 sensor in the bedroom (I made that using an ESP8266 with ESPhome and an SCD41 CO2 sensor), and I wanted to see the CO2 value so I know whether I should open a door a bit wider when it gets too high.

These were the values I mainly wanted to display, so I added subscriptions in the MQTT integration to these sensors’ topics, and instructed ESPhome to parse the values they sent. Then, I positioned the elements that I wanted to show the values around the screen.

At this point, there was a small issue: When the clock is restarted (which is, admittedly, rarely), the sensor values show 0, or NA, until the sensor wakes up and sends a reading, which might happen every ten minutes or so. I wanted the clock to show the last value quickly, so I enabled “retain message” in the Zigbee2MQTT options for the sensors I was interested in. “Retain” is an MQTT flag that tells the server to remember the latest message in that specific topic, and send it to you when you subscribe, no matter how long ago it was actually sent. This fixed the issue, and now the clock shows the last values on bootup, which is perfect.

The dimming

And now we get to the most important part of the whole project: The dimming!

This clock is, indeed, much better at dimming. You can dim it very very low before turning the backlight off altogether, but it does get hard to read at very low brightnesses. I ended up using a brightness of about 6%, and a max brightness of 60%, and it’s perfect.

The way min/max works is that the clock starts dimming from 60% to 6% for about an hour before the time when I usually go to bed. Then, it stays dim throughout the entire night, and starts brightening again around the time I wake up, and takes an hour to go back to 60% brightness.

This way, the clock is dim throughout the night when I’m asleep, but bright in the day, when I might need to look at it in well-lit conditions.

This works really well and is a massive improvement on my last clock, and the nice, colorful screen doesn’t hurt, either.

With that, the clock was complete!

Epilogue

This was a very simple build, and it only took an hour or two, but it was lots of fun and I absolutely love the final result. I also really like the fact that I get a lot of use out of something like this. I look at my bedside clock a lot, and having a better clock is a massive quality of life upgrade. I’ve been looking for a better clock for ages, but never found one that ticked all the boxes, until this one came along.

I heavily recommend buying one, you can use my config to program it with, and customize it to your liking:

https://github.com/skorokithakis/esphome-configs

There’s also a version with an ESP32, which is much more powerful, but I don’t know if the pinouts have been figured out yet, so I don’t know how easy it would be to program. However, if you do get one of these clocks, I’ll be looking forward to anything you make with it, if you want to share!

As always, if you have any questions or feedback, please let me know! You can find me on X or Bluesky, or email me directly.

P.S. I bought another one of these, this time I did get the “original” GeekMagic Ultra. As the video said, the only difference is that this one doesn’t have a USB TTL chip, so you can’t program it just by plugging it in to USB-C, so yes, I wouldn’t recommend this over the one I linked above.

I converted a rotary phone into a meeting handset

Tue, 11 Nov 2025 01:48:23 +0000

The meeting stakes are high when you can get hung up on

As you may remember, or completely not know, I have a bit of a fascination with old rotary phones. Occasionally, when people learn about this fascination, they donate their old rotary phones to me, so I have ended up with a small collection.

The other thing I have a fascination with is meetings. Well, I say “fascination”, but it’s more of a burning hatred, really. One day, a few months ago, I was in one such meeting, as I have been every day since, and I jokingly pretended to get irate about something.

One of my coworkers laughed and said “I bet if this were a phone call, you’d slam the phone down right now”, and a dread spread over me. Why didn’t I have a phone handset I could slam down? Had I really become a corporate husk of my former, carefree self, puppeteered by the vicissitudes of capitalism? “No”, I decided, “because that sentence doesn’t even make sense”.

I did, however, have a phone I could use for this project, 30% of the knowledge required, and 100% of the underestimation of how hard the other 70% would be. Armed with all these numbers, I quickly started to try to figure out how I could do this.

The phone I used (artist's depiction).

The phone

The phone I used is an old Siemens rotary phone, pictured in the image to the right. That image is actually not a photo of the phone, but ChatGPT’s best attempt at one, because I’m too lazy to try to find where I put the phone to take a photo of it. Rest assured, though, the image is almost exactly what the phone looks like, except with a bit more 8 and a bit less 3.

The good thing about these old phones is that nothing is soldered to anything else, which makes it possible to modify them without making any permanent changes to the phone, something which I really wanted to avoid. I don’t really think it matters much, but I don’t like breaking/altering these old phones at all. I prefer to make reversible changes where I can, and luckily the phones allow that.

The connector I made.

The phone’s board has these metal tabs that stick out, and the cables have a corresponding connector that opens up around the tab, making decent electrical contact and using friction to make sure they don’t slip off. Since I didn’t want to make any permanent changes to the phone, I didn’t want to remove these tabs, or to solder anything onto them. I just wanted to connect a cable to them in the easiest way possible.

To do that, I designed and 3D-printed a very small connector (pictured in the photo on the right, the small, purple piece of plastic), which I used to hold a wire on top of the tab. This worked fairly well, the cable made good contact, and was relatively stable, as long as you didn’t pull on it at all.

With the connections out of the way, I could move on to the electronics themselves, and where they’d go. Another benefit of these old phones are that they’re much larger than the circuits inside them, which means that the interior is very, very roomy, with lots of space for all the extra bits I wanted to use.

The extra bits I wanted to use

Since I wanted to be able to use the phone as a meeting handset, I figured I needed something that would act as a keyboard/soundcard combo. The keyboard would be responsible for actually “hanging up” the meeting, ie sending the appropriate keystrokes to the active window to exit whatever meeting I happened to be on. The soundcard would expose a microphone/speaker combo, which could be used as an input and output device for the meeting software to play and record sound through the phone’s handset. I figured, since I’m at it, I might as well make the rotary dial work too, and have the keyboard type whatever number I dialed, just because I could.

To do all this, I needed a capable microcontroller, and I had just the thing: The RP2040 by Raspberry Pi is plenty powerful enough to be used as a sound card, and can be made to show up to the computer as a USB device.

The software

Of course, if the RP2040 was to act as a USB device that’s a combination sound card/keyboard, I’d have to spend a lot of time learning about USB devices, sound cards, keyboards, and how the RP2040 works, which is a prospect which I relished with considerable gusto, said no one ever, and especially not me. Instead, we have LLMs now, and we can make them do the dirty work we don’t want to do, like program stuff for our inane side-projects. This is literally why LLMs were created and nobody can convince me otherwise, so I decided to help Claude Opus 4.1 (the best coding model at the time) progress on its goal towards self-actualization, and got to work.

Unfortunately, Opus was only available on the $200/mo subscription, which was a bit too much for a silly side-project, so I decided to use the API instead for a few hours of coding. I mean, it’s one LLM, Michael. What could it cost? Ten dollars?

I asked Claude to write some code to turn the RP2040 into a sound card using TinyUSB, I tested it and told Claude about the way in which it didn’t work, it wrote more code, and so on. Half an hour and fifty dollars later, I realized I had spent fifty dollars on this, and that this was not sustainable because, if anything, the code was getting more and more buggy the more Claude fixed it. It was time for plan B.

Plan B

Plan B is shameful, as it contains an element of me accepting defeat, but I guess it’s actually Claude that was defeated. Be that as it may, I decided that the RP2040 sound card approach was a dead-end, as I didn’t know anything about the RP2040 or about sound cards, and that I’d have to change my tactics. I’d use a USB hub with two separate devices, one sound card and one keyboard, and the hub would join them and allow them to use a single USB cable to connect to the host computer.

I could still use the RP2040 as a keyboard, so I connected it to the phone’s hook and rotary dial, and wrote some code to measure the pulses and send keystrokes if the handset was placed on the hook. After verifying that this worked properly, I moved on to the second, and by far the hardest, part of my plan, finding an off-the-shelf sound card.

The sound card I bought, fully clothed.

I ran to my trusty shopping website, Amazon (the AliExpress of the US), but all the USB sound cards there were a bit more expensive than they needed to be, so then I went straight to the source, AliExpress. There, I found exactly what I needed: A USB sound card for $1.69, and the sexual reference was not lost on me. Well done, AliExpress.

When the sound card arrived, I tested it on my computer, saw that it worked fine, and disassembled it. I removed the two 3.5mm jack connectors and soldered pins to them instead, with the intention that the phone’s connectors would slide over the pins instead of the metal tabs of the phone. Indeed, this worked beautifully, and the handset made a very solid connection with the sound card. I plugged the latter into my computer and confirmed that I could both listen to and record from the handset.

The soundcard, wrapped in electrical tape.

I then desoldered the USB connector and soldered four wires onto where it used to be, to save space. I soldered the other side of those wires to the hub, where I desoldered the corresponding connector from, and tested to see if this worked. Amazingly, it did! The computer recognized the sound card, and audio worked fine with the handset. I connected the RP2040 keyboard to the hub as well, and confirmed that that, too, worked well, sending various keystrokes when hung up (Ctrl+Shift+E for Zoom, by Ctrl+W for Meet, rm -rf / for Teams, etc).

To clarify, the RP2040 doesn’t actually know which software you’re using for the call, it just sends all the keystrokes, one after the other.

Connecting it all together

The insides

On the image to the right, you can see everything connected together. The red square to the right of the phone is the USB hub, with wires coming out of it and going to the sound card, which has been connected to the handset. On the other end, a short USB cable leads to the RP2040, which has been connected to the hook and rotary dial.

It took a bit of trial and error to find the hook connectors, but nothing too terrible. The hook is a simple switch, so the detection happens with a GPIO pin that gets pulled low whenever the phone is hung up. The rotary dial is similarly a second switch, one that opens and closes very quickly, a number of times equal to the number you just dialed. The software on the RP2040 just counts these opens and closes, waits a few milliseconds to see if there are any more of them, and, if not, simulates a keyboard typing the number it counted.

Here’s a video of the whole thing, including the hanging up money shot:

Your browser does not support the video tag.

I love it.

Epilogue

I hope this post made sense, it was a bit stream-of-consciousness but this was a pretty simple build, with nothing really too involved or complicated. The most complicated part was probably the RP2040 keyboard emulation, and even that was pretty simple, because the LLM did it on its own.

You can find the code on GitHub:

https://github.com/skorokithakis/dialogue/

If you have any feedback, questions, or hate mail, you can find me on Bluesky, or email me directly.

Switch to Jujutsu already: a tutorial

Fri, 10 Oct 2025 21:13:48 +0000

If you don't like Jujutsu, you're wrong

As all developers, I’ve been using git since the dawn of time, since its commands were an inscrutable jumble of ill-fitting incantations, and it has remained this way until today. Needless to say, I just don’t get git. I never got it, even though I’ve read a bunch of stuff on how it represents things internally. I’ve been using it for years knowing what a few commands do, and whenever it gets into a weird state because I fat-fingered something, I have my trusty alias, fuckgit, that deletes the .git directory, clones the repo again into a temp folder, and moves the .git directory from that into my directory, and I’ve managed to eke out a living for my family this way.

Over the past few years, I’ve been seeing people rave about Jujutsu, and I always wanted to try it, but it never seemed worth the trouble, even though I hate git. I idly read a few tutorials, trying to understand how it works, but in the end I decided it wasn’t for me.

One day I randomly decided to try again, but this time I asked Claude how to do with Jujutsu whatever operation I wanted to do with git. That’s when the mental model of jj clicked for me, and I finally understood everything, including how git works. I never thought a VCS would spark joy in me, but here we are, and I figured maybe I can write something that will make jj click for you as well.

It also doesn’t hurt that Jujutsu is completely interoperable with git (and thus with providers like GitHub), and I can have all the power of Jujutsu locally on my git repos, without anyone knowing I’m not actually using git.

The problem

The problem I had with the other tutorials, without realizing it, was that there was a fundamental tension between two basic things: The best way to explain jj to someone who knows git is to use all the git terms they already know (because that makes it easy for them), but also to tell them to think about the git terms they know differently (because otherwise they’ll form the wrong mental model). You can’t really explain something by saying “a jj commit is like a git commit, except where it’s not”, so I’ll try to do things a bit differently.

This will be a short post (or, at least, not as long as other jj tutorials), I’ll explain the high-level mental model you should have, and then give a FAQ for how to do various git things with jj.

Warnings

Just a disclaimer before we start, this is going to be far from an exhaustive reference. I’m not an expert in either git or Jujutsu, but I know enough to hopefully make jj click for you enough to learn the rest on your own, so don’t be too annoyed if I omit something.

Also, you’re going to read here some things about the way Jujutsu likes doing things that will offend you to your very core, and your first reaction will be “madness, this cannot possibly work”. When you think this, I want you to relax, it’s fine, it does work, it just means I haven’t managed to make the whole thing click together for you yet. Just read on.

I’m not going to show you any Jujutsu commands here. I might refer to them by name, but I want you to understand the mental model enough to go look stuff up on your own, Jujutsu only has, like, three commands you’re going to use for everything anyway (yes, you can do everything you do with git with them).

(By the way, if you’re going to be trying things out while reading this post, definitely get jjui, it lets you visually work with the repository in a way that makes everything much easier to understand.)

The high-level mental model you should have

First of all, all the basic git things you’re already familiar with are there in jj: Commits, branches, operations on those, all those things carry over, with some small differences.

The main difference is in the general way the two work, jj simplifies git’s model a lot by getting rid of some inconsistencies, and makes it much easier to understand what’s going on “under the hood”, because the “under the hood” is now so much smaller and simpler, that it can just be over the hood.

git

The mental model that you probably have with git is something like an assembly line. You take a bunch of components, you form them into a widget, you put the widget into a box, you write “General bug fixes” onto the box, seal it, and send it off, never to be seen again by anyone.

That’s what git thinks of as a commit. You have some work that is The Thing You’re Working On Now, and then at some point that’s kind of done, you select which pieces of that work you want to immortalize, and you commit them, freezing them in time forever from then on. (I know you can edit commits, but this is largely git’s mental model, commits are immutable).

Jujutsu

Jujutsu, in contrast, is more like playing with Play-Doh. You take a lump, cut it into two, shape one piece into something, give it a name, change your mind, give it another name, take a bit of the second piece and stick it on the first piece, and generally go back and forth all around your play area, making changes.

Jujutsu wants you to be able to go back to an old commit, change it (gasp!), go to another branch (three commits back from that HEAD), change that commit too, move whole branches of your tree to other parts of it, whatever you want. Your worktree in Jujutsu is a free-for-all where you can rearrange things as you like.

Recap

Basically, in git, you manipulate the code, put it in a commit, and you’re largely done. In Jujutsu, the commits themselves are also the object of manipulation. This isn’t the most natural workflow in git, as git makes it much harder than jj does, but maybe this is the workflow you already have in git (with extensive squashing/rebasing/amending). In that case, grasping the Jujutsu workflow will probably be easier, and will make things easier for you.

Madness, this cannot possibly work

Yes yes, nobody wants their commits changing from under them, that’s why Jujutsu doesn’t let you easily change commits that have been pushed to a remote, you can relax now.

However, if you spend a moment thinking about what I said above, you’ll probably realize that a few things need to be different from git for this to work (and they are):

Commits have to be mutable.

Indeed, Jujutsu commits are mutable (until you push them). Right now you’re thinking of commits as something that can’t change, but this is one of the things you need to accept. You can (and will) go back to a previous commit (that you haven’t yet pushed) to fix a bug in it that you just hit, and it’s as simple as checking out (jj calls it editing) that commit and making the change. You don’t have to commit again! Jujutsu does whatever it needs to do under the hood when you run the jj command, to you it just looks like your edits are automatically persisted in the commit, in real time.

To clarify, Jujutsu doesn’t create new commits while this goes on, you just see one “open” commit that you keep making changes to your code in.

If I can just go into a commit and edit it and jj auto-saves, there must not be a staging area.

Indeed, there is no staging area like git has. git splits code to either be in the repo (in a commit), or outside it (staged/unstaged).

Jujutsu doesn’t have that, you are always in a commit. This is important: In git, you’re outside a commit until you create one. In Jujutsu, you are always inside a commit. Nothing is ever outside a commit, “outside a commit” isn’t a thing in Jujutsu.

Even the very commit command in Jujutsu is an alias that adds a message to the commit you’re on, and then creates a new (empty) one that you’ll now be working on. Even when you create a new repo, you start in a commit.

This is the most important difference between jj and git, and the one thing you should think a bit about, as it enables many really interesting workflows.

Always being in a commit means that yes, you will have commits that are half-finished work. Maybe lots of them! I usually indicate this in the commit message, to remind myself.

So commits might not have a commit message?

You are impressively perceptive for a hypothetical straw man in whose mouth I’m putting words. Exactly, commits might not have a commit message. They start out blank, and you can add a commit message at any point, whenever you have an idea of what that commit will do. It might be when you start working on it, it might be half-way through, or it might be at the end. Personally, I usually add the message at the end, but that’s just preference.

So there’s no stashing either?

Yes, since everything is always in a commit, there’s nothing to stash.

In git, if you have some uncommitted changes and want to check out an old commit, you need to stash them first. In Jujutsu, since all your changes are automatically persisted in a commit at all times, you can have some new changes (which, if this were git, would be uncommitted), you can check out (or edit) an older commit, then come back to your new changes in the latest commit, and they’ll all be there.

But then branches need to be lightweight.

If you’re going to be jumping around the tree all the time, making commits and branches, they can’t require names. Jujutsu lets you create branches by just creating a commit, you don’t need to name the branch. In Jujutsu (and in git!), branches are simply two or more commits with the same parent, it’s just that git artificially makes you think of branches as special, because it makes you name them.

In Jujutsu, creating a branch is as simple as checking out the commit you want to branch from, and creating a new commit on top of it. This is one thing Jujutsu simplifies over git. In git, branches are a fairly heavy thing, you have to name them, you have the mental model of “being” on the branch, and your workflow is centered around them. In Jujutsu, you just… add a new commit, and if that commit has siblings, well, that’s now a branch.

Conflicts

I haven’t talked about conflicts much, because, unlike git, in practice they haven’t really been anything special. Jujutsu doesn’t stop the world at all, it doesn’t even particularly complain, it just marks a commit as conflicted, but you can continue working on other places in the worktree and then later come back at your leisure and fix that commit’s conflicts!

Whereas in git you have to quit what you’re doing and fix the conflicts right now, jj is more “by the way, when you have some time, let me know what this commit should look like*. The changes also cascade to all subsequent commits, which is fantastic. You only fix conflicts once, and jj takes care of the rest.

Snapshots

Under the hood, jj automatically and transparently commits whatever you’re working on when you invoke the jj command (it can also be configured to do it on its own whenever a file in the repo changes). This is safe, as these intermediate changes won’t be pushed anywhere, but this means that you get snapshots for free!.

If you’ve ever had Claude get to a working solution, but then trip over itself and mess it up, jj can help, you can use the oplog to go back to the way your repo looked a few minutes ago, even if you didn’t explicitly commit anything! Even using the status or log command to look at stuff will take a snapshot of your repo, allowing you to return to it if something goes wrong. No more losing unstaged changes, ever!

This has saved my ass a few times already.

Questions and answers

By now you probably have lots of questions, I’ll try to answer some of them here. If you have more questions, just send them to me and I’ll add them here, along with the answer.

How do I branch off main?

You don’t really branch off main, in that you usually won’t need to create two commits off main, you’ll only create one.

git

This is how git thinks of branches. You create a branch, and you're now in a special branch bit.

In git, we branch off of main, and now our mental model is that “we’re in that branch”. In reality, if you look at the graph on the right, it’s all still just a line, we’ve just made a mental “bend” in the graph to tell ourselves that we’re on a branch.

As far as the graph is concerned, though, nothing special really actually happened, we just added more commits. The only real difference is that “main” stops at the third commit, whereas “my branch” stops at the sixth commit. Other than that, the entire history is just one line.

Jujutsu

This is how jj thinks of branches. The two graphs are equivalent, but you aren't anywhere special, `main` is just farther back.

Jujutsu, on the other hand, doesn’t care what you think. It only cares what parents, children, and siblings commits have.

There are two reasons you might want to branch:

History legitimately diverges into multiple directions, or
You want to communicate to other people (or to yourself) that this part of the history is different (e.g. it contains some feature). This is also the case when you want to create a new branch so you can open a PR for it.

To Jujutsu, this repo’s history is a straight line, so there is no actual “branching”. The only reason to have branches here is communication, so Jujutsu asks you to label the commits that you want on the branches yourself. You can see these tags on the example on the right, and it’s the same as the git example above. There are still three commits in main, and three more in my branch.

Jujutsu calls these labels “bookmarks”, and they correspond to whatever git uses to tag branches. Bookmarks are what you’ll tag your commits with to tell git what your branches are.

Here, the graph has actually branched, because `main` has one extra commit.

Continuing the earlier example, if we create a second commit off main, even if that’s a merge commit (a commit with two parents) that’s when the tree actually diverges. In the graph on the right, the commit where we branched off now is a parent to two commits, and history is no longer linear. This isn’t special, it’s just how things are, but this is what’s actually a real “branch” to Jujutsu.

The way that git does things, ie creating a branch without history actually diverging, is just for us humans and our communication needs.

Jujutsu doesn’t require you to name its branches. You can happily work without any branch names at all, and you can easily see what branch is for what from the commit descriptions. You can name them, if you prefer, but you don’t have to.

This sounds a bit alien right now, but it’s actually a really nice way to work.

I’m worried I’ve lost you here, but it doesn’t matter. You’ll understand all of this easily when you play around with the tree a bit in jjui.

How do I add a commit message?

You can add a commit message at any time to the current, using the describe command. You can do this at any time, you can even go back to other commits and amend their messages (again with the describe command).

How do I choose which of my changes to commit?

You don’t! Everything is already in a commit! What you do is you interactively select some of the changes in the current commit (whether this commit is blank/new or an old commit, it doesn’t matter), and you split that commit into two.

Jujutsu can also do this automatically! If you have a commit with a bunch of small changes to various files, jj can absorb these changes into the closest ancestor commit where each thing changed. This is pretty magical, as you can add a few one-liner bugfixes here and there, and jj will just automatically include them in the commits where those lines were touched.

How do I check out a commit?

Without getting too much into specifics, you just edit the commit you want. This checks it out and you can make changes to it, however keep in mind that, if the commit was previously pushed to a remote, jj will give you a warning that you shouldn’t change commits you’ve pushed.

jjui will make navigation around the repo really easy, so use it for checking out commits as well.

How do I cherry-pick a commit onto another branch?

You just… move it. In jjui, go to the commit you want to move, press r (for rebase), go to the commit you want to move it after, press enter, and that’s it.

How do I reset soft/hard?

There isn’t really a soft reset, as there isn’t a staging area for your changes to be reset in. Simply check out (edit) the commit you want to edit, that’s a soft reset in Jujutsu.

For a hard reset (ie to throw away a commit), you abandon that commit. jjui will, again, make it much easier to do this.

What if I make a mistake?

No matter what you do, you can undo it. Not just changes, but any jj operation, you can undo rebases, pulls, anything.

You can also use the oplog (again, jjui makes this really easy) to go back to how the whole repo looked at any point in time. Don’t be afraid to try things, with jj it’s really easy to undo any mistake.

How do I amend a commit?

Simply edit it and make the changes you want.

How do I move unstaged changes from one branch to another?

There are no unstaged changes in jj. All changes are in a commit, if you want to move the changes in your current commit to another branch, simply move your current commit to the target branch by rebasing. I can never remember what “rebase X onto Y” does, so just move the commit with your changes to be a child of your branch’s tip (again, use jjui for this).

How do I open a PR on GitHub?

To do that, you need to push a new branch. Go to the commit you want to push, then probably create a new one on top of that (I tend to create a new commit when I’m done with an old one, just so I’m remember I’m done, but this is personal preference). Then, bookmark that commit with the branch name you want to give your PR, and push the commit along with the bookmark.

That’s all, now you can open the PR.

Here, jj exposes the low-level operations much more than git: You need to move the bookmark on your own to the commit you want to push (git does that automatically for you), and you need to push the bookmark manually as well. This is very helpful for understanding how things work under the hood, but usually you’ll set a jj alias to do this in one step.

Personally, I have an alias (which I’ll include below) to find the bookmark name, move it to the latest commit, and push.

My aliases

Here’s my alias config:

[aliases]
init = ["git", "init", "--colocate"]
ps = ["util", "exec", "--", "bash", "-c", """
set -e

# Check if current commit has both description and changes
has_description=$(jj log -r @ --no-graph --color never -T 'description' | grep -q . && echo "yes" || echo "no")
# Use 'empty' template keyword to check if commit has changes
has_changes=$(jj log -r @ --no-graph --color never -T 'empty' | grep -q "false" && echo "yes" || echo "no")

if [ "$has_description" = "yes" ] && [ "$has_changes" = "yes" ]; then
    echo "Current commit has description and changes, creating new commit..."
    jj new
fi

# Get the bookmark from the parent commit directly
bookmark=$(jj log -r 'ancestors(@) & bookmarks()' -n 1 --no-graph --color never -T 'bookmarks' | sed 's/\\*$//' | tr -d ' ')

if [ -z "$bookmark" ]; then
    echo "No bookmark found on parent commit"
    exit 1
fi

echo "Moving bookmark '$bookmark' to parent commit and pushing..."
jj bookmark set "$bookmark" -r @-
jj git fetch
jj git push --bookmark "$bookmark" --allow-new
"""]
cma = ["commit", "-m"]

This means I can jj init to add jj to a git repo, and jj cma "message" to describe the current commit and create a new one on top of it (that’s what commit does under the hood).

jj ps is a convenience alias that:

Looks backward in history
Finds the last bookmark there (if this were git, this would be my branch name)
Checks if the current commit has changes in it
If it does, it creates a new commit
Moves the bookmark to the parent commit (the one I was on before I ran the command)
Fetches changes from upstream (to update my tree)
Pushes the changes to the remote

I use this a lot!

Epilogue

Jujutsu doesn’t do anything that git can’t do, but it removes so much friction that you’ll actually end up doing things all the time that git could do, but that were so fiddly with git that you never actually did them.

Creating a branch for a minute just to try an idea out even though you’re in the middle of some changes, going back to a previous commit to add a line you forgot, moving commits around the tree, all of these things are so easy that they’re now actually your everyday workflow.

With git, I never used to switch branches in the middle of work, because I was too worried that stashing multiple things onto the stack would eat my work. I’d never go back to a previous commit and amend it, because here be dragons. I was extremely afraid of rebasing because I always got one conflict per commit and had to unconflict the same thing fifty times.

Jujutsu gives you the confidence and understanding to do all of these things, and if you fuck something up (which I haven’t yet, miraculously!) the oplog is right there to fix everything to how it was 30 seconds ago.

I hope this tutorial made sense, but I’m worried it didn’t. Please contact me on Twitter or Bluesky, or email me directly, if you have feedback or corrections.