Forem: Semih ERDOGAN

handoff: Keeping AI Coding Sessions on Track

Semih ERDOGAN — Fri, 08 May 2026 05:55:05 +0000

AI coding tools are very good at helping with the next step.

They are much worse at reliably carrying the full thread of a feature across multiple sessions.

That was the problem I kept running into.

I would start a feature with Claude, ChatGPT, Copilot, or another assistant, make real progress, then step away. When I came back, I had the same questions again:

What exactly was I building?
What decisions had already been made?
What was the current step?
What should happen next?

The model had no memory. I had partial memory. The repo had some memory. None of it was structured enough.

So I built handoff.

What handoff is

handoff is a local-first CLI for structured AI coding workflows.

It creates a small workspace inside your repository under .handoff/ and uses plain Markdown files as the source of truth for the feature you are working on.

The core workflow revolves around five files:

FEATURE.md: raw feature intent
SPEC.md: normalized requirements and acceptance criteria
DESIGN.md: optional technical design
STATE.md: execution plan and progress
SESSION.md: continuation-safe session summary

No cloud sync. No provider lock-in. No hidden agent runtime.

Just files, prompts, and a deterministic workflow.

The real problem was not only memory

At first, I thought continuation was the only missing piece.

After enough AI-assisted coding sessions, I realized there were actually two different problems:

the assistant forgets where the work stopped
the assistant starts implementation before the work is decomposed well enough

That second problem matters just as much.

If the feature is vague, the assistant tends to improvise. Sometimes that works. Sometimes it creates drift, partial implementation, or too much code too early.

That is why handoff is planning-aware, not just continuation-aware.

The workflow I wanted

I wanted something with the strengths of structured decomposition, but without forcing people into one IDE or one proprietary workflow.

I also did not want a system where users had to manually juggle several tools just to start a feature.

So the result became a hybrid workflow:

simple when you want speed
explicit when you want control

The default path

For most features, the flow starts like this:

handoff init payment-integration

Then you edit .handoff/current/FEATURE.md with the feature request, requirements, and constraints.

After that:

handoff run --copy

That is now the default entry point.

handoff run looks at the saved workspace state and decides what prompt should come next:

if planning is incomplete, it emits a planning prompt
if the execution plan is ready, it emits an execution prompt
if execution is already underway, it emits a continuation prompt

That keeps the simple path simple.

You can also use:

handoff next
handoff status

to inspect what the tool thinks should happen next without generating another prompt.

The advanced path

Sometimes you want to review the planning before any code is written.

For that, handoff also has:

handoff spec --copy
handoff design --copy
handoff tasks --copy

Those commands let you inspect the work in stages:

spec: turn feature intent into clear requirements
design: map those requirements to a practical implementation approach
tasks: generate an execution-ready task list in STATE.md

Then you can run:

handoff start --copy

and begin implementation from a cleaner plan.

That distinction matters:

run is the default state-aware entry point
start is for direct execution when a valid plan already exists

Why the file split matters

The value is not just "more files."

The value is that each file has one job:

FEATURE.md captures intent
SPEC.md captures what must be true
DESIGN.md captures how to approach it
STATE.md captures what is being done right now
SESSION.md captures what the next session must know

That separation gives the assistant better footing.

It also gives you better reviewability. You can inspect the spec before implementation, challenge the design before code, and check whether the task list actually matches the feature.

Why determinism matters

One of the design goals of handoff is determinism.

That is why handoff continue is guarded.

If the execution plan is invalid, the command fails with a deterministic error instead of pretending everything is fine.

Examples:

no execution plan initialized
multiple current [>] steps
no remaining steps

That behavior is deliberate.

I do not want a workflow that silently fixes state by guessing. I want the handoff to be inspectable and stable.

A concrete example

Imagine I am adding a payment flow.

I might start with:

handoff init payment-flow

Then in FEATURE.md:

support Stripe checkout
keep existing order flow intact
show clear errors
do not refactor unrelated modules

From there I have two options.

Fast path:

handoff run --copy
handoff next

Reviewable path:

handoff spec --copy
handoff design --copy
handoff tasks --copy
handoff start --copy

Once work is in motion, I can continue with:

handoff continue --copy

The next session gets a prompt grounded in the existing state, not a vague memory of yesterday.

Better continuity is not only about prompts

One thing I like about the current shape of handoff is that it is not only a prompt generator anymore.

It also helps surface state.

That is why commands like these matter:

handoff status
handoff next
handoff validate

They make the saved workflow visible instead of burying it inside one long prompt.

That is important when you are trying to answer simple questions like:

Is this feature ready for execution?
What is the current step?
Why is the workflow blocked?
What command should I run next?

Why local-first still matters

I wanted this to work with any coding assistant.

That meant the core could not depend on one provider, one editor, or one hosted workflow system.

So handoff stays local-first:

Markdown files in your repository
prompt generation from a CLI
no provider dependency in the core flow
no cloud requirement

You can use it with ChatGPT today, Claude tomorrow, Copilot later, or another tool entirely.

The workflow stays yours.

Why repository context matters too

Feature state is only part of the story.

Repository context matters too.

If your README.md and AGENTS.md are missing, stale, or too thin, AI sessions still waste time rediscovering the same project facts.

That is why handoff init can flag missing high-value context, and why there is also a handoff prompt context flow for improving repo-level guidance without writing application code.

That may sound small, but it matters in practice.

A feature plan works much better when the surrounding repository is legible.

Why I still like the CLI model

There is a lot of value in editor-native workflows, and I may support more of them over time.

But the CLI model has one major strength: portability.

The moment a workflow depends too heavily on one IDE, it becomes harder to reuse across tools, harder to debug, and harder to trust.

handoff keeps the source of truth in files you can inspect directly.

That makes it easier to reason about, easier to version, and easier to carry across environments.

Who this is for

handoff is a good fit if:

you build features across multiple AI sessions
you switch between assistants or editors
you want better task decomposition before coding
you care about deterministic state and inspectable workflow
you prefer local tools over hosted orchestration

It is probably not for you if you want a full IDE platform with built-in visual workflow management and heavy automation everywhere.

That is fine. The tool is intentionally narrower than that.

The short version

handoff gives AI coding workflows a memory, a plan, and a deterministic continuation path without taking ownership of your editor or your repository.

That is the whole idea.

Try it

If you want to try the current default flow:

handoff init my-feature
# edit .handoff/current/FEATURE.md
handoff run --copy
handoff next
handoff status

If you want to inspect planning in stages first:

handoff init my-feature
# edit .handoff/current/FEATURE.md
handoff spec --copy
handoff design --copy
handoff tasks --copy
handoff start --copy
handoff continue --copy

Project link:

handoff on GitHub

If you are building with AI every day, you already know the pain this solves.

The interesting part is not that the model needs context.

It is that context needs structure.

Cloudflare Tunnel, Traefik, and a Cleaner Self-Hosted Setup

Semih ERDOGAN — Thu, 07 May 2026 13:26:01 +0000

Today I set up a small stack on my own server using Docker, Cloudflare Tunnel, and Traefik.

The goal was simple: I wanted a cleaner way to expose and manage multiple projects without treating every new deployment like a one-off configuration job.

The useful part was not just that it worked. It made the server feel like a reusable system.

Why I wanted this

I like keeping small projects available online, but once there is more than one service involved, setup work starts repeating itself very quickly.

You need routing, domain handling, HTTPS, container management, and some way to stop the server from becoming a pile of unrelated manual decisions.

I wanted something that felt structured enough to grow, but still lightweight enough for personal projects.

The stack

Docker runs the services
Traefik handles reverse proxying and routing
Cloudflare Tunnel connects the server to the outside world without the usual direct exposure model

Docker gives each project a predictable runtime shape. Traefik gives those projects a consistent entry point. Cloudflare Tunnel removes a lot of the usual friction around exposing services safely.

What makes the stack work is that the responsibilities are separated in a sensible way. Containers are responsible for running applications. Traefik is responsible for routing and service discovery. The tunnel is responsible for controlled external access. Once those boundaries are clear, the setup becomes easier to extend without each layer leaking too much into the others.

Why not just keep it simpler?

That is a fair question, because for one app, a simpler setup is often good enough. A straightforward reverse proxy config is not a problem when there is only one destination behind it.

The problem starts when the server stops being "the place where one app runs" and becomes "the place where different projects may come and go over time."

That is the point where I stop caring only about whether something works and start caring more about whether the structure will still feel reasonable after the fourth or fifth service.

Where this starts to make sense

With a single app, almost any setup can feel acceptable. A manual proxy config does not look too bad when there is only one target. But once there are multiple services, different hostnames, and the possibility of adding more over time, the difference becomes obvious.

That is the point where Traefik stops feeling optional. It becomes the layer that gives the server a stable structure. Services become easier to reason about, routing stops feeling ad hoc, and adding another project starts to look like a repeatable step instead of a fresh configuration job.

The most useful part was reduction in repeated decisions.

services run in containers
routing is handled in one consistent way
external access follows the same pattern

Adding another project no longer looks like "what do I need to invent for this one?" It looks more like "how does this fit into the structure that already exists?"

That is a much better place to be, especially for side projects and internal tools.

What adding a new project looks like

At a high level, adding a new project comes down to two things:

add a hostname rule in the Cloudflare Tunnel dashboard
add Traefik labels to the project's docker-compose.yaml

On the Cloudflare side, the rule is straightforward: point something like test.semiherdogan.net to the Traefik entry point behind the tunnel.

On the container side, the project can stay very small:

services:
  app:
    build: .
    restart: unless-stopped
    labels:
      - traefik.enable=true
      - traefik.http.routers.test.rule=Host(`test.semiherdogan.net`)
      - traefik.http.routers.test.entrypoints=web
      - traefik.http.services.test.loadbalancer.server.port=80
    networks:
      - proxy

networks:
  proxy:
    external: true

The required shape is easy to understand:

join the shared proxy network
declare the hostname in Traefik
let the tunnel rule send traffic to that entry point

That repeatability matters more than the individual labels themselves. Once the naming and network pattern are stable, the cost of adding another service drops a lot because the shape of the problem is already known.

Cloudflare Tunnel also changes the order of concerns in a useful way. Instead of thinking first about direct exposure, port handling, and the outer edge of the server, I can focus more on internal service organization and routing.

That does not remove the need to think carefully, but it does remove some of the repetitive edge-work that usually makes self-hosting feel more fragile than it needs to be.

It also gives me an easy path for the cases where a domain, subdomain, or internal endpoint should not be openly reachable. In those cases, Cloudflare Zero Trust fits naturally into the same setup and makes it straightforward to put a protected layer in front of something without rethinking the whole deployment model.

It is easier to extend, easier to keep mentally organized, and much nicer to work with than a collection of separate, hand-made deployment paths.

The interesting part is not the individual tools. It is that together they create a setup where future projects feel cheaper to add.

And that is exactly the kind of infrastructure decision I tend to like: not flashy, but immediately useful once the number of projects starts growing.

Where I would be careful

The main risk in setups like this is not usually the first deployment. It is slow operational drift.

If hostnames, labels, networks, and entry points are not kept consistent, the "clean structure" benefit disappears surprisingly fast. The same is true if observability is left behind. Once multiple services share the same routing layer, it becomes more important to know what is failing, where requests are going, and which layer is actually responsible when something breaks.

That is also why I like this stack more as a pattern than as a one-time setup. The value is not just that the first app is online. The value is that the second, third, and fourth app can follow the same rules without the server turning back into improvisation.

Where this is probably too much

If you only have one small app and do not expect that to change, this may be more structure than you actually need. In that case, a simpler setup might be the better engineering decision.

What makes this stack appealing is not that it is universally better. It is that it starts paying off when you want a server to host multiple projects without every new service feeling like a fresh round of setup decisions.

Devbox: The First Nix-Based Tool That Felt Practical

Semih ERDOGAN — Thu, 07 May 2026 13:25:51 +0000

Recently I started using Devbox.

It is one of those tools that made immediate sense to me because it sits exactly in the gap I have been feeling for a long time.

Before that, my default workflow for trying a new idea was usually one of two things:

install whatever I needed directly on my machine with Homebrew
put the whole thing into Docker, even when the project was small

Both approaches work, but neither one felt right all the time.

Installing tools directly on my laptop is easy in the short term, but it slowly turns the machine into a place where random project decisions accumulate. A tool I needed once ends up sitting around forever. Version differences start to matter. The system becomes less intentional over time.

Docker solves a different problem, and sometimes it is exactly the right answer. But for very small experiments, side projects, or quick idea testing, it can also feel heavier than what I actually need. Sometimes I do not want a containerized runtime model. I just want a clean development shell with the right tools available.

Why I never fully committed to Nix

I have wanted something like this for a long time, which is why Nix has always been interesting to me in theory.

The promise is very attractive: reproducible environments, clean dependency boundaries, and less pollution on the host machine.

The part that always stopped me was not the idea. It was the feeling that the configuration itself asked for more commitment than I wanted to give, especially for small projects. Every time I looked at a Nix-based setup directly, it felt like I needed to buy into a whole way of thinking before I could get the practical benefit I was actually after.

Why Devbox clicked

Devbox was the first tool in this space that felt like it reduced the activation energy enough for me to actually use it.

The part I liked immediately is that it gives me the Nix-backed isolation I wanted, but through a much more approachable shape. Instead of feeling like I need to adopt the Nix language first, I can describe a project environment in a small JSON file and move on.

Instead of thinking, "do I want to invest in learning this whole toolchain right now?", the question becomes much simpler: "do I want this project to have a clean shell with pinned tools?"

That is a much easier yes.

Jetify's own docs describe Devbox as a way to create isolated, reproducible development shells without needing Docker or the Nix language, and that matches the part that mattered most to me in practice. Sources: What is Devbox?, Devbox GitHub repository.

What it looks like in practice

When I want to try a small project, I do not have to decide between making my laptop messier or creating more container setup than the project deserves. I can define the tools, enter the shell, and keep going.

The flow is simple enough that it is easy to remember:

devbox init
devbox search hugo
devbox add hugo@0.159.0

devbox shell # activate environment
hugo server

And the config stays small:

{
  "packages": ["hugo@0.159.0"],
  "shell": {
    "scripts": {
      "dev": ["hugo server"],
      "build": ["hugo --gc --minify"]
    }
  }
}

That is what made it click for me. It gives me the boundary I wanted without forcing a heavier setup than the project deserves.

It also makes cleanup feel more realistic. When the project is over, I do not need to remember which packages I threw onto my machine just to get through one afternoon of testing. The dependency boundary stays with the project.

That is the part I appreciate most. It feels lighter than Docker for this category of work, but still much more intentional than installing everything globally.

Why it feels worth keeping

Some tools are impressive but never become habit.

Devbox feels more promising to me because it fits into the kind of development work I actually do: small experiments, side projects, trying tools quickly, switching contexts often, and not wanting my machine to reflect every temporary decision I make.

I still think Docker and plain host installs both have their place. This is not really about replacing everything with one tool.

It is more that Devbox finally gave me a practical middle layer I had been missing for a long time.

That is why it clicked.

Simplifying EC2 Connections with AWS SSH

Semih ERDOGAN — Thu, 07 May 2026 13:25:39 +0000

As a developer working with AWS, I often found myself jumping between multiple EC2 instances. Connecting to them securely and efficiently was repetitive, and it usually meant bouncing between the AWS CLI and the Session Manager Plugin.

Those tools are powerful, but I wanted something simpler and faster for day-to-day use. That is why I built AWS SSH, a CLI tool with a small TUI that streamlines the process of connecting to EC2 instances.

Why I built AWS SSH

The AWS CLI and Session Manager Plugin already solve the core problem, but the workflow can still feel clumsy if you switch between instances often.

The main friction points for me were:

Manually searching for instance IDs and typing long commands.
Having no intuitive interface for picking the target instance.
Needing extra steps whenever I wanted to switch regions.

I wanted a tool that reduced that overhead and made the flow interactive instead of procedural.

How AWS SSH works

AWS SSH is a wrapper around the AWS CLI and Session Manager Plugin. It uses those existing tools and puts a more ergonomic interface on top.

The basic flow looks like this:

It fetches the EC2 instances available in your AWS account.
It shows them in a TUI so you can search and select the one you want.
Once selected, it starts the connection through AWS Session Manager.

It also supports region configuration. If you define regions in your AWS credentials file, the tool can search them automatically. If not, it asks you to pick a region at runtime.

Prerequisites

Before using AWS SSH, make sure these are installed and available in your PATH:

You can verify both with:

aws --version
session-manager-plugin --version

Installation

Download the latest release from the GitHub releases page, make it executable, and move it into your PATH.

chmod +x aws-ssh
mv aws-ssh /usr/local/bin/aws-ssh

On macOS, the first run may require allowing the binary from System Settings > Privacy & Security.

Usage

Run the tool like this:

aws-ssh [--profile|-p] [--region|-r] searchparam1 searchparam2 ...

That opens the interface, lets you filter the instance list, and then connects to the selected EC2 instance through AWS Session Manager.

Key features

A simple TUI for selecting EC2 instances.
Search support for narrowing down instances quickly.
Region configuration through your AWS credentials file.
Optional profile selection with --profile.

Configuring regions

If you want the tool to search specific regions automatically, add a regions key to the relevant section in your .aws/credentials file:

[default]
aws_access_key_id = YOUR_ACCESS_KEY
aws_secret_access_key = YOUR_SECRET_KEY
regions = us-east-1,us-west-2

With that in place, AWS SSH will search those regions without asking each time.

Required AWS permissions

To run the tool, you need at least these IAM permissions:

ec2:DescribeInstances
ssm:StartSession

An example policy looks like this:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "ec2:DescribeInstances",
        "ssm:StartSession"
      ],
      "Resource": "*"
    }
  ]
}

If you want tighter access control, you can scope Resource down to specific instances or tags.

Also make sure SSM is enabled on the target EC2 instance, with the required IAM role attached and the SSM agent installed and running. AWS documents that setup here:

Session Manager prerequisites

Why this tool is useful

AWS SSH is meant to remove friction from a workflow that developers repeat constantly. If you manage one instance it is convenient. If you manage many, it becomes much more valuable.

Project links: