DEV Community: Semih ERDOGAN

Context Rollovers Without /compact

Semih ERDOGAN — Wed, 08 Jul 2026 19:38:14 +0000

Long AI coding sessions have a quiet failure mode.

They do not always fail with a bad command, a broken test, or an obvious wrong turn.

Sometimes they fail at the boundary between one context window and the next.

That boundary is exactly where I do not like giving control to an opaque automatic compaction step.

Most AI coding tools eventually hit the same problem. The conversation gets long, the context window gets full, and something needs to happen before the next step becomes unreliable.

The default answer is usually some form of /compact.

I understand why it exists. A long transcript cannot grow forever.

But I never liked the control model.

The assistant decides what matters. It rewrites the conversation into a smaller representation. Then I continue from that summary, without really knowing what was dropped, what was compressed too aggressively, or which failed attempt is now missing from the working memory.

That is exactly the kind of hidden state I try to avoid in coding workflows.

My first serious answer to this was handoff, a local-first CLI for structured AI coding sessions.

That still works well when I want a spec-driven flow: intent, spec, design, decisions, state, session summary, and drift checks.

But not every workday task deserves that much process.

Sometimes I am already deep in a repository, moving through small implementation steps, and I only need one thing:

Before the session gets cleared, write down exactly enough state for the next session to continue safely.

So I built a lighter setup around Claude Code.

What I wanted

The goal was not to create another full workflow system.

I wanted a small project-local rollover protocol:

disable automatic compaction
show context usage while I work
warn when context gets high
write a concrete HANDOFF.md before clearing
load that handoff automatically in the fresh session
keep everything inspectable as normal files

The important part is that the handoff is explicit.

I can open it, edit it, delete it, review it, or decide it is not good enough. The next session starts from a file I control, not from a hidden summary I have to trust.

The project layout is intentionally small:

.claude/
  settings.json
  skills/
    handoff/
      SKILL.md
  templates/
    HANDOFF.template.md
  scripts/
    context_monitor.py
    load_handoff.py
    statusline.py

The Claude settings

The first decision is to turn off auto compaction.

In .claude/settings.json:

{
  "autoCompactEnabled": false,
  "env": {
    "CLAUDE_CONTEXT_WINDOW": "1000000",
    "CLAUDE_ROLLOVER_WARN_BANDS": "75,85,92"
  },
  "statusLine": {
    "type": "command",
    "command": "python3 .claude/scripts/statusline.py"
  },
  "hooks": {
    "UserPromptSubmit": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/scripts/context_monitor.py\""
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/scripts/context_monitor.py\""
          }
        ]
      }
    ],
    "SessionStart": [
      {
        "matcher": "startup|clear",
        "hooks": [
          {
            "type": "command",
            "command": "python3 \"$CLAUDE_PROJECT_DIR/.claude/scripts/load_handoff.py\""
          }
        ]
      }
    ]
  }
}

There are three moving parts here.

statusline.py keeps the current model, branch, and context usage visible while I work.

context_monitor.py runs after user prompts and tool use. When context usage crosses a configured band, it tells the session that rollover is recommended.

load_handoff.py runs when a new session starts or after /clear. If HANDOFF.md exists at the project root, it injects it into the new session as additional context.

That is the loop.

The context warning

The monitor is deliberately boring.

It reads the session transcript path from hook input, scans only the tail of the file, finds the latest main-chain assistant usage entry, and computes an approximate percentage against the context window.

When the percentage crosses a band, it warns once for that band:

msg = (
    f"Context at ~{pct}% ({tokens:,}/{window:,} tokens). "
    "Rollover recommended: run /handoff, then /clear."
)
note = (
    f"[context-rollover] Context usage is at ~{pct}% of the window. "
    "Per this project's rollover protocol: finish the current atomic step "
    "(do not leave the working tree broken), then tell the user it is time "
    "to roll over and offer to run /handoff to write HANDOFF.md. "
    "Do NOT suggest /compact."
)

