DEV Community: George Michalakis

Switch Codex accounts seamlessly with AgentHop

George Michalakis — Sat, 19 Sep 2026 15:28:48 +0000

Story time

I use separate, legitimate Codex profiles for distinct contexts: personal work, a client workspace, and experiments that should not inherit the same local setup. Keeping those contexts separate is useful; repeatedly navigating between them was not.

Each time I needed a different profile, I would log out, change the active setup, reload Codex, and authenticate again. That routine was repetitive, slow, and disruptive.

Worse, it pulled me out of the task just to answer ordinary operational questions: which profile is selected? Is it signed in? What status did Codex last report?

First, let's make the switching less painful

The first (obvious?) answer was a small CLI script. It gave each context an isolated local profile and made the normal sign-out/re-auth cycle unnecessary for routine switching. That solved the most visible friction: I could select the identity and configuration used by the CLI without redoing the entire setup.

And this definitely made the switch faster. However, it did not make the decision easier.

When you are deep in work, I still needed to know:

Which profile is signed in?
Which one Codex reports as ready, close, or blocked, and when will it reset?

I could ask the CLI for status, but checking several isolated profiles by hand was still manual and easy to get wrong.

AgentHop's CLI makes each local profile's current status visible at a glance.

DaaS (Dashboard as a Service)

So the script became a dashboard (wow right). AgentHop reads the local, supported status for each profile and turns it into a small operational view:

ready
close
blocked

plus readable reset times. Profiles that are currently usable appear first; a blocked profile remains muted until the provider reports it as usable again.

That was the first payoff. Instead of bouncing between profile directories and terminal output, I could refresh once and see the current local picture.

The dashboard keeps the fuller account picture available when a quick status check is not enough.

But a dashboard still asks you to open a dashboard. For a check that happens several times in a day, that is one window too many.

The control surface moved to the tray

Now AgentHop starts quietly in the Linux system tray. Clicking its icon gives me the short list I actually need:

the active profile;
a suggested available profile when one is reported; then
profiles grouped by current status.

A blocked profile stays muted; an enabled entry can be clicked to switch directly.

The full dashboard is still there for onboarding, inspecting status, or preparing a new command, but it is no longer a mandatory stop between work and the profile I need.

And this distinction matters. The tray is for the frequent, low-friction question—which profile do I need right now? The dashboard is for the less frequent, higher-context tasks—add an identity, inspect the details, or start a new session.

From CLI status to a tray action and the full dashboard without losing the operational context.

Then I found the problem that mattered more

The first time I switched profiles and tried to continue a real task, I expected to run resume and pick up the conversation. Instead, the resume list looked empty.

The account switch had worked. My working memory had not followed me.

That discovery changed the project. Pretty much the local profile directory was doing two jobs at once: it held account-specific identity, but it also held the transcripts, indexes, snapshots, and other state that made a session discoverable. Pointing CODEX_HOME at a new profile did not just choose a different account; it could make the CLI look at a different history.

As a result I found myself asking a much more interesting question: how do you keep identity isolated without turning every account switch into a separate universe?

AgentHop is the MVP that came out of that question. How?

It is a local-first dashboard for managing AI coding CLI profiles while keeping resumable work close at hand. It:

separates profile identity from continuity;
shows the status Codex makes available; and
prepares the next Codex command without treating a profile change as a new project.

Independent project: AgentHop is unofficial, local software. It is not affiliated with, endorsed by, or supported by OpenAI. It does not create accounts, combine subscriptions, bypass limits, or expose credentials to the browser. It does not decide whether any account setup or use complies with provider policy.

Use only accounts you are authorized to use and follow the provider's terms. For OpenAI services, see the current Terms of Use and account-switching help.

The architecture: identity is NOT continuity

Most quick account switchers point a CLI at a different home directory. That works for isolated credentials, but a home directory often contains much more: configuration, transcripts, archived sessions, SQLite indexes, locks, and snapshots. Change the whole directory and you may change all of those at once.

The central design decision is deliberately simple:

Identity is isolated. Each account has its own local profile home.
Continuity is shared. Resumable session state lives in a canonical shared location defined by the provider adapter, including the discoverability metadata and indexes that let the CLI find it.
The provider owns provider details. The dashboard should not need to know how a particular CLI stores credentials, models usage, or indexes threads.

This is the difference between “switch who is making the next request” and “switch into a separate universe with no history.”

What AgentHop does today

AgentHop currently ships with an OpenAI Codex adapter and a local React + FastAPI control surface. It can:

discover the default and named local profiles;
show profile state as ready, close, or blocked, rather than hiding two independent status windows behind one percentage;
show human-readable 5-hour and weekly reset times when the provider supplies them;
mute profiles the provider reports as blocked and group profiles by their current status; and
create a new isolated profile, guide the user through the normal terminal sign-in, select a profile, reconcile shared continuity when required, and prepare a new or resume command.

The ordering is operational, not a policy judgment. Profiles reported as usable appear first. When a profile has more than one blocked window, AgentHop presents the later reset as its expected unblock time because that is the latest status change it can show.

The practical sequence is refresh, choose the profile appropriate for the work, reconcile shared state when required, then copy the next command.

The browser sees sanitized profile names, status, reset information, and command results. It never needs the contents of an authentication file.

A small architecture that leaves room to grow

AgentHop is not “provider-neutral” because it has a generic dropdown. Different CLIs have different credential stores, session models, supported status interfaces, and safe launch semantics. The shared core stays small so adapters can own those facts.

Layer	Responsibility
React dashboard	Local control surface; renders sanitized state and starts bounded actions.
FastAPI backend	Validates input, owns the local API boundary, selects adapters, and returns safe results.
Provider adapter	Discovers profiles, reads supported status, prepares commands, and owns continuity reconciliation behavior.

For Codex, AgentHop builds on documented CODEX_HOME, authentication, and app-server interfaces. The browser does not host an interactive CLI. It gives you a quoted command to review and run in your own terminal.

Try it locally

You need Python 3.11+, Node.js 18.19+ (Node 20+ recommended), npm, and the Codex CLI on your PATH.

git clone https://github.com/Thegm26/AgentHop.git
cd AgentHop

python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'
npm --prefix frontend ci
./scripts/desktop.sh

This repository launcher starts AgentHop in the local Linux system tray and builds the dashboard from the installed frontend dependencies. Click the icon to refresh or switch an enabled profile; choose Open dashboard… for the full view. The launcher keeps the backend on loopback. The README also covers the optional desktop-menu installer and the alternate .venv/bin/agenthop desktop launcher when frontend assets are already built.

For frontend development only, use another terminal:

cd frontend
npm run dev

Click Add account, choose a local profile name, copy the displayed sign-in command, and complete the normal provider login in your browser. Then return to AgentHop and choose Refresh usage. The app shows commands for review rather than running a shell for you. For desktop installation, APIs, and security details, see the README.

What this is—and what it is not

This is a local, single-user MVP: it does not create accounts, combine subscriptions, bypass provider limits, or send credentials to the dashboard.

It is not a remote or multi-user service, and Codex is its first working adapter. See the README for the complete security and deployment notes.

Repo: https://github.com/Thegm26/AgentHop

Open Tab: Let Your Spare Change Cover Someone Else's Checkout

George Michalakis — Mon, 07 Sep 2026 05:21:34 +0000

This is a submission for Weekend Challenge: Generosity Edition

What I Built

Open Tab lets one customer's spare change help with someone else's purchase.

A customer reaches checkout and chooses to add a small contribution. The money enters a shared pool. Another customer can use part of that pool during an ordinary checkout, with no application and no explanation required.

I built it around a familiar moment: someone has enough for most of a purchase and could use a little help with the rest. Asking a stranger or an employee can feel exposing. Open Tab keeps that moment inside the same payment screen everyone uses.

The weekend prototype connects two fictional local businesses, Café Sol and Bread & Butter Bakery. Each business has its own employee route and product catalogue. Both feed the same Open Tab pool and activity ledger.

The contribution follows a predictable rule. A purchase moves toward the next 50-cent mark. When the total already ends in .00 or .50, Open Tab adds €0.20 instead. The customer always sees the amount before paying.

Why small amounts can work

Research supports testing a small round-up prompt ahead of a flat donation request. A study in the Journal of Consumer Psychology found that people responded more favourably to round-up requests even when both formats asked for the same amount. The researchers linked the effect to lower perceived pain of giving. An Open Tab pilot would still need to measure its own contribution rate. Kelting et al., Would You Like to Round Up and Donate the Difference?

Everyday food purchases create repeated opportunities for that choice. The UK's nationally representative National Diet and Nutrition Survey found that 72% of participants had bought food or drink away from home during the previous seven days. Most did so once or twice that week. In its shorter food record, 17% reported an occasion involving a café, coffee shop, sandwich bar, or deli. These figures show recurring relevant transactions rather than expected Open Tab usage. UK National Diet and Nutrition Survey, 2019 to 2023

Digital checkout provides an existing place for Open Tab across the euro area. The ECB's SPACE 2024 study drew on 50,000 consumers. It reports continued growth in digital payments, with cards remaining the most popular digital method. Electronic payment acceptance increased across every euro-area country. European Central Bank, SPACE 2024

The demo menu is an illustrative local price book. It ranges from a €1.80 butter croissant to a €10.50 pasta bowl, while most drinks cost between €2.50 and €4.50. Pret's public UK delivery menu listed an all-butter croissant at £2.70 and a flatbread at £6.15 on September 7, 2026. This comparison supports the general purchase scale rather than a claim about average European prices. Pret A Manger delivery menu

At that scale, cents accumulate quickly. If 100 eligible checkouts contributed an average of €0.25, the pool would receive €25 in one day. With 200 eligible checkouts at the same average, it would receive €50. These examples are arithmetic scenarios. Real results depend on checkout volume and customer participation, with local pricing and programme rules also shaping the total.

For a participating business, Open Tab could create community affinity without requiring a points programme. Regular customers can see that their small contribution has a local use, giving them a reason to feel connected to the venue. That loyalty effect remains a product hypothesis. A pilot would need to measure merchant willingness alongside customer return behaviour.

Demo

)

Live employee views:

Customer terminal: Open Customer Checkout

Keep an employee view open and place Customer Checkout beside it.

Contribute to Open Tab

Choose products on the employee screen and create a checkout. The customer terminal receives the order. Select the round-up option and watch the shared pool increase on the employee dashboard.

Use the shared pool

Create a fresh checkout and select Use Open Tab on the customer terminal. Available choices adapt to the purchase and current pool balance. Apply one choice, pay the remainder, then return to the employee screen to see the receivable and updated activity.

Payments are simulated for this challenge. The persisted accounting lifecycle models how contributions and assisted purchases move through the system.

Code

Source: github.com/Thegm26/open-tab

The key accounting transition is authorization. It locks the shared scenario and order before checking available funds. An idempotency record makes a safe retry return its original result.

select * into s
from public.demo_scenarios
where id = c.scenario_id
for update;

select * into o
from public.orders
where id = c.order_id and scenario_id = s.id
for update;

out := public.ot_idempotency_replay(s.id, 'authorize', p_key, p_hash);
if out is not null then
  return out;
end if;

select s.settled_pool_cents - coalesce(
  sum(amount_cents) filter (
    where status = 'authorized' and expires_at > v_now
  ), 0
)
into v_available
from public.fund_reservations
where scenario_id = s.id;

if p_amount > v_available then
  raise exception 'INSUFFICIENT_POOL';
end if;

How I Built It

Open Tab uses Next.js with TypeScript. Employee routes provide the point-of-sale controls for each business. Customer Checkout follows the newest order and updates as its payment state changes.

Supabase provides persistent Postgres storage. Every monetary value uses integer cents, which avoids floating-point accounting errors. Transactional RPC functions own the important balance changes.

A round-up creates a pool credit only after simulated payment succeeds. When someone requests help, Open Tab creates a short-lived claim and reserves the chosen amount. The purchase total sets the ceiling. Pool availability and server policy can reduce it further.

An assisted purchase creates a merchant receivable for the amount covered by Open Tab. Employees can settle outstanding receivables from the dashboard. Refunds preserve the split between customer money and pool money. Eligible funds return to the pool, while a refund after settlement creates recovery debt.

The app uses idempotency keys with request hashes for payment-sensitive operations. A retry with the same input returns the recorded result. Reusing that key with changed input fails safely.

The interface is responsive across phone and desktop layouts. Activity pagination keeps a longer ledger readable, while separate customer and employee views make the live checkout loop easy to follow.

The automated suite currently passes 40 tests across 7 files. It covers the reservation lifecycle, refund accounting, settlement behavior, and repeated requests. The production build also passes TypeScript validation.

This remains a focused hackathon simulation. It uses one shared terminal lane for the newest order. A production POS integration would assign terminal lanes to specific merchant devices and connect them to a payment processor.

The part I cared about most was preserving dignity at checkout. Customers see a quiet, ordinary choice. Underneath that choice, the ledger protects funds that another person may rely on.

K8s: Node Maintenance & Eviction

George Michalakis — Sun, 06 Sep 2026 17:17:06 +0000

If you read my previous posts on topology spread and the affinity club, we mostly talked about Pod placement: which nodes can accept a new Pod, and how topology spread constraints keep replicas balanced.

But clusters consist of nodes, and nodes need maintenance too. A worker node may need an operating-system upgrade, a kernel update, more capacity, or replacement hardware.

“Okay, then delete it lol,” right?

Sure, if you are okay with the people calling those services starting to scream >:)

Before taking a node out of service, we need to move its workload safely.

That raises three related questions:

How do we stop new Pods arriving on the node?
How do the Pods already running there leave?
How many of those Pods is it safe to interrupt at once?

The first two are handled by cordon, drain, and eviction.
For the third, read the PodDisruptionBudget post ;)

Cordon: stop new placements

kubectl cordon worker-1

Cordoning marks a node as unschedulable. The scheduler will not place new Pods there, but the Pods already on the node keep running.

Think of it as closing a hotel to new guests: the guests already in their rooms are still there.

To make a node schedulable again later:

kubectl uncordon worker-1

Drain: prepare a node to go out of service

kubectl drain worker-1 --ignore-daemonsets

kubectl drain first cordons the node, then tries to evict its eligible Pods. Controllers such as Deployments and StatefulSets then create replacement Pods, which the scheduler can place on other suitable nodes.

Why `--ignore-daemonsets`?

In our case, kubectl drain stops before evicting the web Pods because it encounters DaemonSet Pods: kindnet and kube-proxy.

DaemonSet Pods are intended to run on every applicable node, so drain refuses to remove them by default.

--ignore-daemonsets tells drain to leave those Pods in place and continue evicting eligible workload Pods.

Those DaemonSet Pods remain until the node itself goes offline or is removed. That is exactly what we want during the drain:

networking / node-level services stay available while the "regular" workload leaves.

But wait... did you see what the command says?

Evicting pod...

Why evicting instead of deleting?

Eviction: removing pods in a graceful / policy-aware manner

When possible, kubectl drain uses Kubernetes’ Eviction API rather than directly deleting a Pod.

An eviction asks Kubernetes to terminate a Pod gracefully and subject to cluster policy.

The Pod receives its configured terminationGracePeriodSeconds, giving the application time to shut down. Whether it stops receiving traffic and completes cleanup safely depends on the workload’s readiness handling, lifecycle hooks, and termination behavior.

Most importantly for the PodDisruptionBudget post, the API checks whether a PodDisruptionBudget permits the disruption.

In a maintenance scenario, the tool should use eviction so availability safeguards are respected.

Planned versus unplanned disruption

Node maintenance is a voluntary disruption since an administrator intentionally asks Pods to leave a healthy node.

However:

A node crash
power failure
network partitions

are all involuntary disruptions...

At this case Kubernetes cannot ask permission before a failed node becomes unavailable.

PodDisruptionBudgets protect only against voluntary disruptions. They cannot prevent a machine from failing, but they help us avoid making an existing incident worse while performing planned work.

K8s: Topology Spread

George Michalakis — Sun, 30 Aug 2026 16:27:11 +0000

Following the previous article, where we were introduced to the affinity club, we concluded that if:

We apply pod anti-affinity to our critical service.
We have only two worker nodes.

We are “safe” if one node fails, but we cannot scale beyond two replicas during a traffic spike or another period of distress.

This is where topology spread constraints come into play.

Before continuing, it helps to remember what the Kubernetes scheduler does: whenever a new Pod needs a home, it filters out unsuitable nodes and then chooses among the remaining candidates.

Topology spread constraints participate in that decision; they do not move Pods that are already running.

In our web Deployment, we add the following constraint:

topologySpreadConstraints:
  - maxSkew: 1
    topologyKey: kubernetes.io/hostname
    whenUnsatisfiable: DoNotSchedule
    nodeAffinityPolicy: Honor
    nodeTaintsPolicy: Honor
    labelSelector:
      matchLabels:
        app: web

Let’s dissect it one field at a time.

`maxSkew: 1`

maxSkew defines the largest permitted difference in the number of matching Pods between topology domains. In our case, each worker node is a topology domain.

For two worker nodes, the possible distributions look like this:

`worker`	`worker2`	Allowed?
1	1	✅
2	1	✅
2	2	✅
3	1	❌
3	0	❌

If the difference is greater than 1, the distribution is not allowed. A new Pod that would violate this rule remains Pending.

`topologyKey: kubernetes.io/hostname`

The topology key tells the scheduler how to divide the cluster into topology domains.

Because kubernetes.io/hostname normally has a unique value on each node, the scheduler spreads matching Pods across individual nodes. In a larger cluster, we could instead spread across zones by using a label such as topology.kubernetes.io/zone.

Node inclusion policies

nodeAffinityPolicy: Honor
nodeTaintsPolicy: Honor

These fields control whether node affinity and taints are respected when the scheduler decides which topology domains participate in the skew calculation.

nodeAffinityPolicy: Honor has no practical effect in this experiment because the web Pods do not define a nodeSelector or node affinity. nodeTaintsPolicy: Honor, however, matters because our nodes have taints.

`nodeTaintsPolicy`

It controls whether node taints are considered when the scheduler calculates the topology spread.

In our Kind cluster, the control-plane node has a NoSchedule taint that the web Pods do not tolerate.

With nodeTaintsPolicy: Honor, the scheduler respects that taint and excludes the control-plane node from the spread calculation. It therefore calculates the distribution using only worker and worker2.

Without Honor

Without Honor, the default policy is Ignore. The control-plane node could then be counted as an empty topology domain even though the web Pods cannot actually run there.

A distribution such as 1 / 1 / 0 could make the next Pod violate maxSkew: 1 and remain Pending.

Honor does not add a taint or evict existing Pods. It only controls which nodes participate in the topology-spread calculation.

`whenUnsatisfiable: DoNotSchedule`

If scheduling a Pod would violate maxSkew, the scheduler leaves it Pending.

In other words, DoNotSchedule prioritizes satisfying the spread constraint over scheduling the Pod immediately.

`labelSelector`

labelSelector:
  matchLabels:
    app: web

The label selector determines which Pods are counted when calculating the distribution.

We are adding the constraint to a Deployment, so shouldn’t Kubernetes automatically count all Pods from that Deployment? No. The scheduler counts Pods whose labels match this selector. The web Pod template must therefore carry the matching app: web label.

I know it feels a little weird. You can inspect the result visually with Headlamp.

Let’s see what we did:

With four replicas, the scheduler places two Pods on each worker.

Now suppose worker2 needs maintenance. kubectl cordon worker2 prevents new Pods from being scheduled there; kubectl drain worker2 would cordon it and then evict eligible Pods. In this demo, we recreate the web Pods after cordoning to force the scheduler to make the placement decision again.

In our cluster, the cordoned node receives the node.kubernetes.io/unschedulable:NoSchedule taint. With nodeTaintsPolicy: Honor, the scheduler excludes that node from the spread calculation.

Because we have not set minDomains, worker becomes the only eligible topology domain. If it has enough capacity, all replacement Pods can be scheduled there. maxSkew is therefore still satisfied: there is only one eligible domain to compare.

But in the second case, did we hide the issue under the carpet?

Yes and no.

With maxSkew: 1, we wanted to say:

If one worker disappears, do not keep stacking replicas on the other one.

But that is not what the manifest currently says. It only limits skew across the topology domains that participate in the calculation.

To require at least two eligible domains, we add minDomains: 2:

topologySpreadConstraints:
  - maxSkew: 1
    minDomains: 2 # Require at least two eligible domains (workers)
    topologyKey: kubernetes.io/hostname
    whenUnsatisfiable: DoNotSchedule
    nodeAffinityPolicy: Honor
    nodeTaintsPolicy: Honor
    labelSelector:
      matchLabels:
        app: web

When fewer than two eligible domains remain, Kubernetes treats the global minimum Pod count as zero when calculating skew.

Below, we scale the Deployment to five replicas and compare two scenarios.

First, worker2 is cordoned. With only one eligible domain and minDomains: 2, Kubernetes schedules one Pod on worker; the other four remain Pending because placing another Pod would violate maxSkew: 1.

After I uncordon worker2, both domains become eligible again and all five Pods run with a balanced 3/2 distribution.

This is the difference between maxSkew and minDomains:

maxSkew controls balance across eligible domains, while minDomains specifies how many eligible domains must exist before Kubernetes permits further placement. It preserves the intended topology, not application availability by itself.

What comes next?

We now know how to control where new Pods may be scheduled, but maintenance introduces another question: how many running Pods may Kubernetes voluntarily evict at the same time?

Eviction? Maintenance? Why do we care?

Read about PodDisruptionBudgets (PDBs), and let's find out together :D

K8s: The Affinity Club

George Michalakis — Sun, 16 Aug 2026 10:26:02 +0000

Introduction

If you have fiddled with Kubernetes long enough to worry about which node your Pods are actually running on, you can probably relate.

First: what does affinity even mean?

Affinity: a strong feeling that you understand or like someone or something; a close relationship between people or things with similar qualities.

Okay. Fair enough.

In Kubernetes, affinity is a family of scheduling rules:

Node affinity defines hard requirements and soft preferences for which nodes can run a Pod.
Pod affinity lets us place a Pod near other Pods.
Pod anti-affinity lets us keep Pods away from other Pods.

So, loosely, if I were a Pod, I would say:

“I have an affinity for being near or away from these Pods.”

But why care?

At the end of the day, I can always scale to more replicas. I’m safe… right?

Let’s see it in action

Let’s take the worst-case scenario.

Imagine a cluster with two worker nodes. We have a critical service, but all of its Pods happen to be scheduled on worker-1.

Traffic grows, so we scale the Deployment. But every new replica still lands on worker-1.

After scaling, two things become obvious:

worker-1 is becoming stressed.
If worker-1 fails, every replica fails with it—and the application is down.

The scheduler is not random, but without a placement rule, it has no obligation* to spread our replicas across workers.

In this scenario, worker-2 is right there... empty..

Ok. Can we force Kubernetes to keep replicas of the same service on different workers?

Yes. That is exactly what pod anti-affinity is for.

Below, we apply pod anti-affinity to our critical service’s Deployment.

Before: no placement rule

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
  namespace: drainlab
spec:
  replicas: 2
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      containers:
        - name: nginx
          image: nginx:1.27-alpine
          resources:
            requests:
              cpu: 250m
              memory: 128Mi
          ports:
            - containerPort: 80

After: hard pod anti-affinity

apiVersion: apps/v1
kind: Deployment
metadata:
  name: web
  namespace: drainlab
spec:
  replicas: 2
  selector:
    matchLabels:
      app: web
  template:
    metadata:
      labels:
        app: web
    spec:
      affinity: # <-Magic starts to happen here
        podAntiAffinity: 
          requiredDuringSchedulingIgnoredDuringExecution:
            - labelSelector:
                matchLabels:
                  app: web
              topologyKey: kubernetes.io/hostname # <-finishes here
      containers:
        - name: nginx
          image: nginx:1.27-alpine
          resources:
            requests:
              cpu: 250m
              memory: 128Mi
          ports:
            - containerPort: 80

This tells the scheduler:

requiredDuringScheduling “A new app: web Pod cannot be scheduled onto a node that already runs another matching app: web Pod.”

If every eligible worker already runs one, the new Pod stays Pending rather than placing two replicas on the same node.

More specifically:

requiredDuringScheduling: if no valid worker exists, the new Pod stays Pending.
IgnoredDuringExecution: Kubernetes does not evict an already-running Pod merely because later changes violate the anti-affinity condition.
topologyKey: kubernetes.io/hostname: each worker node is treated as a separate failure domain.

But wait… if I have two eligible worker nodes and need four replicas, do the other two remain Pending?

Before anti-affinity, all four Pods could run on worker-1, even though one node failure would take down the entire service.

Now, Kubernetes protects us from that false sense of safety but hard pod anti-affinity limits us to one matching Pod per worker.

So we gained failure isolation, but we gave up that easy scaling?

No, This is where topology spread constraints come in.

*Kubernetes may already prefer to spread Pods using soft scheduling preferences. Exact placement depends on available resources and scheduler configuration. This example demonstrates why relying on a preference is different from declaring a hard availability rule.

Labs / Visualizations for this article can be found here

Save yourself from Architectural Amnesia: ADRs

George Michalakis — Sat, 14 Mar 2026 02:03:07 +0000

When you see it...

From smaller teams to larger ones, from the senior SWE managing the entire backlog to EOs, POs, and SMs juggling overlapping responsibilities, I have often found myself in meetings or PR discussions nitpicking scope details and suddenly realizing one of two things:

I disagree with the broader implementation picture.
I do not even remember whether I agreed with it in the first place.

That second one is worse.

For context, I am working in a SAFe Scrum setup, so these roles and handoffs are a very real part of day-to-day delivery.

Half-measures (Best-case scenario)

"Uhh, there is a Confluence page about this decision. We had a meeting for that."

Clicks the link.

Scans a page with 10 comments (8 resolved, 2 still open).

OK, this makes a bit more sense now.

Still, I do not remember what we said. I do not remember how long it took, and it probably took longer than it should have.

Even in this best-case scenario, I am still left with two problems:

I do not remember the back-and-forth, and some of it was probably important.
If I now have a different opinion, I really do not want to reopen the topic. That usually means more meetings, more pages, and more comments. Atlassian may be doing a great job with version control, but I do not want to be stuck restoring version 23 of a Confluence page that nobody will care about two weeks later.

Give credit where it is due

That does not mean Confluence is useless.

Architects, PMs, and business stakeholders need version control, comments, and discussions too. You cannot expect a product owner:

To log in to GitHub every time they want to sync with the architect on whether the team is migrating the DB.
To align on the confidence level of PI objectives with different POs inside a pull request.

Confluence has its place.

But at the same time, nobody wants to spend all of this just to discuss something like a new or existing PR label:

10 minutes to raise it during the daily stand-up
5 minutes to schedule a call
20 minutes to prepare a page explaining the current state and the proposal
35 minutes for the meeting itself
20 minutes for the notes afterward
20 minutes updating the page with the latest comments and decisions

And yes, those numbers are completely realistic.

Architecture Decision Records

This is where ADRs help.

An ADR is a lightweight record of an important technical decision: why it was needed, what options were considered, what was chosen, and what tradeoffs came with that choice.

At its simplest, it is just a markdown file living in your repo, somewhere like this:

docs/
  adrs/
    0001-use-topic-a.md

That is basically it.

A small document, committed with the code, with sections such as:

Context: what problem are we trying to solve?
Decision: what did we choose?
Alternatives considered: what were the other realistic options?
Consequences: what do we gain, and what do we give up?
Status: proposed, accepted, superseded, deprecated

Nothing fancy. Just enough to preserve the reasoning behind a technical decision close to the codebase where engineers will actually look for it.

Basic rules

Keep ADRs for technical topics that are likely to be searched while someone is working in the repo. If you used a specific pattern, tool, or extension, I would much rather Ctrl+F the repo and find the reasoning in the docs than dig through a GitHub page or old meeting notes.
Make the person opening the PR the driver of the discussion. They should gather feedback, collect comments, help the team converge on a decision, and eventually merge or close the PR with the ADR alongside the change.
Do not optimize for unanimous agreement. Optimize for a clear decision with explicit tradeoffs and enough context that the next person can understand why it happened.

That is the real value: not perfect documentation, but recorded reasoning close to the codebase.

If you want a good collection of ADR templates, look here.

PS1: Use this as a starting point for introducing ADRs to your team.

PS2: An agent helped with syntax refactoring. The expressions, the main writing, the flow and the pain is mine :)