DEV Community: maxmoffa

wakey-claude: surviving the Claude Code 5-hour usage window

maxmoffa — Mon, 06 Jul 2026 11:17:46 +0000

The problem: the 5-hour wall

If you use Claude Code on a Pro or Max subscription, you know the drill. You're deep into a long refactor, the agent is mid-flow, and then the 5-hour usage window runs out. The session stops, context evaporates, and whatever the agent was doing is left in an undefined state.

The usual "solutions" are all some flavor of babysitting: watch the usage percentage in the status line, guess when the reset happens, keep a mental note to come back, or set up a cron job / at task that blindly restarts something at a hardcoded time. All of them put the burden on you, and none of them solve the real problem: the agent loses its train of thought exactly when it's most expensive to lose it.

What I wanted was different: the session should notice by itself that the limit is close, write down where it is, and come back on its own when the window resets — no cron, no external scheduler, no human alarm clock.

That's wakey-claude.

"Wakey wakey, it's time for school" — except it's your usage window resetting.

The idea: an alarm, not a babysitter

The core design decision is that wakey-claude is event-based, not state-based. Nothing runs in the background, nothing polls, and nothing is written to disk until usage actually crosses the threshold. When it does, the thing that gets written is a one-shot alarm — a tiny flag file — not continuously-updated state.

This matters because both hook points that Claude Code offers run very often:

the statusLine command re-renders constantly;
a PreToolUse hook fires before every single tool call.

If either of them did real work on every invocation, you'd pay for it on every render and every tool call. Instead, each piece does the absolute minimum and the flag file is the only communication channel between them.

The flag file lifecycle — from armed to handled to deleted, once per 5-hour window

How it works

Three pieces cooperate:

1. The sensor: `usage-statusline.sh`

Claude Code pipes its status JSON into the statusLine command on every render. The script prints the usual one-line summary (model, 5-hour usage %, context usage), but it also acts as a threshold sensor: when rate_limits.five_hour.used_percentage crosses the threshold (default 95%, configurable via USAGE_GUARD_THRESHOLD), it raises the alarm by writing ~/.claude/wakey-flag.json:

{
  "resets_at": "2026-07-06T15:00:00Z",
  "usage": 96,
  "handled": false,
  "created_at": "2026-07-06T10:47:12Z"
}

Below threshold it writes nothing. And if a flag for the current window's resets_at already exists, it writes nothing either — this dedup guard is deliberate, because an unconditional overwrite would silently re-arm an alarm that already fired.

2. The consumer: `usage-guard.sh`

The PreToolUse hook is a dumb one-shot consumer. No flag file → no-op, exit 0, the tool call proceeds. If the flag exists and hasn't been handled, the guard blocks the tool call exactly once, flips handled to true, and uses the blocked-call feedback to tell Claude what to do: checkpoint your progress, schedule a native wakeup, stop starting new work.

If the flag is already handled, or its window has already reset, the guard passes through (deleting an expired flag as it goes).

3. Claude itself

This is the part I like most: the checkpoint and the wakeup are delegated to the agent, not implemented in bash. When the guard blocks it, Claude:

writes a PROGRESS.md describing exactly where it is and what's left;
schedules a native one-time wakeup for resets_at + 3 minutes;
stops.

When the wakeup fires, Claude reads PROGRESS.md and resumes exactly where it left off. The bash side never needs to know how to schedule anything on your OS — the agent figures that out, which is precisely the kind of glue work agents are good at.

Claude writing its checkpoint and scheduling a wakeup at the window reset

The flag file lifecycle

The whole protocol fits in three states per 5-hour window:

State	Who sets it	Meaning
written (`handled: false`)	statusline	usage crossed the threshold, alarm armed
handled (`handled: true`)	guard	Claude was told to checkpoint and schedule the wakeup
deleted	guard / next crossing	window reset, ready for a fresh flag

A corrupt or unparseable flag can't serve as either an alarm or a dedup key, so it's treated as "expired" by the guard (deleted, fail open) and as "no flag" by the statusline (overwritten). Since the statusline runs far more often than the guard, the file self-heals on the next render.

Fail open, always

A hook that runs before every tool call has one non-negotiable property: it must never accidentally lock you out of your own session. Every "can't tell / don't know" path in the guard exits 0:

jq missing → pass through;
flag unparseable → delete it, pass through;
resets_at missing or in the past → delete it, pass through;
already handled → pass through.

The only path that blocks is the happy one: a valid, unhandled flag for a window that hasn't reset yet. And it blocks once — the handled boolean is the dedup mechanism.

Install

npx wakey-claude install

This copies the two scripts into ~/.claude/hooks/ and merges the statusLine and PreToolUse entries into ~/.claude/settings.json, backing it up first and leaving your existing hooks untouched. uninstall removes only what it added, and status tells you what's installed and whether an alarm is currently armed.

It also works per-project:

npx wakey-claude install --project          # shared with the team, committed
npx wakey-claude install --project --local  # personal, gitignored

Project-scope settings reference the scripts via $CLAUDE_PROJECT_DIR instead of absolute paths, so they survive moving or cloning the checkout — and install --project gitignores the flag file for you, because a one-shot alarm is transient state, not something to commit.

When (not) to use this

Like every small tool, it has a specific shape of problem it solves.

✅ Long interactive sessions on a Pro/Max subscription, where losing the agent's context mid-task is the real cost.
✅ Teams that want the same guard shipped to everyone via a committed .claude/ directory.
❌ API-key logins — rate_limits.five_hour is simply not populated, the status line shows n/a and the guard never triggers.
❌ Headless or CI environments — there's no interactive session to pause, and no statusline render loop to raise the flag.
❌ Machines that sleep — the session process must stay alive for the scheduled wakeup to fire. A closed laptop lid or a dead SSH/tmux session silently prevents the resume.

Claude waking up and picking up from PROGRESS.md

Try it

The project is on GitHub: MaxMoffa/wakey-claude. It's small — two bash scripts, a Node CLI for install/uninstall/status, and a test suite covering both — with jq as the only runtime dependency on the bash side.

Feedback, issues, and PRs are very welcome — especially if you've found a different way to survive the 5-hour wall and want to compare notes.

MaxMoffa / wakey-claude

"Wakey wakey, it's time for school" — except it's your 5-hour usage window resetting.


              z Z
        \ | / z
     ' -(u_u)- ' ______________________
        / | \.-'  ~   ~   ~   ~   ~  '-.
       (pillow)________________________/

 _    _   ___   _   __ _____ __   __
| |  | | / _ \ | | / /|  ___|\ \ / /
| |  | |/ /_\ \| |/ / | |__   \ V / 
| |/\| ||  _  ||    \ |  __|   \ /  
\  /\  /| | | || |\  \| |___   | |  
 \/  \/ \_| |_/\_| \_/\____/   \_/  
 _____  _       ___   _   _ ______  _____ 
/  __ \| |     / _ \ | | | ||  _  \|  ___|
| /  \/| |    / /_\ \| | | || | | || |__  
| |    | |    |  _  || | | || | | ||  __| 
| \__/\| |____| | | || |_| || |/ / | |___ 
 \____/\_____/\_| |_/ \___/ |___/  \____/

wakey-claude

…

View on GitHub

The brain freeze between us and AGI

maxmoffa — Thu, 02 Jul 2026 21:10:00 +0000

Imagine growing up with the same brain you had when you were 10 years old: same knowledge, same experience. You would probably embrace life without asking too many questions, but you would never become the best version of yourself.

I have been spending these months thinking about AI, using it and trying to look ahead at the end goal. The obvious question is: “what’s next?” AI models like Claude Mythos and many others are getting much smarter than their first versions. I remember talking with a colleague last week about how “stupid” they used to be looking back, and now the models we use every day feel much sharper and more coherent. The point here is that they improved in just a few years, across different versions that were mostly human-made. Maybe, if they started improving themselves, we might reach AGI faster.

What is AGI?

So what is AGI exactly? AGI stands for Artificial General Intelligence, and the keyword here is “general”. The models we use every day are incredibly smart but in a way they are still specialists, great at the tasks they were trained for but not really able to understand the world the way we do. An AGI would be a different beast, a model able to learn, reason and adapt to any kind of problem you throw at it, even the ones it has never seen before, exactly like a human being would. For me this is the real finish line, not a model that already knows everything, but one that can learn anything on its own, without waiting for the next version to come out.

What do I mean by human-made?

These are human-made models for me because there are still, nowadays, a few parts of a model’s training process where we (assuming you are not an agent) are required, and I feel like this is the main reason we don’t have AGI yet. I read an article from Anthropic about this and they were saying that AI models are improving their capabilities and are now able to improve themselves in many phases, but there are still huge architectural choices made by humans, and a lot of the problem-setting and the judging of results is done by flesh and blood.

The evolution of AI development, from simple chat to a closed self-improvement loop. Diagram inspired by Anthropic’s “When AI builds itself”

I have been using the Playwright plugin with my Claude subscription and I have noticed a huge spike in autonomy: when they understand the problems and recognize them, they are able to fix these “bugs” most of the time. I’m actually using it while I write this article, I asked Claude to build a new feature in my platform, it built the feature and then tested it. After this it noticed from the test that something wasn’t working, and it instantly knew the task needed more digging. Then I wondered what could happen if a model could remember its errors right away and critique its own choices and by “remember” I don’t mean its context, which it loses once the session ends.

Probably Claude and all the other frontier models still have to learn to be self-critical. This skill helps us humans improve when we are dealing with new things and stepping out of our comfort zone, but in order to improve we need to be able to do it on our own, without waiting for someone else to be part of the process. AI needs a neuroplastic brain.

What does neuroplastic mean, and why is it so important?

We humans (or should I say animals) have the best architecture that mother nature could bring to the table: we are autonomous machines able to understand ourselves and what we need in order to survive. After many years of evolution behind us, we have been able to adapt to the fast-changing world we live in. Our brain is able to understand how everything works and adapt to it, continuously.

This continuous adapting and self-improving process has been possible thanks to our neuroplastic brain. Neuroplasticity is our brain’s ability to change its own structure and functions based on our experiences, knowledge and life. This is the missing block in AI’s capabilities, the one that will make AI grow even faster than it did this last year.

Before going further, I need to draw a line that often gets blurred. Learning continuously is one thing; becoming aware of what you learn is another. The first is an engineering problem: how do we let a model update its own weights from new experience without breaking what it already knows? The second is a much deeper, still open question about consciousness and identity. In this article I'm talking about the first one. I see continual learning as a necessary step toward something more human-like, maybe even a necessary condition for it, but not a sufficient one. So when I say AI needs a neuroplastic brain, I don't mean it will suddenly feel or know it exists. I mean it should stop being frozen, and start changing with the world it lives in. Whether that ever turns into real awareness is a different story, and honestly one I can't promise.

The AI model we are using is a frozen brain

The new models are learning many things nowadays, there’s a new version almost every month, they are improving very fast but they still can’t keep pace. When new AI models come to life they learn a lot of new stuff: the knowledge ranges from coding to biology, literature to math and so on. Once they finish their training phase, the new monster gets tested, and once everything checks out the brain gets frozen. It’s not literal, obviously, but the brain gets locked in that state: when you are using a model, let’s say Opus 4.8, it experiences new concepts and ideas every day through your chats, but that knowledge doesn’t become part of its capabilities or its ‘approach to life’.

Why is the brain frozen?

You might be asking, why do they freeze it? That might feel like something stupid but there are a number of reasons. First, you keep control of it: if you remove the leash, it might become something that the creator didn’t want to build or didn’t imagine, and if a company releases a product that might change, for better or for worse, without their will, it could be risky. But the biggest risk with continual learning nowadays is something called “catastrophic forgetting”.

When these neural networks learn something, they write this knowledge inside their weights, which we can say are the blocks which make the brain. Now when something new gets taught to the model, those same weights get updated (you don’t get new weights for new things), so old knowledge might get overwritten, and this leads to the model forgetting something it learnt in the past. There are techniques to mitigate this major flaw during the creation process, looking mostly at each weight or with other options, but these instruments aren’t enough yet for a continual learning brain.

The AI approach

To be fairly honest, they have a few ways to learn things while we chat with them. Beside the context window, which is temporary memory, they can store new info about us and how we work using markdown files, or in the most advanced configuration with a database of some sort. These are external instruments that the LLM can use to access context and so keep track of the things it does.

Let’s imagine an AI model like a black box: we give an input on one side, then something happens inside the box and we get an output from the other side. What happens inside is what we are talking about. Inside there is the “real brain” that we are trying to upgrade continuously; when we use files and databases we are not talking about something inside that box, but about the instruments the box can use.

As an example, we can say the box is like us: it can sort of think and receive inputs and outputs, while markdown files and databases are like a book. We can read it if we need to do something related to its content, but it’s not necessarily something that remains inside of us. It’s worth being precise here: during training the box did learn like us, absorbing knowledge into itself, but once frozen it can only rely on the book.

I’ll go even deeper with the example. Let’s say the book is a dictionary: we find a new word we have never seen before and decide to look it up. Once we get to it, we can read what it means and understand. Now let’s say we do that with multiple words. Time has passed, and now, without the dictionary, we can still understand the meaning of a few words we read in that book, while maybe we totally forgot the meaning of others we looked up the same way. An AI model couldn’t remember any of those words; it will always need the book, which in the AI context means the files and the databases.

What we experience doesn’t go only into our memory, it goes much deeper into our brain. This affects us very deeply and changes the way we interact with the world, something that a context window loaded with the same data can’t do: it changes what we are.

What are they doing in this direction?

The Anthropic article I mentioned before (you can find it in the links below) says a lot about this topic and about how AI models evolve. We started a few years ago with a simple chat, then we started building the harness around the model to make it smarter, until we got to agents and then to the agent-orchestration level. Now we are able to launch multiple instances of AI agents working together on the same project. The models have become so much better than the early versions that they are able to take part in generating the new versions of themselves, but not completely.

The next step, it seems from the article, will be closing the loop.

Closing the loop

Once the loop is closed the AI models won’t need us anymore to help them become better, we’ll become only users; only the infrastructure will need to be maintained by us, at least until AI gets a body. I don’t want to create an illusion, I respect you for reading my thoughts, but this isn’t a fully neuroplastic brain, because it still requires a full process like the one they are running today, so this loop isn’t fast enough. We learn every day and everywhere and sometimes we don’t decide what life is teaching us, at this stage AI is still being built in a lab, not in the real world. To gain neuroplasticity we need to embed the loop.

Embedding the loop

Embedding the loop means that AI will gain its neuroplastic skill and will be able to learn new things continuously, every day, without any human input. It means that the speed we are used to seeing between model versions will increase so drastically that it probably won’t be smart to keep giving it a version number. This means one step ahead in its evolution cycle; and again, this doesn’t mean consciousness, but the path is probably the right one. In order to gain this kind of loop, we need models able to dynamically update their weights, the ones they use inside to build the answers to our questions.

And now the big question, how? Going back to neuroplasticity, a human brain doesn’t engrave everything it gets to interact with in real time, this information is temporary in our memory, let’s say like a big context. The real moment the brain goes back to this temporary data is while we are sleeping, that’s where our “inner weights” get updated. OpenClaw, if you are reading this you probably know what I am talking about, already has something similar at harness level: there is a dreaming phase where it cleans its own memory and organizes it, but it doesn’t touch the weights, it’s just updating markdown files. Imagine if all of us got to have a “child model”: all of them start from the same knowledge but each one grows differently because it is having different experiences, and they could have a second model for dreaming that helps cleaning the temporary stuff and updates the weights carefully: consolidation instead of real-time engraving, which is exactly how you avoid catastrophic forgetting. A dreaming model. This idea reminds me of the movie “I, Robot” (2004), when Sonny (the conscious android) tells the detective about his dream and Detective Del Spooner, played by Will Smith, says that robots can’t dream. And no, giving models a dreaming phase won’t make them Sonny, but it might finally let them wake up a little different from yesterday.

Sonny during the interrogation scene in “I, Robot” (2004), © 20th Century Fox

And the AGI?

Last but not least, AGI is the end goal of this futuristic gold rush. I’m not gonna say when and how AGI will be among us, no one has the ability to imagine a date for it yet, but I can say pretty easily that achieving the neuroplastic skill and letting AI models run free might be dangerous or might be epic. Remember the 10-year-old brain from the beginning? Imagine being born with all that knowledge: you probably knew how to solve simple math problems, write, read and interact with people; then you go on with your life and become a young adult at 30, but with the same brain you had 20 years before, the same emotions and capabilities. How would you interact with the world? Would you even be conscious enough of what’s happening around you? Even if you got an update at 20, after a year it would be already outdated. We need to keep learning, improving and understanding ourselves more.

Maybe, going back to the version number of AI models, it might not be as useless as I said before; it will just turn into its age.

References

The beauty of modularity: a discipline of looking, not building

maxmoffa — Fri, 08 May 2026 16:28:00 +0000

Every developer knows it: divide et impera, simplify and execute. There's nothing more fascinating, in computer science, than the ability to break down a complex task into simpler, more intuitive ones — it's the foundation on which every problem, every program, every line of code is built.

Starting from this observation, I want to try to tell what fascinates me about making things modular and composing them to build something bigger. I try to apply this principle in every project I work on, so I can reuse what I write as often as possible: I can't stand throwaway code, written to run in one specific case and then die. There are contexts where it's unavoidable, but where it can be avoided I think it's worth doing.

What do I mean by "modular"?

When I say something is modular, I don't just mean it's "broken into pieces." I mean it's made of autonomous units that can live and change without dragging the rest along.

For me, a module always has three traits:

Clear boundaries: it's clear what's inside and what's outside, and what it's responsible for. This reduces ambiguity and chaos ("where does this responsibility end?").
Explicit interface: it talks to the outside through a few declared access points. In software these can be APIs, ports, events, props, CLIs, environment variables, input and output files. In real life they can be procedures, checklists, templates.
Substitutability and reuse: if you keep the interface stable, you can change the implementation or reuse the same piece across contexts without rewriting from scratch.

In practice, modularity for me is a strategy to lower the cost of change over time: if tomorrow I have to update a piece, I want to be able to do it without breaking or rewriting everything else.

Modular bricks (interlocking) – close-up

Modularity at its best (in my opinion)

When I think about modularity in the digital world, a few examples come to mind that, more than others, manage to embody its spirit: not just "breaking into pieces," but building blocks with clear boundaries, clean interfaces, and a life of their own — pieces you can combine, swap, or reuse without having to start over.

The examples I picked come from very different contexts — infrastructure, frontend, and personal productivity — and that, in my view, is exactly the point: modularity isn't a feature of a language or a framework, it's a way of thinking that shows up at every level of the stack. In each of these cases I like to look at two things:

what is being made modular (the process, the component, the unit of content);
how it's being made modular, meaning which "boundaries" actually make that piece independent.

Docker

I like to picture Docker containers as hot-swap cards: closed, self-contained objects you plug in or pull out without shutting the system down. Each container carries its own code, runtime, libraries, and configuration, and exposes itself only through a clean interface: ports, volumes, environment variables.

This image, I think, captures Docker's modularity well:

Clear boundaries: what happens inside stays inside, which kills off most of the "works on my machine" pain.
Substitutability: you can swap a container (even a database one) without touching the rest, because the interface stays the same.
Composability and reproducibility: with docker compose you assemble multiple "cards" and get the same system on a laptop, across a team, and in production.

The most interesting part is the mental shift: you don't "fix" the server anymore, you replace components like slotting in a card. The metaphor has its limits, and it's worth exploring them because they clarify what modularity can and can't promise.

But the isolation is less total than the metaphor suggests: containers share the host kernel, and portability is paid for in bloated images, slow builds, and a security surface you still have to watch.

Di Software: Docker, Inc.Screenshot: VulcanSphere - Self-taken; derivative work, Apache License 2.0, https://commons.wikimedia.org/w/index.php?curid=182060522

Module Federation

If Docker makes infrastructure modular, Module Federation brings the same spirit to the frontend: born with Webpack 5 and now available in Vite too via plugins, it lets multiple applications (even from different teams) expose and consume modules at runtime, instead of compiling one monolithic bundle. A stable shell loads pieces (components, pages, libraries) published elsewhere on the fly and composes them into a single experience.

My mental image is an app built from grafts: each remote is a deployable module with clear boundaries and an explicit interface.

Real release boundaries: each remote has its own build, pipeline, and version. Updating a piece doesn't mean redeploying the whole shell.
Reuse without duplication: a module lives in one place and is consumed wherever it's needed, cutting copies and drift across projects.
Controlled shared dependencies: common libraries (e.g., React, the design system, utilities) are negotiated between host and remote.

What's interesting is that modularity here isn't "free": it shifts decisions and responsibilities onto boundary design, failure handling, and performance. It's exactly that friction that makes you understand when runtime modularity really pays off, and when it just adds complexity.

But the price is sneaky: bugs move from build-time to runtime, version mismatches between host and remote only surface in production, and every network failure becomes a visible failure of the app.

Notion

One last shift in level: from infrastructure to frontend, now we move up to the user-facing tool. Notion is probably the example I live closest to, and it's literally the tool I'm using to write this post. The thing that strikes me most is that the same environment I'm using to put these lines together is also the one I use to run my company, build procedures, collect ideas, and organize projects: one place, many different uses, all built from the same little bricks.

My mental image is a set of composable bricks: blocks, pages, databases, and views all belong to the same family and offer clean contact surfaces to the other pieces.

Clear boundaries for each block: every element (paragraph, toggle, table, embed) is its own unit — movable, duplicable, nestable, without breaking the context it lives in.
Reuse and composition: a database can show up on multiple pages as different views, a page can be linked, embedded, or turned into a template, and the same schema works for both a blog post and a company procedure.
Same tool, different contexts: from blog posts to CRM, from meeting notes to a lab HACCP, the content changes but the mental model doesn't, and that lowers the cost of switching between activities.

The interesting point is exactly this: modularity doesn't show up in the single block, it shows up in the fact that the same "language" supports wildly different uses without ever feeling forced. It's proof that, when the boundaries are well thought out, a few base pieces are enough to cover hugely different scenarios.

But the same freedom that makes it powerful is also its Achilles' heel: without strong conventions you end up reorganizing the workspace more than actually using it, and the "right" module always seems to be one step further away.

Notion desktop (https://www.notion.com/help/notion-for-desktop)

Modularity in "real" life

You might not expect it, but modularity isn't a computer science invention: the physical and organizational world is full of remarkable examples, often so woven into our daily lives that they go almost unnoticed. Here are a few that, in my opinion, tell the same story as Docker containers and Notion blocks, just off-screen.

ISO shipping containers: same box, same dimensions, same hooks for decades. The contents change (fruit, cars, clothes) but not how they're moved, and around that single interface an entire global logistics system has been rebuilt.
LEGO bricks: a handful of piece types, an interface (the studs on top and bottom) standardized for decades, and a composition range that goes from a spaceship to the Eiffel Tower. The same piece from 1980 still snaps onto a set released yesterday.
IKEA furniture (e.g., Kallax): same cubes, same dimensions, same holes. The interface here is literally physical: the standard 32 mm hole and the cube's dimensions, constant across models and accessories. The same cube becomes a bookshelf, a room divider, a TV stand, or a vinyl holder depending on context, without the piece itself really changing.
Automotive platforms (e.g., Volkswagen's MQB): the same chassis and the same electrical architecture support the Golf, Audi A3, Skoda Octavia, and SEAT Leon. The module is the mechanical base, the interface is how the bodywork and engines attach to it.
The mother sauces of classical cooking: five bases (béchamel, velouté, espagnole, tomato, hollandaise) from which hundreds of derivative sauces come. Change one ingredient "at the interface" and you get a different dish, without starting from scratch each time.

The common thread is always the same: clear boundaries, a stable interface, and pieces you can swap without bringing down the rest. Once you start seeing it that way, modularity stops being a code question and becomes a way of looking at the world.

ISO shipping containers in a port

How do you discover a module?

The thing I like most, when I'm working on a system or a company, is that a module isn't invented — it's discovered. It's already there, inside the problem, hidden under noise, repetitions, and habits. What we call "designing a module" is actually an act of observation: it means noticing a boundary that has been there for a long time and finally giving it a name.

I like to think of it as sculpture: the marble block already contains the statue, the sculptor doesn't create — they remove what's in excess until the shape comes out on its own. In the same way, in a system or a process there are already natural fault lines — my job is just to recognize them before forcing arbitrary divisions.

To spot them, I usually rely on a few recurring signals:

Repetition: if I'm writing or doing the same thing for the third time with small variations, there's a module underneath asking to come out. My hands are already using it, it just needs to be made explicit.
Things that change together: what changes for the same reasons and on the same occasions tends to belong together; what changes for different reasons wants to be separate. It's the golden rule for figuring out where to cut.
The pain of change: if changing one small thing forces me to touch ten unrelated places, the system is telling me the boundary was drawn in the wrong spot — or hasn't been drawn at all yet.

Seen this way, finding a module looks more like archaeology than architecture: you dig, you brush, you wait for the shape to come out. And the best moment is when you realize that module had been there all along, and you just had the patience to find it.

This has happened to me concretely a couple of times. I work for a company that does environmental monitoring, and one of the things I've built is Square, our platform: the grids used to host charts, maps, and rankings written case by case, and at some point the repetition was so obvious that I extracted standard widgets — the same ones that today live indifferently inside grids, in reports, or in other contexts. Same story for a GIS-like page: the information shown on the map found its natural form as composable layers, toggleable and stackable as needed, without rewriting the map every time.

My attempt at building a "module"

I tried to apply this same logic outside of code too, with Plop, the dissolvable cube I made with some of my colleagues: the cube always stays the same, what changes is what you put inside (flavors, active ingredients), and even the liquid base you dissolve it into can vary — usually water, but milk works too if you want. Once the module is discovered, every new variant costs much less than inventing a product from scratch.

Beware the false module!

Having said all this, the opposite risk is just around the corner: once you get comfortable with modularity, the temptation is to see modules everywhere — and that's not always a good thing. The truth is that not everything has to be a module, and forcing it often makes the system worse, not better.

The two signals I watch most carefully are these:

The module used only once: if I've just extracted a "reusable" piece but the second use case doesn't exist and I struggle to really picture it, I'm probably paying the cost of abstraction (interface, configuration, documentation) without the benefit. It's the classic module born from a hypothesis, not from observation — almost always better to leave it inline until repetition shows up on its own.
The module that does too much: when the interface bloats with parameters, the docs start filling with "if… then…" clauses, and the internal logic gets hard to explain in a single sentence, I'm usually not looking at a complex module, but at multiple overlapping modules asking to be separated. It's the same signal as "the pain of change," but seen from the inside: if changing one behavior forces me to understand all the rest, the boundaries are in the wrong place.

The rule I try to keep in mind is simple: modularity has to reduce cognitive cost, not add to it. When I feel a module is making my life harder instead of simpler, it's usually not an implementation problem — it's a sign that that module, the way I drew it, didn't really exist.

What I take home

In the end, modularity for me is mostly this: a strategy to reduce cognitive cost and the cost of change over time. It's not there to make a system look more elegant — it's there to make it cost less, in attention today and effort tomorrow.

But what really stays with me, after all of this, isn't a technique — it's a habit of looking. Once you've seen the ISO container behind global logistics, the 32 mm hole behind the Kallax, and the five mother sauces behind an entire menu, you stop looking at the world as a single block and start looking for the fault lines — not to break everything, but to figure out where you can actually change something without having to rebuild the rest.

In that sense, modularity is less a property of things and more a way of reading complexity: digging until you see the boundaries that were already there, giving them a name, and then having the discipline to leave alone the pieces that, modules, weren't really. It's the price — and the gift — of looking at the world in blocks.

References

Divide et impera (wikipedia): https://en.wikipedia.org/wiki/Divide_and_impera
Modularity (wikipedia): https://en.wikipedia.org/wiki/Modularity
Coupling and cohesion (wikipedia): https://en.wikipedia.org/wiki/Coupling_(computer_programming)
Separation of concerns (wikipedia): https://en.wikipedia.org/wiki/Separation_of_concerns
Interface (computing) (wikipedia): https://en.wikipedia.org/wiki/Interface_(computing)
Docker overview: https://docs.docker.com/get-started/docker-overview/
Docker Compose overview: https://docs.docker.com/compose/
Containerization (wikipedia): https://en.wikipedia.org/wiki/Containerization_(computing)
Linux kernel (wikipedia): https://en.wikipedia.org/wiki/Linux_kernel
Module Federation (Webpack docs): https://webpack.js.org/concepts/module-federation/
Webpack 5 release (Webpack blog): https://webpack.js.org/blog/2020-10-10-webpack-5-release/
Micro-frontends (martinfowler.com): https://martinfowler.com/articles/micro-frontends.html
Notion (product): https://www.notion.so/product
Notion API (as an example of explicit interfaces): https://developers.notion.com/
ISO container / Intermodal container (wikipedia): https://en.wikipedia.org/wiki/Intermodal_container
LEGO brick (wikipedia): https://en.wikipedia.org/wiki/Lego
IKEA KALLAX series: https://www.ikea.com/us/en/cat/kallax-series-27534/
32 mm system (wikipedia): https://en.wikipedia.org/wiki/32_mm_cabinetmaking_system
Volkswagen Group MQB platform (wikipedia): https://en.wikipedia.org/wiki/Volkswagen_Group_MQB_platform
Mother sauces (wikipedia): https://en.wikipedia.org/wiki/Mother_sauce
Iodo (Plop): https://iodo.tech
Sense Square (Square): https://sensesquare.eu

Loved this setup, would be perfect to create a docker just for this

maxmoffa — Thu, 30 Apr 2026 13:42:22 +0000

Jervi

Dec 2 '25

Setup Expo Build Environment on WSL2 (Without Android Studio nor Paying Expo Credits)

#reactnative #linux #localbuild

3 min read

Android desktop mode: features, device support, and the OLED screen burn-in problem

maxmoffa — Thu, 16 Apr 2026 11:53:47 +0000

The evolution of Android has brought the dream of a true "PC in your pocket" closer to reality, especially with the advent of desktop modes on smartphones. As someone who has actively used and tested these features—most recently on my Pixel 10—I’ve seen both the productivity upside and the rough edges.

My typical setup is intentionally simple: a generic Samsung 1080p monitor, a basic Baseus USB‑C hub, and a wireless keyboard + mouse connected to the hub via a USB dongle. I usually stay in desktop mode for 2–4 hours at a time with auto brightness enabled.

The biggest issue is that the phone display stays on the whole time, often showing static UI. On an OLED panel, that’s a recipe for burn‑in risk. It also adds unnecessary heat, on top of whatever heat the desktop session itself generates.

On top of the burn‑in angle, I’ve also run into reliability bugs. Apps sometimes open on the external desktop, but if you open the same app on the phone, it can "steal" focus and effectively collapse the desktop session back into the mobile experience.

In this article, I’ll break down Android desktop mode, what devices support it, why Pixel currently has a unique OLED risk, and a temporary workaround I built: BlackTop.

TL;DR

Android desktop mode turns your phone into a multi-window desktop on an external display.
On some OLED phones (notably Pixel), the phone screen can stay on with static UI during desktop sessions, increasing burn-in risk.
BlackTop is a temporary workaround that blanks the phone display to reduce that risk while you keep working.

What is android desktop mode?

Android desktop mode is a feature that allows a compatible smartphone to project a PC-like interface onto an external display. This transforms the mobile device into a productivity workstation, supporting multiple windows, keyboard and mouse input, and advanced multitasking. The desktop environment is not just a mirrored phone screen, but a separate interface optimized for large displays, similar to what you would expect from a traditional computer.

How does it work?

The core requirement for desktop mode is support for DisplayPort Alt Mode over USB-C, which enables video output to external monitors. Not every USB-C port supports video output: some devices and cheaper hubs/cables carry data and power only.

When a compatible device is connected to a monitor (often via a USB-C hub or adapter), it launches a desktop-style UI. This interface allows users to open multiple resizable windows, use keyboard shortcuts, and interact with apps in a more desktop-like manner. Peripheral support (mouse, keyboard, Ethernet, storage) further enhances the experience.

Which devices support desktop mode?

Samsung DeX

Samsung has been the pioneer in this space with its DeX platform, available since 2017. DeX is supported on a wide range of Galaxy devices, including the latest Galaxy S25 series, Z Fold 6, and many previous flagships like the S8 through S25, Note series, and all generations of the Fold. DeX can be launched via a wired connection or wirelessly on supported TVs and monitors. It offers a mature, feature-rich desktop experience, including multi-window support, drag-and-drop, keyboard shortcuts, and the ability to use the phone as a touchpad.

Google Pixel desktop mode

With Android 16, Google introduced an official desktop mode for Pixel devices, starting with the Pixel 8, 9, and 10. When connected via USB-C to a compatible display, these Pixels can now project a desktop interface. While promising, Google’s implementation is still in its early stages, lacking some of the polish and features of Samsung DeX.

Motorola Ready For

Motorola’s “Ready For” mode provides a similar desktop experience on devices like the Moto G100, G200, and Edge+ series. Ready For can be launched via HDMI, on Windows PCs via an app, or wirelessly to compatible displays. Users praise its clean Android interface and robust performance, sometimes even preferring it to Samsung DeX.

Huawei Easy Projection

Huawei’s Easy Projection is available on many Mate and P series devices. It allows users to cast their phone’s desktop environment to an external display, with features like multi-window multitasking, file management, and quick search from a start menu-like interface. Like DeX and Ready For, it leverages DisplayPort Alt Mode over USB-C.

Other brands

Other manufacturers such as HTC (U series), Asus (ROG and Razer gaming phones), and select LG models (after 2018 updates) also support desktop mode or video output via DisplayPort Alt Mode over USB-C. Some devices offer basic screen mirroring rather than a true desktop environment, and third-party solutions like Maru OS or DisplayLink adapters fill the gaps for unsupported phones, though with limitations.

Pro tip: If your desktop mode lets you turn off the phone screen or switch it into a touchpad mode (like DeX typically does), enable that setting. It reduces static UI on the OLED panel and often lowers heat and battery drain too.

The OLED burn-in problem in desktop mode

The issue on pixel devices

While desktop mode is a powerful feature, it comes with a significant risk for devices with OLED displays: screen burn-in.

This is especially problematic on Google Pixel devices running Android 16’s desktop mode. When the phone is connected to an external display, the internal screen can remain fully on and show static UI for the entire desktop session. If you do 2–4 hour sessions regularly, that’s a lot of time with the same elements on screen.

In my case, the two most obvious consequences were:

OLED risk: the display is effectively "always on" during desktop mode, increasing burn‑in risk.
Heat: the phone runs noticeably hotter with the display permanently lit, on top of whatever load the desktop session adds.

Unlike Samsung DeX, which typically allows the phone screen to be turned off or repurposed as a touchpad, Google’s desktop mode currently lacks any first‑party option to blank or dim the device’s own display during desktop sessions. This design oversight makes desktop mode much riskier on OLED Pixels than it needs to be.

Is this issue present on other devices?

The problem is not unique to Pixel devices, but its severity and the available mitigations vary by manufacturer. Samsung DeX, Motorola Ready For, and Huawei Easy Projection all provide options to turn off or repurpose the phone’s screen when in desktop mode, greatly reducing the risk of burn-in. On these platforms, the phone’s display can usually be set to sleep, act as a touchpad, or display a screensaver.

In contrast, Google’s implementation currently keeps the phone screen always on during desktop mode, with no built-in way to blank it.

And there’s a second class of issues: stability glitches when exiting desktop mode. In my experience:

Some home screen widgets render incorrectly after you unplug, and only recover after a reboot.
In some cases, the Android status bar can freeze the phone after disconnecting. Pulling down the shade triggers a freeze, and the only way to keep using the phone is to lock and unlock it again. A full reboot fixes it more permanently.

Screenshot: widgets rendering incorrectly after exiting desktop mode (only fixed after reboot).

A workaround that reduced the odds of the status-bar freeze for me was:

Close all desktop windows.
Lock the phone screen.
Then unplug the USB‑C hub.

General screen timeout and OLED burn-in concerns

Disabling screen timeout (intentionally or because of desktop mode) increases the risk of burn-in, battery drain, and overheating on any OLED device. Best practices to avoid burn-in include lowering brightness, using dark mode, enabling dynamic screen savers, and ensuring the screen does not display static content for extended periods.

A temporary solution: Blacktop

Until Google addresses this critical flaw, I have developed a workaround called BlackTop.

MaxMoffa / blacktop

Blacktop

OLED-friendly fullscreen black overlay for Android desktop setups

Why

Some Android desktop modes (Google Pixel, etc.) keep the phone screen powered on while connected to an external monitor. The screen sits face-down or unused, draining battery and wearing out OLED pixels. Blacktop fixes this: one tap sends the display into a pure black fullscreen, cutting OLED power draw to near-zero without actually turning off the screen (which would kill the desktop session).

Features

Pure Black Fullscreen

Covers the entire screen with #000000. On OLED panels, black pixels are physically off — zero light output, minimal power draw. Tap anywhere to exit.

Wake Lock

Prevents the display from sleeping while Blacktop is in fullscreen mode. Toggle available in the UI. When the tab loses visibility, the lock is released automatically and re-acquired when the tab returns.

PWA — Install as App

Blacktop ships as a Progressive Web App. Install…

View on GitHub

Blacktop is a lightweight, web-based stopgap that blanks the phone’s display while you keep using desktop mode. It requires no special permissions and can work across devices.

What Blacktop does

Blanks the phone display during desktop-mode sessions to minimize static content on the OLED panel.

What Blacktop does not do

It does not fix the root cause in Android’s desktop mode.
It cannot fix desktop-mode bugs (app focus, widgets, status bar behavior).
It cannot change the behavior of your external monitor.

I urge Google and other Android manufacturers to prioritize a built-in solution that allows users to turn off or blank the phone screen during desktop sessions.

Check out Blacktop on GitHub

Call to action: If you try Blacktop, please share your phone model, Android version, and your typical desktop-mode session length. That feedback helps validate whether the approach generalizes beyond my setup.

Conclusion

Android desktop mode is a transformative feature that turns smartphones into powerful productivity tools. Support is now widespread among flagship devices from Samsung, Google, Motorola, and Huawei, each offering their own take on the desktop experience. However, as my experience with the Pixel 10 shows, there are still critical issues to resolve—most notably, the risk of OLED screen burn-in caused by the phone screen staying on during desktop mode. Until official fixes arrive, solutions like BlackTop are necessary to safeguard your device. I hope this article helps raise awareness and encourages manufacturers to deliver a robust, user-friendly desktop mode that doesn’t compromise device health.

Discussion prompt (good "first comment")

I’m curious to hear from other Pixel owners: have you noticed ghosting, heat issues, or battery drain when using desktop mode for long periods? If you reply, include your Pixel model, Android version, brightness level, and session length.

And for DeX users: what’s the one feature you think Google is missing the most right now?

DEV Community: maxmoffa

wakey-claude: surviving the Claude Code 5-hour usage window

The problem: the 5-hour wall

The idea: an alarm, not a babysitter

How it works

1. The sensor: usage-statusline.sh

2. The consumer: usage-guard.sh

3. Claude itself

The flag file lifecycle

Fail open, always

Install

When (not) to use this

Try it

MaxMoffa / wakey-claude

"Wakey wakey, it's time for school" — except it's your 5-hour usage window resetting.

wakey-claude

The brain freeze between us and AGI

What is AGI?

What do I mean by human-made?

What does neuroplastic mean, and why is it so important?

The AI model we are using is a frozen brain

Why is the brain frozen?

The AI approach

What are they doing in this direction?

Closing the loop

Embedding the loop

And the AGI?

References

The beauty of modularity: a discipline of looking, not building

What do I mean by "modular"?

Modularity at its best (in my opinion)

Docker

Module Federation

Notion

Modularity in "real" life

How do you discover a module?

My attempt at building a "module"

Beware the false module!

What I take home

References

Loved this setup, would be perfect to create a docker just for this

Setup Expo Build Environment on WSL2 (Without Android Studio nor Paying Expo Credits)

Android desktop mode: features, device support, and the OLED screen burn-in problem

TL;DR

What is android desktop mode?

How does it work?

Which devices support desktop mode?

Samsung DeX

Google Pixel desktop mode

Motorola Ready For

Huawei Easy Projection

Other brands

The OLED burn-in problem in desktop mode

The issue on pixel devices

Is this issue present on other devices?

General screen timeout and OLED burn-in concerns

A temporary solution: Blacktop

MaxMoffa / blacktop

Blacktop

Why

Features

Pure Black Fullscreen

Wake Lock

PWA — Install as App

What Blacktop does

What Blacktop does not do

Conclusion

Discussion prompt (good "first comment")

References

1. The sensor: `usage-statusline.sh`

2. The consumer: `usage-guard.sh`