That last line matters.

I do not want the assistant to solve this by falling back to the default compaction habit. The instruction is specific: finish the current atomic step, write a handoff, clear, resume.

The hook also exits successfully on any internal error. A context monitor should never break the coding session.

The /handoff skill

The user-facing command is a Claude skill called handoff.

Its job is to write one file: HANDOFF.md.

The skill front matter keeps the tool surface tight:

---
name: handoff
description: Write HANDOFF.md for a context rollover so the user can /clear and continue in a fresh session. Use when the context-rollover warning fires, when context usage is high, or when the user asks to hand off / roll over / continue in a new session.
argument-hint: "[optional extra notes to carry over]"
allowed-tools: Read, Write, Bash(git status:*), Bash(git branch:*), Bash(git log:*), Bash(git diff:*), Bash(date:*)
---

Then it captures live repository state at invocation time:

Current repo state (captured at invocation):

- Date: !`date '+%Y-%m-%d %H:%M'`
- Branch: !`git branch --show-current`
- Working tree: !`git status --short`
- Diff summary: !`git diff --stat HEAD`
- Recent commits: !`git log --oneline -5`

That gives the assistant hard facts before it writes the handoff.

The rest of the skill is mostly constraints:

follow the template exactly
use real paths and commands
keep it dense
include failed attempts
make the next step immediately executable
do not include secrets
overwrite any existing HANDOFF.md
do not commit anything

The "failed attempts" section is the one I care about most.

Successful work is usually visible in the diff. Failed attempts disappear unless someone writes them down. That is how fresh sessions waste time retrying commands, approaches, or assumptions that already failed twenty minutes ago.

The template

The template is short and intentionally operational:

# Handoff

> Generated: {date} - Branch: {branch} - Previous session: {one-line session label}

## Current Goal

## Current State

## Completed Work

## Key Decisions

## Files Changed

## Failed Attempts / Avoid

## Open Tasks

## Next Concrete Step

## User Preferences / Constraints

This is not a spec.

It does not try to redesign the task. It does not ask for a product brief. It does not split the feature into phases.

It answers one practical question:

If I clear the session right now, what does the next assistant need in order to continue without guessing?

The most important section is Next Concrete Step.

Not "continue the migration." Not "finish the API." Not "investigate tests."

It should be something like:

Open `app/services/billing/reconcile.py` and update `build_reconcile_query`
to include the new `invoice_status` predicate, then rerun
`pytest tests/services/test_billing_reconcile.py`.

That is the difference between a useful handoff and a vague summary.

Resuming after /clear

The resume hook is just as small.

On session start, it looks for HANDOFF.md at the project root:

root = os.environ.get("CLAUDE_PROJECT_DIR") or data.get("cwd") or os.getcwd()
path = os.path.join(root, "HANDOFF.md")
if not os.path.isfile(path):
    return

If the file exists, it reads a bounded amount, includes the file age, and injects it as rollover context:

age_h = (time.time() - os.path.getmtime(path)) / 3600
with open(path, encoding="utf-8", errors="replace") as f:
    body = f.read(MAX_BYTES)
ctx = (
    f"[context-rollover] HANDOFF.md found at the project root "
    f"(last modified {age_h:.1f}h ago). It is the handoff from the previous "
    "session - resume from it. Read 'Next Concrete Step' and continue there. "
    "Briefly confirm to the user that you resumed from HANDOFF.md and state "
    "the next step. If the user's first message is unrelated to this handoff, "
    "or it looks stale, say so and ask whether to delete HANDOFF.md.\n\n"
    "----- HANDOFF.md -----\n" + body
)

That stale-file behavior is important.

HANDOFF.md is useful when it is current. It is dangerous when it silently becomes old context. The hook does not delete or ignore old files by itself; it exposes the age and tells the fresh session to call out a stale or unrelated handoff instead of continuing blindly.

The actual daily flow

The day-to-day usage is simple.

When the context warning appears, I do not immediately clear the session. First I let the assistant finish the current atomic step so the working tree is not left in a broken state.

Then I run:

/handoff

That writes HANDOFF.md. If the task is important, I quickly scan the file, especially Failed Attempts / Avoid and Next Concrete Step.

Then I run:

/clear

In the fresh session, the SessionStart hook loads HANDOFF.md. I usually still send a small prompt such as:

Continue from HANDOFF.md.

That prompt is not doing the loading. The hook already did that. It is just an explicit nudge that the fresh session should continue the rollover instead of treating the first turn as a new unrelated task.

Why this is separate from handoff

My handoff CLI and this Claude setup solve related but different problems.

The CLI is for structured work. It is useful when I want the assistant to move from feature intent to spec, design, task state, decisions, evidence, and drift audit.

This setup is for daily continuity.

It does not ask me to work spec-first. It does not impose a planning phase. It only creates a controlled boundary between one session and the next.

That makes it much easier to use during normal work.

When the task is large or ambiguous, I still prefer the full handoff workflow.

When I am already coding and the context window is getting high, this lighter /handoff is enough.

Porting the idea to Codex or another agent

The exact files will change by tool, but the design ports cleanly.

You need four surfaces:

persistent instructions
a reusable handoff command
lifecycle hooks, if the tool supports them
a project-local handoff file

For Claude Code, that became:

.claude/settings.json
.claude/skills/handoff/SKILL.md
.claude/templates/HANDOFF.template.md
.claude/scripts/*.py
HANDOFF.md

For Codex, I would map the same idea differently.

Use AGENTS.md for durable repository rules: when to roll over, what HANDOFF.md means, and how fresh sessions should treat it.

Use a Codex skill for the reusable workflow. Codex skills are plain directories with a SKILL.md, and repo-scoped skills can live under .agents/skills. A handoff skill there can carry the same template discipline: inspect git state, write HANDOFF.md, preserve failed attempts, and end with a concrete next step.

Use Codex hooks for lifecycle glue. Codex supports hook events such as UserPromptSubmit, PostToolUse, SessionStart, PreCompact, and PostCompact, configured through hooks.json or config.toml under the relevant .codex layer. That is enough to recreate the same pattern: warn before context rollover, discourage blind compaction, and load HANDOFF.md when a fresh session starts.

The shape would look like this:

AGENTS.md
.agents/
  skills/
    handoff/
      SKILL.md
.codex/
  hooks.json
  hooks/
    context_monitor.py
    load_handoff.py
templates/
  HANDOFF.template.md
HANDOFF.md

The exact hook payloads and statusline behavior are tool-specific, so I would not blindly copy the Claude scripts into Codex. I would keep the protocol and adapt the integration points.

For tools without hooks, the fallback is still useful:

Ask the assistant to write HANDOFF.md using the template.
Start a new session.
Paste or attach HANDOFF.md.
Tell the assistant to continue from Next Concrete Step.

That is less automatic, but it keeps the most important property: the context boundary is explicit and reviewable.

Full example files

I did not want to turn this post into a wall of Python, so I kept the full example files separate:

These are meant as a starting point, not a package. The important part is the protocol: warn before rollover, write the handoff explicitly, clear the session, and load the handoff into the next one.

The rule I care about

The real rule is simple:

Do not let an invisible summary become the only bridge between two coding sessions.

If the work matters, the bridge should be a file.

It should say what changed, what failed, what decisions were made, what remains open, and what the next concrete step is.

That does not need to be heavyweight.

For big features, I still like structured specs and state files.

For daily coding, a disciplined HANDOFF.md is often enough.

Agent Poke: Scheduled Check-ins for Codex and Claude Code

Semih ERDOGAN — Fri, 15 May 2026 09:14:03 +0000

I use Codex CLI and Claude Code a lot during the day.

Not through an API. Not through a custom integration.

Mostly just the normal local CLIs, logged in with my subscription accounts, running inside whatever project I am working on.

That workflow is simple enough, but there was one small thing I kept thinking about.

Some of these tools meter usage in rolling time windows. In practice, the first message starts the window. If I only remember to open the tool later in the day, I may still have the same subscription, but the timing is not as useful as it could be.

So I built a tiny helper for myself: agent-poke.

Repo: github.com/semiherdogan/agent-poke

It does not try to be smart.

It just sends a small message to the agents at fixed times.

Hey!

That is the whole idea.

The problem I wanted to solve

Claude is most useful to me during the workday, roughly between 09:00 and 19:00.

Codex is useful almost all the time.

At first, I thought about making the scheduler dynamic. It could track the last run, calculate the next allowed time, handle per-agent windows, and keep its own state.

That was too much for this problem.

What I actually needed was a static schedule that lines up with the day well enough.

The current schedule is:

0 6 * * * /app/scripts/run-checkin.sh
6 11 * * * /app/scripts/run-checkin.sh
12 16 * * * /app/scripts/run-checkin.sh
18 21 * * * /app/scripts/run-checkin.sh

In plain English:

06:00 starts the first window before the workday
11:06 is five hours plus six minutes later
16:12 carries the window through the end of the workday
21:18 opens an evening window with a little more buffer

The six extra minutes are intentional.

I do not need to hit the boundary exactly. I only need to avoid firing slightly too early.

The container timezone is configured through TZ in docker-compose.yml. For me that is:

TZ: Europe/Istanbul

Why Docker

I want this to run on a server, not on my laptop.

That made Docker Compose the simplest deployment target. The container has the two CLIs installed, a scheduler, and a small runner script.

The shape is deliberately boring:

agent-poke/
  Dockerfile
  docker-compose.yml
  config/
    schedule.cron
  scripts/
    login-codex.sh
    login-claude.sh
    run-checkin.sh
  logs/
  workspace/

There is no database. No web UI. No queue. No service framework.

It is just enough container around a few CLI commands.

Login is still manual

This part was important to me.

I did not want to bake credentials into an image or pretend subscription login is the same thing as an API key.

The user logs in once, using the official CLI flow.

For Codex:

docker compose run --rm agent-poke login-codex

That runs:

codex login --device-auth

For Claude:

docker compose run --rm agent-poke login-claude

That runs:

claude auth login --claudeai

Both CLIs save their login state under the container user's home directory.

That directory is a Docker volume:

volumes:
  - agent_home:/home/agent

So the image can be rebuilt, but the login state stays.

The one command to avoid is:

docker compose down -v

That removes the volume, which also removes the saved logins.

Interactive check-ins

My first thought was to avoid the interactive CLIs entirely.

For scheduled jobs, non-interactive commands are usually cleaner:

codex exec "Hey!"
claude -p "Hey!"

But for this specific tool, I decided against that.

The goal is to behave like normal CLI usage. I do not want Codex and Claude to use different paths, and I do not want Claude to accidentally fall into a separate programmatic usage bucket if its metering changes.

So the final version drives both CLIs the same way:

open the interactive CLI with Hey! as the initial prompt
wait for the response to settle
exit the CLI

The runner starts the agents in parallel. That matters because I do not want Claude to start several minutes after Codex just because one response is slow.

Passing the message as the initial prompt also avoids a fragile timing problem: the scheduler does not have to wait for the TUI input box to become ready before typing.

That means expect is back in the image.

It is a little less elegant than a pure non-interactive command, but it matches the way I actually use the tools.

There is one operational consequence: after login, I run one manual check so both CLIs can ask and remember any workspace trust prompt.

docker compose run --rm agent-poke checkin

After that, the scheduled runs use the same interactive path.

The runner keeps recent logs only. The default is:

LOG_KEEP: 20

That is enough to inspect recent runs without letting a small helper slowly fill a disk.

Raw terminal output is disabled by default because TUI tools emit a lot of escape sequences. If I need to debug the actual screen output, I can turn it back on with:

RAW_AGENT_OUTPUT: 1

The normal log only records whether each agent started and completed successfully. I deliberately avoided parsing TUI output because small formatting changes in Codex or Claude could make that brittle.

The small deployment detail

The container runs as a non-root user.

That is usually the right default, but it means the host-mounted logs/ and workspace/ directories need to be writable by that user.

On this image, the agent user is 1001:1001, so the setup needs:

mkdir -p logs workspace
chown -R 1001:1001 logs workspace

That fixed the only real deployment issue I hit.

Without it, the check-in script could start, but failed when it tried to create a log file.

What I like about it

This is one of those tools where the main feature is that there are not many features.

The final version is just:

fixed schedule
manual login
persistent home volume
interactive CLI check-ins
plain log files
Docker Compose deployment

That is enough for now.

If I ever need per-agent scheduling or smarter state, I can add it later.

But for this problem, the static version is easier to trust.

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 first 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.

But continuity was only part of the issue.

The deeper problem was that intent, requirements, decisions, current progress, and validation evidence were scattered across chat history and code changes.

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 now revolves around six files:

FEATURE.md: raw feature intent
SPEC.md: normalized requirements and acceptance criteria
DESIGN.md: optional technical design
DECISIONS.md: durable product and architecture decisions
STATE.md: execution plan, progress, and evidence
SESSION.md: continuation-safe session summary

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

Just files, prompts, and a deterministic workflow from intent to execution.

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 several different problems:

the assistant forgets where the work stopped
the assistant starts implementation before the work is decomposed well enough
important decisions lose their reasoning
completed work lacks evidence
implementation quietly drifts away from the spec

Those later problems matter 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 intent-aware, planning-aware, decision-aware, and 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

There is also a closing-loop command:

handoff drift --copy

handoff drift does not modify code. It generates a structured audit prompt that asks an assistant to compare the saved intent, spec, design, decision log, state, session summary, and implementation.

That gives you a final check before you call the feature done.

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
DECISIONS.md captures why durable choices were made
STATE.md captures what is being done right now
STATE.md also captures evidence for completed steps
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, review decisions later, and check whether the task list actually matches the feature.

Decisions are part of the memory

Requirements are not the only thing worth preserving.

In long-running work, the more expensive loss is often decision history:

Why did we choose this approach?
What alternatives did we reject?
Is this decision still valid?
Should a future assistant re-open this topic?

That is why new feature workspaces include DECISIONS.md.

It is intentionally lightweight. It is not for every small implementation detail. It is for durable product or architecture choices that future sessions should not re-litigate without new evidence.

Evidence changes the execution loop

AI-assisted coding often ends with a vague claim that work is done.

That is not enough.

The default execution prompts now ask the assistant to record evidence in STATE.md after completed micro-steps:

changed files
commands or tests run
result
notes or remaining risks

That turns the loop from:

Task -> "done"

into:

Task -> code -> evidence

It is still simple Markdown, but it gives you something concrete to review.

Drift audit before closing

The last failure mode is silent drift.

A feature can have a good spec, a reasonable plan, and passing tests while still missing part of the original intent.

handoff drift --copy exists for that moment.

It emits a prompt for an audit, not an automatic verdict. That distinction is important. The CLI stays deterministic and provider-agnostic; the assistant does the code inspection using the saved artifacts as the checklist.

The goal is to catch mismatches like:

a requirement in SPEC.md that never reached implementation
an accepted decision in DECISIONS.md that code ignored
a completed task in STATE.md without matching evidence
a session summary that no longer reflects the repo

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.

Before closing the work, I can ask for a drift audit:

handoff drift --copy

That prompt checks whether the implementation still matches the saved intent.

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, decisions, evidence, and drift.

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 evidence exists for completed work?
Did implementation drift from the spec or decisions?
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 want decision history outside chat
you want evidence attached to completed work
you want drift checks before closing features
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 intent, memory, decisions, evidence, 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
handoff drift --copy

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
handoff drift --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: