DEV Community: Chudi Nnorukam

How I Use AI as an Executive Function Prosthetic

Chudi Nnorukam — Tue, 16 Jun 2026 00:36:41 +0000

For years I thought I had a discipline problem. I had shipped code, finished a degree, built things, and still the dominant private feeling was that I was getting away with something, that the gap between what I could do on a good day and what I could do on a normal one was a character flaw I was hiding. The reframe that changed everything was clinical, not motivational: I do not have a discipline problem. I have an executive function problem. And executive function, unlike character, can be supported from the outside.

This is the most personal of the three posts in this cluster. The other two are practical: the CLAUDE.md guide and the five skills. This one is the why underneath both.

What Is Executive Function, Actually?

Executive function is the brain's management layer. It is not intelligence, and it is not knowledge. It is the set of processes that turn knowing-what-to-do into actually-doing-it. The National Institute of Mental Health describes ADHD as fundamentally a disorder of these self-management processes rather than of attention alone.

It is not one function. For the purposes of getting work done, it is at least four distinct ones, and ADHD disrupts each of them in a different way:

Working memory, the mental scratchpad holding what you are doing right now.
Task initiation, the ability to start, to cross the gap from intention to action.
Context switching, the ability to drop one task, pick up another, and come back without losing the first.
Time perception, the internal sense of duration that lets you pace and estimate.

Calling them out separately matters, because "I struggle with executive function" is too vague to act on. Each of the four breaks differently and each one needs a different prosthetic. Lumping them together is how you end up trying to fix a time-perception problem with a task-initiation strategy and concluding you are just broken.

What Is an Executive Function Prosthetic?

A prosthetic does not heal. It compensates. Glasses do not repair your eyes, they do the focusing your eyes cannot, and the result is that you see. Nobody calls glasses a moral failure. Nobody tells a nearsighted person to try harder at focusing.

An executive function prosthetic is the same idea pointed at the management layer. It is an external system that performs the executive work your brain struggles to perform, so the outcome is the same as if the function worked. A calendar is a prosthetic for time perception. A checklist is a prosthetic for working memory. The framing I want you to take from this post is that you are allowed to build these, deliberately, for the specific parts of you that do not work, and that doing so is engineering, not cheating.

The crutch objection answers itself. Yes, it is a crutch. Crutches let people walk who otherwise could not. The point of an assistive tool was never to prove you can do it the hard way. It was the walking.

I use Claude Code as a prosthetic for all four functions. Here is the map.

How ADHD Disrupts Each Function, and How AI Compensates

Working Memory

How ADHD breaks it: the scratchpad is smaller and leakier. You hold fewer items and they fall off faster, especially across interruptions. Close a project, come back, and the model of what you were doing is partly or wholly gone.

The prosthetic: I move the scratchpad out of my head into a file Claude reads automatically. My conventions, my stack, my current task, all of it lives in CLAUDE.md, so the cost of dropping it from memory goes to zero. The file remembers, so I do not have to. The first time I reopened a project and Claude told me what I was doing before I said a word, the relief was physical.

Task Initiation

How ADHD breaks it: there is a real barrier between planning and starting. It is not laziness, it is a failure of the initiation circuit to fire, and a blank editor is the worst possible trigger because it offers nothing to grab. You can know exactly what to do and still be unable to begin.

The prosthetic: I never start from a blank slate. I describe the goal and Claude decomposes it into three to five concrete tasks, and I pick one. Picking one item off a list is a completely different cognitive act than generating the first move from nothing, and the initiation circuit, which could not fire on "build the feature," fires easily on "do this one named thing." The decomposition is the prosthetic. The list is the ramp.

Context Switching

How ADHD breaks it: every switch tears down the mental model, and rebuilding it costs time. The American Psychological Association measures the typical recovery at about 23 minutes per switch. ADHD switches more often, involuntarily, and rebuilds slower. Ten interruptions is not ten minutes lost, it is most of a working day bled out in reconstruction.

The prosthetic: the reconstruction gets done by the tool, not by me. At session start, Claude reads the checkpoint and summarizes the open state, what was in flight, what was blocked, before I write a line. The cold start becomes a warm one. The 23 minutes I would have spent opening files semi-randomly trying to jog the memory get spent on the actual work instead.

Time Perception

How ADHD breaks it: you cannot feel time passing. "One quick fix" becomes four hours. A two-hour task gets estimated at twenty minutes. You ship on deadline panic because there is no internal clock to pace against, and the absence is invisible from the inside, which is what makes it so hard to fix by awareness.

The prosthetic: external time markers, generated by the tool, surfaced at the moment of drift. Checkpoints at real intervals that interrupt and ask "you set 45 minutes, you are at 60, still the right task?" The brain that cannot generate the time signal gets handed one, while the drift is happening rather than after. The clock lives outside me because inside me it does not run.

The One That Is Not on the Standard List: Discounting the Positive

There is a fifth gap that is not technically executive function, but it sabotages all four, so I treat it as part of the same system.

"Discounting the positive" is a cognitive distortion from CBT: you mentally erase your own wins, so only the failures register. You shipped three features and your brain renders the one bug. ADHD ships with this so reliably that it stops feeling like a distortion and starts feeling like accuracy. It is not accuracy. It is a measurement error, and it is expensive, because the ADHD reward system is already under-fueled, and a brain that cannot see its own progress gets none of the dopamine that progress is supposed to pay.

This is where my mirror skill came from. It is the most personal thing I have built. At the end of a session, it reflects back what I actually did, grounded in evidence: the commits, the closed tasks, the things that shipped. Not encouragement, receipts. When I tell myself "good job," my brain discounts it in real time. When a tool shows me the commit log of what I closed today, the distortion has nothing to argue with. The win gets to count.

That last clause is the whole reason this matters. For an under-fueled reward system, letting the win count is not a nice-to-have. It is the fuel that makes tomorrow's initiation possible. Externalizing the scorekeeping is how I keep the distortion from quietly stealing the dopamine I need to keep going.

What This Looks Like in Practice

A single feature, start to finish, mapped to the four functions plus the fifth:

Intention: "Add rate limiting to the API."

[Task initiation]   I do not stare at a blank editor. I hand Claude the goal.
                    It returns: 1) define the limiter, 2) wire the middleware,
                    3) add the headers, 4) write the tests. I pick #1.

[Working memory]    Everything I decide (Redis-backed, 100 req/min, per-key)
                    goes straight into CLAUDE.md. I do not hold it. It holds it.

[Context switch]    Slack pulls me out for 40 minutes. I come back cold.
                    Claude reads the checkpoint: "limiter defined, middleware
                    next." No 23-minute rebuild. Warm start.

[Time perception]   A 45-minute checkpoint pings at 60. "Still on the limiter?"
                    I had drifted into refactoring an unrelated helper.
                    Caught it now instead of two hours from now.

[Discount-positive] End of session my brain says "you barely did anything."
                    /mirror: "Shipped rate limiting, 4 tasks closed, tests
                    green. Commits attached." The win counts. Fuel for tomorrow.

No single piece of that is heroic. The system is the point. Each prosthetic is dull on its own. Together they let a brain that cannot reliably do any of the four functions produce the same output as one that can.

The Honest Limits

This is environmental support, not treatment. It does not replace medication, therapy, or a clinician, and I would not want anyone to read a blog post and substitute it for care. The prosthetic frame is a way to design your environment, not a way to fix your neurology.

It also has failure modes. A prosthetic that lies is worse than none: stale context in CLAUDE.md will make Claude reason confidently from a model that no longer matches reality, and you have to maintain the aid with the same discipline you lack, which is its own quiet joke. And there is a real risk of outsourcing understanding, of letting the tool carry so much that you stop being able to hold any of it. The guard there is that I still have to understand what ships. The prosthetic carries the management layer. It does not get to carry the thinking.

But the reframe stands, and it is the thing I most want you to take. I am not undisciplined. My executive function works differently, and the parts that do not work can be supported from the outside, deliberately, without shame. I stopped trying to white-knuckle my way into a neurotypical brain. I started building prosthetics for the specific functions mine does not have. The work got done. So did I.

Frequently Asked Questions

What is an executive function prosthetic?
An external system that performs the executive-function work your brain struggles to do, the way glasses do the focusing your eyes cannot. It does not heal the underlying difference. It compensates so the outcome is the same as if the function worked.

Is using AI for executive function just a crutch?
Yes, and that is not an insult. Crutches let people walk who otherwise could not. The goal of an assistive tool is the outcome, not proving you can do it the hard way. A calendar is a crutch. So are glasses.

What is "discounting the positive"?
A cognitive distortion from CBT where you mentally erase your own wins so only the failures register. It is common with ADHD and it starves an already under-fueled reward system, which is why externalizing your own scorekeeping helps.

Does this replace ADHD medication or therapy?
No. It is environmental support, not treatment. It works alongside medication, therapy, and other supports, never instead of them. Talk to a clinician about treatment and use tools like this to design your environment.

If this mapped onto your experience, the two practical companions are the ADHD developer's guide to CLAUDE.md for the working-memory layer, the five Claude Code skills for the rest of the executive-function gaps, and the original ADHD coding workflow that started this whole cluster.

Originally published on chudi.dev

5 Claude Code Skills Every ADHD Developer Needs

Chudi Nnorukam — Tue, 16 Jun 2026 00:35:48 +0000

I have built 114 Claude Code skills. Most of them are engineering plumbing. But five of them exist for one reason only: my executive function has specific, repeatable holes, and I got tired of falling into the same ones. These five are not productivity hacks. Each one maps to a named ADHD deficit, and each one fills it the same way every time so I do not have to re-improvise around my own brain at 2pm.

If you want the broader system this sits inside, start with my Claude Code ADHD workflow and the CLAUDE.md guide. This post is the skills layer specifically.

What Is a Claude Code Skill?

A skill is a named, repeatable workflow you invoke with a slash command. Instead of re-prompting Claude Code from a blank slate every time ("okay, help me figure out what to work on, here is my situation again..."), you type /adhd-task-triage and it runs the same defined steps it ran yesterday. For an ADHD brain, that determinism is the feature. The skill does not depend on me remembering how to drive it. It just runs.

Custom skills live in a .claude/skills/<name>/SKILL.md file that describes what the skill does and when it should fire. You can build one for any gap you fall into more than twice.

1. adhd-task-triage: Energy-Based Prioritization

The gap it fills: task initiation paralysis.

Standard task managers sort by priority or deadline. That assumes you can act on the top item by willpower. ADHD does not work that way. The top-priority task and the task you can actually start right now are often different tasks, and trying to force the high-priority one when your initiation circuit is offline produces zero output and a guilt spiral.

adhd-task-triage sorts by available energy, not importance. You tell it where you are (wired, foggy, depleted), it looks at the work in front of you, and it hands back the task that matches the state you are actually in, not the one you wish you were in.

/adhd-task-triage

Why it helps specifically: it removes the moral framing. The question stops being "why can't you just do the important one" and becomes "what can this brain, in this state, actually initiate." Matching the task to the energy is how you get momentum, and momentum is the thing ADHD brains can ride once it exists.

2. mirror: The Counter to Discounting the Positive

The gap it fills: cognitive distortion, specifically discounting the positive.

"Discounting the positive" is a CBT term for a thinking pattern where you mentally delete your own wins. You shipped three features, but your brain only renders the one bug. ADHD comes bundled with this so often that it feels like just being realistic. It is not realistic. It is a measurement error, and it is corrosive, because a brain that cannot see its own progress loses the dopamine that progress is supposed to pay out.

mirror reflects back what I actually did, grounded in evidence, not vibes. It reads the session, the commits, the closed tasks, and tells me plainly: here is what shipped. Not cheerleading. Receipts.

/mirror

Why it helps specifically: ADHD reward systems are under-fueled, and discounting the positive starves them further. When the skill says "you closed four tasks and shipped the auth flow," and points at the commits, the distortion has nothing to push against. I cannot argue with the log. The win gets to count, which is the entire point.

The reason this works is that it is external and evidence-based. If I tell myself "good job," my brain discounts it instantly. If a tool shows me the commit history of what I closed today, the distortion has no grip. Externalize the scorekeeping and the distortion loses.

3. pickup: Session Resume for Context-Switching

The gap it fills: context-switch recovery cost.

Every interruption tears down the mental model of what I was doing. Rebuilding it is the 23-minute reconstruction tax that, for an ADHD brain, runs longer and hits more often. The worst version is the overnight gap: I close the laptop mid-thought and the next morning the entire working model is just gone.

pickup reconstructs the session for me. It reads where I left off, what was in flight, what was blocked, and summarizes the open state before I write a single line.

/pickup

Why it helps specifically: it converts a cold start into a warm one. The reconstruction that used to eat the first half hour of every session, the part where I open files semi-randomly trying to jog the memory, gets done by the skill in seconds. I am not rebuilding the model. I am reading it back.

4. schedule: A Patch for Time Blindness

The gap it fills: time perception distortion.

Time blindness is an ADHD hallmark: you cannot feel time passing, so "I'll just fix one thing" becomes a four-hour rabbit hole, and a two-hour task gets estimated at twenty minutes. You ship on deadline panic because your brain has no internal clock to pace against.

schedule puts external markers on the work: it sets up recurring checkpoints and time-boxed runs so the passage of time becomes visible instead of imagined. It is the external clock my brain does not have.

/schedule

Why it helps specifically: ADHD does not respond well to "be more aware of time," because the awareness machinery is the thing that does not work. It responds to external structure. A skill that interrupts at a real interval and asks "you set 45 minutes for this, you are at 60, still the right task?" gives me the time signal my brain cannot generate, at the moment the drift is happening rather than after.

5. librarian: Reducing the Cognitive Load of Navigation

The gap it fills: working-memory overload from holding a whole codebase in your head.

Navigating a large codebase means holding a map of it in working memory: where things are, what calls what, which file owns which concern. ADHD working memory cannot hold that map, so every navigation becomes a fresh, expensive search, and the expense itself becomes a reason to avoid touching unfamiliar parts of the code.

librarian walks the knowledge layer for me. Instead of me grepping around trying to reconstruct where a behavior lives, I describe what I am after and it returns the relevant pieces and how they connect. It holds the map so I do not have to.

/librarian

Why it helps specifically: it collapses the navigation tax. The mental energy I would spend reconstructing "where does this live and what touches it" is exactly the executive-function budget I do not have to spare. Offloading the map means I can spend that budget on the actual change instead of on finding the place to make it.

What This Looks Like in Practice

A real morning, lightly compressed, showing the five working as a chain rather than in isolation:

9:10  Sit down. No memory of yesterday's state.
      /pickup  ->  "You were mid-refactor on the signal loop, JWT
                    middleware blocked on a cookie setting. 2 tasks open."
      Cold start avoided. ~20 min reconstruction skipped.

9:14  Brain is foggy, not wired.
      /adhd-task-triage  ->  hands me the low-initiation-cost task
                            (write the middleware test), not the hard one.
      Momentum started instead of staring at the blank editor.

9:20  Need to change the auth schema but forget where it lives.
      /librarian  ->  returns the schema file + everything that touches it.
      Navigation tax collapsed. No grep spiral.

9:25  /schedule already running a 45-min checkpoint in the background.
      At 10:10 it pings: "60 min on a 45 task, still the right one?"
      Caught a hyperfocus drift before it ate the morning.

11:30 Brain says "you got nothing done."
      /mirror  ->  "3 tasks closed, middleware shipped, schema migrated.
                    Here are the commits."
      Distortion loses. The win counts.

None of these is doing anything a disciplined neurotypical developer could not do by hand. That is the point. They do it for me, the same way every time, so the doing does not depend on executive function I cannot summon on command.

How Do You Start Building Your Own?

Do not install five skills today. Pick the one deficit that costs you the most, mine was the cold-start reconstruction, and build or invoke the one skill that targets it. A skill is a SKILL.md file in .claude/skills/ that names what it does and when it triggers. Start there, use it for a week, and let the next-most-expensive gap tell you what to build next.

The pattern underneath all five is the same: name the executive-function gap precisely, then build a repeatable thing that fills it so you stop re-improvising around your own brain.

Frequently Asked Questions

What is a Claude Code skill?
A packaged capability you invoke by name (like /pickup) that runs a defined, repeatable workflow. Instead of re-prompting Claude from scratch each time, you call the skill and it runs the same proven steps every time.

Are these built into Claude Code?
Claude Code ships with a skill system and some bundled skills. Several here (like adhd-task-triage and mirror) are custom skills I built for my own setup. The transferable thing is the pattern: build a skill for any recurring executive-function gap.

Do I need ADHD for these to help?
No. They help anyone who context-switches a lot, undersells their progress, or loses the thread between sessions. ADHD just makes the gaps sharper, so the payoff comes faster.

How do I invoke a skill?
Type its slash command (for example /pickup) in Claude Code. Custom skills live in .claude/skills/ as a SKILL.md file that defines what the skill does and when it fires.

These skills are the executive-function layer on top of the working-memory layer from the CLAUDE.md guide. For the clinical picture of why each gap exists and how AI compensates, read how I use AI as an executive function prosthetic.

Originally published on chudi.dev

The ADHD Developer's Guide to CLAUDE.md

Chudi Nnorukam — Tue, 16 Jun 2026 00:35:39 +0000

I reopened a file I had already fixed that morning. Not metaphorically. I literally re-fixed a bug I had closed four hours earlier, because between the fix and the reopen, my brain had quietly deleted the entire afternoon. That is the ADHD tax most productivity advice never names: it is not that you cannot focus, it is that the working model of what you were doing does not survive the gap between sessions.

CLAUDE.md is the cheapest fix I have found for that specific failure. This is the companion to my Claude Code ADHD workflow; that post is the full system, this one zooms all the way in on the single file doing most of the work.

What Is CLAUDE.md, Actually?

CLAUDE.md is a Markdown file that Claude Code reads automatically at the start of every session. You do not paste it. You do not remind Claude it exists. It just gets read, every time, before the first line of work.

There are two places it lives:

./CLAUDE.md at a project root holds rules for that project: the tech stack, the conventions, the gotchas.
~/.claude/CLAUDE.md holds your global rules: things true across everything you build (your voice, your defaults, the things you never want re-litigated).

For a neurotypical developer this is a convenience. For an ADHD developer it is a prosthetic. The difference is what the file is replacing.

Why CLAUDE.md Is External Working Memory for ADHD Brains

Working memory is the mental scratchpad that holds "what I am doing right now and the three things I just decided about it." ADHD shrinks that scratchpad and makes it leaky. Every interruption, a Slack ping, a stray thought, a context-switch to email, knocks items off it. When you return, the scratchpad is blank and you rebuild it from scratch.

The American Psychological Association puts the rebuild cost at roughly 23 minutes per context switch for a typical brain. For an ADHD brain that involuntarily switches more often and rebuilds slower, the real cost is higher and it compounds. Ten switches a day is not ten minutes lost, it is most of a morning.

CLAUDE.md moves the scratchpad out of your head and into a file. The conventions you would otherwise have to remember, hold, and re-explain now live somewhere that does not leak:

It remembers your tech stack, so you never re-explain "we use SvelteKit, not Next."
It remembers your conventions, so you stop re-deciding the same naming question.
It remembers your voice, so output comes back sounding like you without a paragraph of instructions.
It remembers the current task, so reopening the project does not start from "wait, what was I building?"

You are not asking Claude to remember for you. You are writing down what you would otherwise have to hold, once, so that the cost of dropping it goes to zero.

The mental reframe that made this click for me: CLAUDE.md is not documentation you write for other people. It is a note you write to your own future self, who will have no memory of today. Write it for the version of you that comes back tomorrow with the scratchpad wiped.

What This Looks Like in Practice

Here is a real, trimmed version of a project CLAUDE.md from my setup. Nothing exotic, that is the point. It is boring, and boring is what survives.

# Project: chudi.dev blog

## Stack (do not re-ask)
- SvelteKit + Svelte 5 runes ONLY ($state, $props, $derived). No legacy `let`/`$:`.
- Tailwind v4 + CSS custom properties in src/app.css. Never hardcode hex in components.
- Content: Markdown in content/posts/. Frontmatter required: title, date, description, tags.

## Voice (apply to all writing)
- First person, conversational, backed by real numbers.
- NEVER use em-dashes. Use commas, periods, parentheses.
- Lead with the failure, then the fix. No marketing tone.

## Gotchas (learned the hard way)
- Never use the $lib alias in any file reachable from a prebuild script. tsx
  on Vercel will not resolve it. Use relative imports. (Cost me a 3-hour outage.)
- Reading time is auto-calculated. Do not hardcode it.

## Current checkpoint
- Last task: shipped citability CTA on 3 top-traffic posts.
- Next task: write the 3-post ADHD cluster around claude-code-adhd-workflows.
- Blocked by: nothing.

The four sections map directly onto the four things my working memory cannot be trusted to hold: the stack, the voice, the landmines, and the bookmark.

The Current checkpoint block is the one that matters most for ADHD. Before I had it, every session opened with a flailing minute or two of "okay where was I." Now the first thing Claude tells me is what I was doing and what is next, because it read the checkpoint before I said a word. The flail is gone.

The Global File Does the Re-Decided Stuff

The project file handles per-project facts. The global ~/.claude/CLAUDE.md handles the things I was tired of re-deciding everywhere:

## Defaults (do not ask, just do)
- Verify before claiming done. Show the build output, do not say "should work."
- Break vague goals into 3-5 atomic tasks and let me pick one. Never hand me a blank slate.
- One question at a time. If you have three, ask the first and wait.

That last rule is pure ADHD accommodation. A wall of "do you want A or B, and also C or D, and what about E" is a context-switch grenade. "Ask the first, wait" keeps me in one decision at a time.

How Does CLAUDE.md Compare Before and After?

I tracked my own sessions loosely for two weeks before writing a real CLAUDE.md and two weeks after. This is self-reported and n-of-one, so read it as a direction, not a benchmark. But the direction was not subtle.

Signal	Before CLAUDE.md	After CLAUDE.md
Time to first useful action after reopening a project	5 to 15 minutes of "where was I"	Under 1 minute
Re-explaining stack/conventions per session	Almost every session	Effectively never
Re-doing work I had already finished	A few times a week	Rare
Sessions that ended without me knowing what was next	Most of them	Almost none (the checkpoint forces it)

The biggest win is not on that table because it is hard to measure: the dread went down. Reopening a half-built project used to carry a little spike of "ugh, I have to reload all of this." When the file reloads it for me, that spike mostly disappears, and the lowered friction is what actually gets me back into the chair.

What Breaks This System

CLAUDE.md is not free and it is not foolproof. Two failure modes, both real, both mine.

Stale context is worse than no context. I once let a project's CLAUDE.md describe an architecture I had refactored away three weeks earlier. Claude reasoned confidently from a model that no longer matched the code, and I almost shipped it. The fix is discipline: when you change something structural, update the file in the same breath. An out-of-date CLAUDE.md does not just fail to help, it actively lies to you with full confidence.

The unwritten checkpoint. The checkpoint only works if you write it before you close. The times I closed mid-thought and skipped it, the next session opened cold, exactly the problem the file was supposed to solve. I eventually added a hook that nudges me to update the checkpoint before the session ends, because relying on ADHD memory to maintain the ADHD memory aid is, predictably, a bad plan.

How Do You Start?

Do not engineer the perfect file. Open the project, create CLAUDE.md at the root, and write four headers: Stack, Voice, Gotchas, Current checkpoint. Fill in what you know right now. Leave the rest blank. The file gets better every time Claude asks you something you wish it already knew, because that question is the exact thing you should write down.

Your working memory is not a character flaw to push through. It is a constraint to design around. CLAUDE.md is the cheapest way I know to design around it.

Frequently Asked Questions

What is CLAUDE.md and where does it live?
It is a plain Markdown file Claude Code reads automatically at the start of every session. Project rules go in ./CLAUDE.md at the project root; global rules go in ~/.claude/CLAUDE.md. You never have to tell Claude to read it, it just does, every time.

How is it different from explaining context in chat?
Chat context dies when the session ends. CLAUDE.md persists across sessions. For an ADHD brain that loses the mental model across interruptions, that persistence is the entire value: the file holds your conventions so your working memory does not have to.

Will CLAUDE.md fix my ADHD?
No. It externalizes one slice of executive function, working memory, so the cost of switching back into a project drops from minutes to seconds. It is a prosthetic, not a cure.

How long should it be?
Short enough that you would actually read it, long enough that Claude stops asking you things you already decided. Mine run 40 to 120 lines per project. Prune it when it drifts out of date, because stale context is worse than none.

If CLAUDE.md is the working-memory layer, the next layer is the executive-function gaps it does not cover. I wrote about the specific Claude Code skills every ADHD developer needs for that, and the bigger clinical picture in how I use AI as an executive function prosthetic.

Originally published on chudi.dev

Entity Optimization for Brands in AI Search

Chudi Nnorukam — Wed, 22 Apr 2026 22:13:03 +0000

Originally published at chudi.dev

AI search engines do not rank pages. They score entities, then quote the entity that best matches the query. For a sub-DR-20 brand, this is the good news. You cannot outspend enterprise SEO teams on backlinks. You can out-engineer them on entity coherence.

This post is the engineering playbook for that work. It covers the three schemas that anchor the graph, the sameAs surface where most brands leak trust, the knowsAbout field that tells engines what you are an authority on, and the measurement loop that tells you when it is working. The reference model throughout is chudi.dev (the Person brand) and citability.dev (the product brand): a deliberate two-node graph that synergizes without cannibalizing.

§1 — Why AI citations resolve to entities, not URLs

Classical SEO optimized for pages. Answer engines optimize for the entity behind the page. If two sites say the same thing and one site has a coherent Person + Organization + sameAs graph, the engine quotes the coherent site even when the other page ranks higher in traditional SERPs. Cite the entity, not the URL. That is the mental model shift this cluster pivots on.

§2 — The three anchor schemas

Every resilient entity graph has three anchor schemas. Person. Organization. SoftwareApplication. They cross-reference through creator, publisher, and about fields. Miss one anchor and the graph reads as a disconnected individual, a disconnected company, or a disconnected tool. Engines pick the version of your story they find easiest to summarize, which may not be the version you want quoted.

§3 — sameAs coherence across platforms

The sameAs array is the single most valuable field in the Person schema for sub-DR-20 brands. It is also the field most brands let drift. Six platforms. Six subtly different job titles. Six subtly different descriptions. Engines treat this as ambiguity and choose a canonical, usually the platform with the highest authority, not the one you care about.

§4 — The knowsAbout surface nobody uses

knowsAbout is the declarative authority claim. Use it to stake your territory. For chudi.dev, the stake is AI Visibility Engineering, Generative Engine Optimization, Entity Graph Architecture, and Sub-DR-20 SEO. Four claims. Four phrases an engine can match against a query.

§5 — The citation flow

When a query arrives, an AI engine runs a pipeline. Retrieve candidate entities. Score coherence. Gate. Cite. Optimizing for citation means shortening the distance between query and gate.

§6 — Measurement: how you know it is working

The answer engines that matter (Perplexity, ChatGPT with search, Google AI Overviews) do not expose rank. They expose citations. Measurement is a different instrument than Google Search Console. Track citation count per engine, quote length per citation, and coherence-check failures across your sameAs graph.

Bridge — from thinking to measurement

This post describes the thinking. citability.dev is the instrumentation. Run the citability scorer on any chudi.dev post to see what the engine actually extracts, which entity it resolves to, and where the coherence gates are failing.

ADHD Remote Work for Developers: Build for Context Decay, Not Perfect Focus

Chudi Nnorukam — Fri, 10 Apr 2026 23:55:49 +0000

Originally published at chudi.dev

I worked from home for eight months before I figured out I was failing at remote work specifically because of ADHD, not despite doing everything "right."

I had a desk. A monitor. A to-do list. I woke up at the same time every day. And still, whole afternoons would vanish. I'd look up at 5pm, realize I'd been deep in a rabbit hole since 11am, and have nothing to show for it that anyone would call work.

The problem wasn't focus. ADHD gets described as a focus problem, but that's wrong. My focus was fine. It was just pointed at the wrong things for hours at a time, with no external force to redirect it. That's what remote work does to ADHD brains: it removes every environmental cue that normally handles redirection for you.

Here's what I replaced those cues with.

Why remote work hits ADHD harder than most people realize

An office is full of behavioral scaffolding you don't notice until it's gone.

The commute is a transition ritual. It physically separates "home brain" from "work brain." Without it, you start working and your nervous system never quite shifts modes.

Other people visibly working is a constant time cue. You glance up and see colleagues at their desks, it's 2pm, you haven't eaten. That passive awareness regulates your own sense of time. Without it, time blindness kicks in fully.

Scheduled meetings are anchors. Even if you hate meetings, they force context switching at predictable intervals. They're external interrupts the ADHD brain doesn't have to generate internally.

Remote work strips all three. What you're left with is a quiet room, unlimited flexibility, and a brain that cannot generate external structure from nothing.

Flexibility, for ADHD, is not a feature. It's a trap.

Environment design: make your space do the transition work

The most reliable fix I found is physical environment separation. Not because it's psychologically important in some abstract way, but because ADHD brains form strong context associations. If you sleep, relax, and work in the same chair, your brain genuinely cannot tell which mode to be in.

If you have a separate room, use it only for work. Close the door when you're done. The physical act of closing the door is the end-of-day ritual. Open it again when starting. That's the whole commute.

If you don't have a separate room (I didn't for two years), use environmental cues instead:

A specific chair at a specific surface. Not the couch. Not the bed. One chair that means work. Sit in it, you're working. Leave it, you're not.

Distinct lighting. I use a desk lamp on a smart plug scheduled to turn on at 9am and off at 6pm. When it turns on, that's the ambient "it's work time" signal. This sounds absurd. It works.

A start ritual that's identical every day. Mine is: make coffee, carry it to the desk, open a specific playlist. Three steps, always the same order. The ritual triggers the context switch. Willpower doesn't have to.

The goal isn't a beautiful home office. It's tricking your nervous system into associating a location with a mode.

Time anchors: replace meetings with artificial deadlines

Time blindness is the ADHD symptom that remote work makes worst. In an office, you feel time passing through social cues. At home, four hours can feel like forty minutes.

The fix is time anchors, and the most effective one I've found is a scheduled video call. It doesn't matter what the call is about. It just has to happen at a predictable time, because your brain will orient itself around it. "I have a call at 2pm" creates a before-the-call and an after-the-call. That's two time blocks with structure, instead of one infinite formless day.

If you don't have regular calls, manufacture them:

Daily standup with yourself. Five minutes on video, speaking out loud, covering what you did yesterday and what you're doing today. The video part matters. Talking to a camera activates social awareness in a way typing doesn't.

Focusmate sessions. Two people, 50-minute video session, each says what they're working on, then works silently, then checks back in. It's structured, it ends, and the commitment to another person is enough accountability to keep most ADHD brains on task.

90-minute alarms. Not as a task timer. As a "what are you doing right now" interrupt. When it goes off, write one sentence in a running doc: what you're doing, whether it's the right thing. That's it. The awareness loop is enough to reduce hyperfocus drift.

Async communication: close every loop explicitly

Open communication loops are ADHD kryptonite at home.

In an office, you send a Slack message and you can see the person at their desk. You know they're alive. You have some sense of whether they saw it. At home, you send something and then... nothing. That uncertainty sits in your brain as an open tab, consuming attention.

The fix is aggressive loop-closing, on both ends.

Send explicit "done" messages. When you finish a task that someone asked for, message them directly: "Done, PR is up." Don't assume they'll see the PR notification. Close the loop yourself. This sounds like extra work but it's actually cognitive offloading — you're moving the "did they see it" question out of your head and into their inbox.

Batch your Slack/email. Check twice a day: 9:30am and 3:30pm. Outside those windows, quit the app. I mean actually quit it, not just minimize it. The notification bubble sitting in your dock is a distraction even when you're not looking at it.

Use Loom instead of "let's hop on a call." When you need to explain something complex, record a 3-minute video. It's faster to make than scheduling a call, the other person can watch it at their pace, and you don't have to hold the context of what you were going to say while waiting for a meeting slot to open up.

Set explicit Slack statuses. "Deep work until 2pm" tells your team not to expect synchronous response. It also reminds you what you're supposed to be doing when you look at your own status and see it staring back.

Body doubling: the remote version

Body doubling is working in the presence of another person. It activates the social engagement system, which provides the kind of external accountability ADHD brains need to sustain attention on boring tasks. It sounds like it shouldn't work. It works.

The office version is automatic. The remote version requires effort to set up, but it's worth it.

Focusmate (focusmate.com) is purpose-built for this. You book 50-minute sessions with a random partner, you both say what you're working on, you work silently, you check back in at the end. It's free for a few sessions per week, paid for unlimited. I've used it to get through tax returns, documentation, and every other task that normally gets avoided indefinitely.

Discord co-working servers. There are ADHD-specific ones with always-on voice channels where people work silently together. You join, unmute when you want company, mute when you need quiet. The ambient presence of other people is enough.

A recurring call you never close. I have a weekly video call with a friend who also works remotely. We don't talk during it. We just exist on the same screen, working. When one of us needs to say something, we say it. This is body doubling. It costs nothing and it's sustainable.

Managing your manager remotely with ADHD

The part nobody talks about: ADHD makes remote work harder because managers can't see you working. In an office, your presence is visible evidence of effort. At home, you have to manufacture that evidence.

This isn't about performing productivity. It's about removing the anxiety of wondering whether your manager thinks you've disappeared.

Daily end-of-day summary, one sentence. "Finished the auth PR, reviewed two tickets, starting the cache refactor tomorrow." Send it every day, at the same time, without being asked. It closes the loop for your manager and it forces you to acknowledge what you actually did, which matters for your own ADHD sense of accomplishment.

Overcommunicate blockers. When you're stuck, say so immediately. ADHD means stuck can turn into three hours of silent spiraling without warning. Saying "I'm blocked on X, any context?" gets you unblocked faster and signals that you're engaged, not absent.

Use async video for updates that would otherwise be a meeting. A 2-minute Loom is easier for everyone than a 30-minute call. It respects your manager's time, it documents the update, and it proves you exist and are thinking.

What I stopped doing

I stopped trying to simulate the office at home. I don't have scheduled "office hours" where I sit at my desk whether or not I have anything to do. I don't use time-blocking as a rigid constraint because rigid constraints with ADHD become guilt traps when they break, which they always do.

Instead, I work with the parts of ADHD that actually help remote work. Hyperfocus is an asset when pointed at the right thing, so I protect large uninterrupted blocks in the morning. The lack of commute means I can start working when my brain is actually ready, not when a train schedule says I should be at a desk.

Remote work with ADHD doesn't require suppressing the ADHD. It requires replacing the scaffolding the office provided with intentional, homemade versions of the same cues.

The cues work. The willpower approach doesn't. That's the whole thing.

If you want to compare notes on what's working, the contact is at the bottom of the page. Remote ADHD work is still being figured out by most of us in real time.

Sources

Self-Improving RAG: Teaching Claude Code to Learn From Errors

Chudi Nnorukam — Fri, 10 Apr 2026 23:55:21 +0000

Originally published at chudi.dev

I was debugging the same authentication error for the third time this month.

Same error. Same root cause. Same fix.

Claude Code had solved this exact problem two weeks ago—but it didn't remember. Each session starts fresh. No memory of what worked, what failed, or what patterns emerged.

That's a massive waste of debugging time.

So I built a system to fix it.

The Problem With Stateless AI

Claude Code is powerful, but it has a fundamental limitation: every session starts from zero.

This means:

Same mistakes repeated across sessions
No accumulation of project-specific knowledge
Debugging loops that should take minutes take hours
Learnings trapped in conversation history, never extracted

The irony? Claude Code can solve complex problems. It just can't remember that it already solved them. This is where building a self-improving RAG system becomes transformative.

Introducing the Self-Improving RAG System

I built a configuration that makes Claude Code learn from every debugging session.

The core idea: automatic capture, structured storage, intelligent retrieval.

When something breaks, the system captures it. When something works, the system remembers it. When a session ends, the system reflects on what happened.

No manual logging. No /learn commands for every insight. The system watches, learns, and improves. This is built on the principles of Retrieval-Augmented Generation (RAG)—using external knowledge to enhance AI responses—combined with Claude Code's development capabilities.

Architecture: Three Memory Layers

The system uses three complementary memory approaches:

┌─────────────────────────────────────────────────────────────────┐
│                     Knowledge Layer                              │
│                                                                  │
│  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐          │
│  │ ChromaDB     │  │ Graph Memory │  │ CLAUDE.md    │          │
│  │ (Vectors)    │  │ (Relations)  │  │ (File)       │          │
│  └──────────────┘  └──────────────┘  └──────────────┘          │
│                                                                  │
│  Collections:          Relationships:     Sections:             │
│  • error_patterns      • error→file       • Known Pitfalls      │
│  • successful_patterns • error→fix        • Successful Patterns │
│  • project_learnings   • fix→file         • Error History       │
│  • meta_learnings      • decision→outcome                       │
└─────────────────────────────────────────────────────────────────┘

Layer 1: ChromaDB (Semantic Search)

Vector embeddings enable semantic search across all captured knowledge.

Collections:

error_patterns: Build failures, type errors, runtime exceptions
successful_patterns: What worked—deployment patterns, architecture decisions
project_learnings: Project-specific insights
meta_learnings: Process improvements from self-reflection

When I search "authentication errors," I get relevant results even if the exact phrase wasn't used.

Layer 2: Graph Memory (Relationships)

ChromaDB stores flat documents. But knowledge has structure.

Graph memory tracks relationships:

Error ──occurred_in──→ File
  │
  └──fixed_by──→ Fix ──applied_to──→ File

Decision ──led_to──→ Outcome
                        │
Learning ←──learned_from─┘

This enables queries like:

"What errors have occurred in auth.ts?"
"What fixes have been applied to the API module?"
"What decisions led to successful deployments?"

Relationships reveal patterns that flat search misses.

Layer 3: CLAUDE.md (Project Memory)

Each project maintains a CLAUDE.md file—a living document that Claude reads at session start.

Sections:

Known Pitfalls: Project-specific gotchas (auto-populated by hooks)
Successful Patterns: Code patterns that have worked
Error History: Recent errors with resolutions

This provides immediate context without database queries.

Automatic Learning Capture

The magic is in the hooks—scripts that intercept Claude Code events.

Hook: Capture Failures

When a build or test fails:

# capture_failure.py (PostToolUse hook)
def capture_failure(tool_result):
    if tool_result.exit_code != 0:
        error = extract_error(tool_result.output)
        store_to_chromadb({
            "type": "error_pattern",
            "error": error,
            "file": tool_result.file,
            "timestamp": now()
        })
        update_graph("error", error, "occurred_in", tool_result.file)

No manual intervention. Failures get captured automatically.

Hook: Track File Edits

When files are modified:

# log_edit.py (PostToolUse hook)
def log_edit(tool_result):
    if tool_result.tool == "Edit":
        update_graph("fix", tool_result.diff, "applied_to", tool_result.file)

This builds the error→fix→file relationship over time.

Hook: Session Summary

When a session ends:

# session_summary.py (Stop hook)
def session_summary():
    learnings = extract_learnings(session_history)
    update_claude_md(learnings)
    store_to_chromadb(learnings)

The system extracts what was learned and persists it.

Self-Reflection: Meta-Learning

Beyond capturing individual learnings, the system reflects on patterns.

At session end, a self-reflection agent analyzes:

What approaches were effective
What inefficiencies occurred
What patterns emerged

These meta-learnings go into a separate collection—insights about the development process itself, not just specific bugs.

Example meta-learning:

"When debugging TypeScript type errors, checking the imported types first resolves 70% of issues faster than tracing through the codebase."

This is knowledge about how to debug, not just what broke.

Memory Decay: Keeping Knowledge Fresh

Old knowledge becomes stale. A fix that worked six months ago might not apply to the current architecture.

Memory decay solves this:

Half-life: 90 days (configurable)
Minimum weight: 0.1 (never fully forgotten)
Access boost: Recently used memories get +20% weight

The result: Claude prioritizes recent, actively-used knowledge while maintaining a long-term memory of rare but important patterns. This is similar to the token optimization strategies I've outlined for reducing AI token usage, where selective information display keeps context efficient.

Custom Commands

The system adds slash commands for manual interaction:

Command	What It Does
`/learn`	Manually capture a learning from the current session
`/search-knowledge "query"`	Search all memory layers
`/review-plan`	Validate a plan against past learnings
`/reflect`	Trigger self-reflection analysis
`/memory-stats`	Show knowledge base statistics
`/memory-maintain`	Run decay, merge duplicates, archive old memories

Most learning happens automatically. These commands are for when you want manual control.

Effort-Based Routing

Not every task needs maximum AI capability. The system classifies prompts:

Level	Example	Token Impact
`low`	"What's the syntax for..."	Fastest, cheapest
`medium`	"Implement this feature"	Balanced
`high`	"Architect the auth system"	Maximum capability

Simple questions get fast answers. Complex problems get deep thinking.

Real Results

After two months of use:

Before (vanilla Claude Code):

Same auth bug: 45 minutes to debug (third time)
Build failures: Manual pattern recognition
Session knowledge: Lost after conversation ends

After (self-improving RAG):

Same auth bug: /search-knowledge "auth middleware" → fix in 2 minutes
Build failures: Automatic capture, searchable history
Session knowledge: Persisted, searchable, improving

The system has captured 150+ error patterns, 45 successful patterns, and 80 meta-learnings across my projects. For more on Claude Code workflows and best practices, see my comprehensive Claude Code guide.

Getting Started

The system is available as a configuration you can install:

cd ~/Projects/active/claude-rag-config
./setup.sh

# Then in any project:
claude

Setup installs:

Hooks for automatic capture
Custom commands for manual control
ChromaDB for vector storage
Graph memory database
CLAUDE.md template

Requirements: Python 3.9+, Node 18+, ChromaDB (pip install chromadb)

Getting Started: The Minimum Viable RAG Setup

You don't need the full system on day one. Here's the smallest version that actually makes a difference.

Step 1: Install ChromaDB

pip install chromadb

That's your vector store. One command.

Step 2: Create a capture hook

Create a file at ~/.claude/hooks/post_tool_use.py:

import json, sys, chromadb, hashlib
from datetime import datetime

data = json.loads(sys.stdin.read())

if data.get("tool") == "Bash" and data.get("exit_code", 0) != 0:
    client = chromadb.PersistentClient(path="~/.claude/memory")
    collection = client.get_or_create_collection("error_patterns")

    error_text = data.get("output", "")[:500]
    doc_id = hashlib.md5(error_text.encode()).hexdigest()

    collection.upsert(
        documents=[error_text],
        ids=[doc_id],
        metadatas=[{"timestamp": datetime.now().isoformat()}]
    )

print(json.dumps({"continue": True}))

This captures every failed Bash command into ChromaDB. No manual intervention.

Step 3: Add a search command

Add this to your CLAUDE.md:

## /search-errors command
When user types /search-errors "query":
1. Query ChromaDB error_patterns collection
2. Return top 3 similar past errors and their context
3. Suggest fixes based on patterns

Step 4: Add a project-specific CLAUDE.md section

## Known Pitfalls (auto-updated)
<!-- This section gets updated by the session summary hook -->

That's the minimum viable setup. Four steps, maybe 20 minutes. You won't have graph memory or self-reflection yet--but you'll have semantic search over your past errors, which is where most of the day-to-day value comes from.

The auth bug I mentioned at the top of this post? The minimum viable version would have caught it. The error was in the database. The fix was two queries away.

Build the full system when the minimum version proves itself. For me, that took about 3 weeks.

The minimum version will change how you think about debugging. Instead of starting from scratch each session, you'll start with a search. That shift alone is worth the 20-minute setup cost.

What's Next

The system keeps improving. Planned additions:

Cross-project learning: Patterns that work in one project suggested in others
Confidence scoring: How reliable is this learning based on how often it's worked?
Team memory: Shared knowledge base across collaborators

The Bigger Picture

This isn't just about remembering bugs.

It's about accumulating developer judgment in a searchable, queryable format.

Every debugging session teaches something. Without capture, those lessons evaporate. With this system, they compound.

Claude Code doesn't just help you code. It becomes a repository of everything you've learned about your codebase—and it gets smarter every session.

Questions about implementing this in your workflow? Reach out on LinkedIn.

Sources

Claude Code Best Practices (Anthropic)
Claude Code Hooks Documentation (Anthropic)
ChromaDB Documentation (Chroma)

Bug Bounty Automation: Building Security Workflows That Scale

Chudi Nnorukam — Fri, 10 Apr 2026 23:54:50 +0000

Originally published at chudi.dev

My first automated bug bounty scan found 47 "critical" vulnerabilities.

I submitted 12 reports. Every single one was a false positive.

The program I targeted now knows my name. Not in a good way.

That specific embarrassment is what made me rebuild everything from scratch. Not a faster scanner. Not a better scanner. A fundamentally different approach to what automation should and shouldn't do in security research.

This guide is the result: a complete system for bug bounty automation that actually works in production.

What Bug Bounty Automation Actually Is (and Isn't)

Bug bounty automation is not a script that finds vulnerabilities for you.

That framing leads directly to 47 false positive submissions and a wrecked reputation.

What it actually is: a system that handles the mechanical parts of security research — reconnaissance, asset discovery, initial scanning — while keeping humans in control of the decision that matters most: what to submit.

The best automation makes you a more effective researcher. It doesn't replace your judgment. It amplifies it.

What automation handles well:

Subdomain enumeration across certificate transparency logs
Technology fingerprinting at scale
Running known payload patterns against hundreds of endpoints simultaneously
Tracking which findings have been validated vs. just detected
Generating properly formatted reports for each platform's requirements

What automation handles poorly:

Novel vulnerability classes that don't match existing patterns
Context-aware exploitation (is this XSS actually exploitable in this specific app context?)
Deciding whether a finding is worth a researcher's reputation
Anything that requires reading the room on a specific target

Understanding this division is more important than any technical decision you'll make.

The Core Architecture: 4 Agents, One Orchestrator

After rebuilding the system twice, the architecture that works is a 4-agent pipeline coordinated by a central orchestrator.

Orchestrator (Claude Opus)
├── Recon Agents (parallel)
├── Testing Agents (max 4 concurrent)
├── Validation Agent (single, evidence-gated)
└── Reporter Agent (platform-specific formatters)

The orchestrator is a project manager, not a worker. It distributes tasks, manages rate limit budgets, detects agent failures, and persists session state between runs. It never touches an endpoint directly.

Recon Agents

Recon runs in parallel across multiple discovery methods:

Subdomain enumeration via certificate transparency (crt.sh, Censys)
Technology fingerprinting with httpx to identify frameworks, servers, CDNs
JavaScript analysis for hidden endpoints, API keys in source, internal route paths
GraphQL introspection where applicable

All discovered assets feed into a shared SQLite database. Recon agents never block each other — if subdomain enum hits a rate limit, JavaScript analysis keeps running.

Testing Agents

Testing agents take the recon output and probe for vulnerabilities. I cap these at 4 concurrent to avoid triggering WAFs or rate limits.

What they test:

IDOR: multi-account replay of authenticated requests
XSS: payload injection with response diff analysis
SQL injection: error-based and time-based patterns
SSRF: metadata service probing, internal network access
Authentication issues: token fixation, session handling edge cases

Each testing agent handles one vulnerability class. Failure is isolated — if the IDOR agent crashes, XSS testing continues unaffected.

Validation Agent: The Most Important Part

Here's the thing most bug bounty automation gets wrong: detection is not exploitation.

My payload appearing in a response means nothing. It might be in an error log that's never rendered, in an HTML attribute that's properly escaped, on a WAF block page, or in a JSON response that's never interpreted as HTML.

The Validation Agent's only job is to disprove findings.

The evidence gate process:

Every finding starts with a confidence score of 0.0 to 1.0 based on initial detection (around 0.3 for most). Confidence determines routing, not just advancement:

Confidence	Action
0.85+	Immediate human review queue
0.70–0.84	Same-day batch review
0.40–0.69	Weekly review
Below 0.40	Discarded, pattern logged

To reach 0.85+:

Baseline capture: Normal request with innocuous input. Record response headers, body length, content type.
PoC execution: Same request with malicious payload in a sandboxed environment.
Response diff analysis: Not "does the response contain my payload?" but "does the response differ from baseline in an exploitable way?"
False positive signature matching: Known-harmless patterns get auto-dismissed.

If PoC succeeds and diff analysis confirms exploitability: confidence rises to 0.85+. Queued for human review.

If PoC fails: confidence drops. Finding goes to weekly batch review, not discarded.

This is adversarial validation. The agent is trying to kill findings. Findings that survive are credible.

Since implementing this: 0 false positives submitted across 3 months.

The finding lifecycle is a state machine. Findings move through defined states with explicit transitions:

States: new → validating → reviewed → submitted / dismissed

new → validating (automatic)
validating → validating (confidence adjustment, up or down)
validating → reviewed (0.70+ confidence)
reviewed → submitted (human approval)
reviewed → dismissed (human rejection)

Confidence isn't binary. A finding can gain or lose credibility based on evidence at every step.

Reporter Agent

Once a finding clears human review and gets approved, the Reporter Agent handles formatting. Every platform has different submission requirements. I built a unified findings model plus platform-specific formatters — write the finding once, output to HackerOne, Intigriti, or Bugcrowd format automatically.

The Learning Layer: SQLite RAG

The piece I didn't plan but won't remove.

Every time an agent hits a rate limit, gets banned, or has a finding dismissed, it logs that to a SQLite database with semantic embeddings. Before running against a new target, the orchestrator queries this database — "have we seen this stack before? what broke?"

After 3 months of data, the system meaningfully avoids mistakes it's already made. That wasn't in the original design. I added it after watching the system make the same rate-limit mistake on three targets in a row. The fourth target, it slowed down automatically. That was the moment I stopped thinking of this as a script.

Three tables do most of the work:

Table	Purpose
`knowledge_base`	Semantic embeddings of past findings and techniques
`false_positive_signatures`	Known patterns that look like vulnerabilities but aren't
`failure_patterns`	Recovery strategies for different error types

The first month is calibration, not hunting. The RAG database starts empty. Every finding is evaluated without prior context, so the false positive rate is higher than steady state. By week 2, the system starts filtering patterns it's already rejected. By week 4, confidence scores mean something specific to your programs and testing patterns. Skip the calibration month and month two is chaos.

The Human-in-the-Loop Gate

Full automation for security research is wrong.

Not in a theoretical sense. Wrong in a "your reputation will be destroyed" sense.

Consider two hypothetical researchers. Researcher A submits 200 reports, 50 accepted (25% rate). Researcher B submits 50, 40 accepted (80% rate). Programs trust Researcher B. They triage faster. They pay higher. The acceptance rate compounds over months.

Finding cleared by Validation Agent (confidence 0.85+)
    ↓
Human review queue (checked once per day)
    ↓
[APPROVE] → Reporter Agent formats + submits
[DISMISS] → Logged with reason, updates false positive signatures
[INVESTIGATE] → Flagged for manual testing

Every submission has been through my eyes before it goes to a program. Non-negotiable.

What the system will never do:

Submit reports without human approval
Test targets outside registered bug bounty programs
Test out-of-scope domains (hard-blocked before execution, not just warned)
Exaggerate severity for higher bounties
Auto-resume after a ban without human authorization

After switching to mandatory human review: acceptance rate went above 80%. Programs respond faster because trust is established. Evidence packages prevent disputes.

The slow-down is worth it. 5 high-quality reports per week beats 50 that damage your reputation.

Validation: Why Detection Isn't Exploitation

The validation layer is what makes or breaks a bug bounty automation system. Most systems skip it. That's why most systems produce garbage.

A scanner finding your payload in a response proves nothing. The payload might appear in an error message that's never rendered. It might appear HTML-escaped in an attribute. It might appear on a WAF block page explaining what was filtered. Every one of those looks like a vulnerability to a pattern matcher. None of them are.

Response diff analysis is the fix. Instead of asking "is my payload in the response?" the validation agent asks "does the response differ from baseline in an exploitable way?"

Pattern	Why It's a False Positive
Payload in error message	Error messages aren't rendered as HTML
Payload in JSON response	JSON with correct Content-Type isn't executed
`<script>` in HTML	Properly escaped, not XSS
403 response with payload	WAF blocked it, not vulnerable
Reflected in `src=""` attribute	Often non-exploitable context
SQL syntax error on invalid input	Input validation, not injection

For XSS specifically: regex can't tell you if JavaScript executes. Browser validation via Playwright loads the target page, injects a marker that fires if code runs, and checks whether that marker triggers. If alert() fires, XSS is confirmed. If not — regardless of how "vulnerable" the response looks — the finding gets rejected.

The false positive signatures database stores every pattern the system has learned to dismiss. Every rejected finding adds to it. After 3 months, it filters hundreds of known-harmless patterns before they reach the review queue.

Before validation: ~40 findings per scan, 2-3 valid (90%+ false positive rate).
After validation: ~40 detections, 8-12 survive for human review, 5-7 valid (~40% false positive rate at review stage).

Still not perfect. But humans now review 12 findings instead of 40 — and 60% of what they see is real.

Failure Recovery: The 6 Categories

My testing agent hit a rate limit at 2 AM. It retried immediately. Got rate limited again. Retried. Rate limited. Retried faster. By morning, I was IP-banned from the target's entire infrastructure.

That specific failure taught me that error handling in security automation isn't optional. Generic retry loops make things worse. Every error needs classification first.

Category	Detection Pattern	Recovery Strategy
Rate Limit	HTTP 429, "too many requests"	Exponential backoff (2x multiplier, 1hr max)
Ban Detected	CAPTCHA, IP block, consecutive 403s	Immediate halt + human alert
Auth Error	401, expired token, invalid session	Credential refresh + retry (3 max)
Timeout	No response >30 seconds	Reduce parallelism + extend timeout
Scope Violation	Testing out-of-scope domain	Remove from queue + blacklist
False Positive	Validation rejection	Log pattern + update signatures

Exponential backoff for rate limits: 30s, 60s, 120s, 240s, capped at 1 hour. The ceiling matters. HackerOne resets rate limits every 15 minutes — waiting 4 hours wastes time.

Ban detection has highest priority. It checks before rate limit detection. When triggered: all agents stop immediately, human alert fires, session state saves for investigation. Never auto-resume. Human must explicitly authorize continuation.

Escalation threshold: same error category 5+ times within 5 minutes triggers human intervention. First-occurrence rate limits and single timeouts never escalate.

Before categorized recovery: ~30% of scans interrupted by unhandled errors, bans monthly.
After: ~5% need human intervention, zero bans in 6 months, 200+ learned error signatures.

Multi-Platform Integration

HackerOne needs severity ratings with their specific weakness taxonomy. Intigriti wants different field names and inline severity justification. Bugcrowd has unique bounty table structures. Without a unified model, you end up maintaining three separate report generators for the same findings.

The approach that works: one internal findings model with three platform-specific formatters. Every agent works with the unified model. Platform awareness lives only at two boundaries — ingestion (pulling scope from platforms) and submission (sending reports to platforms). Everything between is platform-agnostic.

interface Finding {
  id: string;
  title: string;
  description: string;
  vulnerabilityType: VulnType;
  cvssVector: string;        // Full CVSS v3.1 vector
  cvssScore: number;         // Calculated from vector
  severity: 'critical' | 'high' | 'medium' | 'low' | 'informational';
  poc: { steps: string[]; curl?: string; script?: string; };
  evidence: { screenshots: string[]; requestResponse: string[]; hashes: string[]; };
  confidence: number;
  status: FindingStatus;
}

Each platform formatter implements the same interface: format, validate, submit. They transform the unified Finding into what each platform expects. HackerOne maps vulnerability types to their weakness taxonomy IDs. Intigriti uses different field names. Bugcrowd requires bounty table entries mapped from severity.

The Budget Manager tracks API rate quotas per platform. Before every API call, agents check canRead() or canWrite(). If exhausted, the request queues until quota resets.

A first-mover priority system monitors all three platforms for programs launched in the last 24 hours. New programs get immediate passive recon. Active testing starts after a 2-4 hour delay for scope to stabilize. Early submissions on new programs have higher acceptance rates — less competition, more unreported surface area.

Tools and Stack

Orchestration: Claude Opus (orchestrator), Claude Haiku (testing agents)
Recon: httpx, subfinder, amass, crt.sh API
Testing: Custom Python agents per vulnerability class, Playwright for JS analysis
Validation: Docker sandboxed execution, custom response diff library
Storage: SQLite with sqlite-vec for semantic search
Platform integration: HackerOne API, Intigriti API, Bugcrowd API
Infrastructure: VPS ($40/mo) — not serverless, you need persistent state. See my Python agent deployment guide for setup
Total monthly cost: ~$180 ($40 VPS + ~$140 Claude API)

What I'd Do Differently

Start with the Validation Agent, not the scanner. The scanner is interesting. The validation layer is what actually matters. Build it first.

Cap concurrent agents at 4 from day one. Started with 10. Got IP-banned from 3 programs in two weeks.

Build the human review queue before anything else. The moment you can submit without a gate is the moment you will. Build the gate first.

Accept that it won't make you rich quickly. This system makes you roughly 3.5x more effective. That's the actual value proposition.

Current Results (3 Months In)

12 active programs being monitored
~30 findings surfaced for human review per week
~4-6 submitted after review
0 false positives submitted
~$180/month running cost
~3.5x throughput increase vs. manual research

Building something similar? The hardest part is the validation layer. Start there — everything else is just plumbing.

The multi-agent patterns behind this system are in the Battle-Tested Builder Kit — CLAUDE.md templates, agent routing rules, and verification gates you can drop into your own projects.

Sources

OWASP Web Security Testing Guide (OWASP)
OWASP Top Ten (OWASP)
MITRE CWE (MITRE)

Claude Code vs Cursor vs GitHub Copilot: Which One Actually Ships Better Production Code?

Chudi Nnorukam — Fri, 10 Apr 2026 23:54:36 +0000

Originally published at chudi.dev

I spent three months building a trading bot in production. Real money on the line. 4,000 lines of Python across 22 files. WebSocket feeds from Polymarket, Binance price data, Chainlink oracles, SQLite databases, and a systemd deployment pipeline.

During those three months, I used Claude Code for 95% of the work. But I also tested Cursor and GitHub Copilot on the exact same codebase to understand where each tool actually excels.

All three tools are good. But they solve completely different problems.

Claude Code shipped the bot. Cursor could have shipped it faster if I sat at the keyboard the whole time. Copilot could autocomplete most of it if I knew exactly what I wanted to write.

I paid for all three tools myself. Claude Code costs me $200/month, Cursor is $20/month, Copilot is $19/month. I have skin in the game to pick the right tool.

Here's what nobody tells you: picking the wrong tool doesn't just slow you down. It trains you to work differently. I watched a friend spend six months with Copilot autocomplete, then switch to Claude Code and feel completely lost because he'd built a mental model around "I drive, the tool types." Claude Code requires the opposite mental model. The tool drives. You supervise.

That inversion is where most developers get tripped up. They grab whatever their team already uses, force it to do things it wasn't designed for, and blame the tool when it underperforms. Meanwhile the engineer down the hall using the right tool for the right workflow ships twice as fast.

What Does Each Tool Actually Do Best?

Claude Code is an autonomous agent: it reads your codebase, writes code, runs tests, and fixes failures without you in the loop. Cursor is an IDE built for inline editing speed. GitHub Copilot is autocomplete. Each excels at a different layer of the coding workflow.

Best for production systems with real money: Claude Code (prevents costly mistakes via instruction system)

Best for code editing speed: Cursor (2-3x faster than Claude Code's terminal workflow)

Best for pure autocomplete: GitHub Copilot (trained on GitHub, knows all patterns)

Feature	Claude Code	Cursor	GitHub Copilot
Multi-file editing	Autonomous (20+ files)	Manual per file	Manual per file
Cost/month	$100-200 (Max plan)	$20 (Pro)	$10-19
Best for	Architecture, refactors	Inline editing	Autocomplete
Context window	200K tokens	128K tokens	Limited
Terminal integration	Native CLI	IDE plugin	IDE plugin
Autonomous execution	Yes	Partial	No

How Did I Test These? Same Codebase, Same Tasks, Real Metrics

I used the same 4,000-line Python trading bot as the test environment for all three tools. Same five tasks, same codebase, same definition of done: all tests pass, no LSP errors, feature works in production. I timed every task from "start" to "verified complete."

I didn't run contrived benchmarks. I used each tool to solve actual problems in a real production trading bot.

The codebase:

4,000 lines across 22 Python files
WebSocket integrations, asyncio loops, SQLite database layer
Real external dependencies (py-clob-client, Binance SDK, web3.py, Chainlink feeds)
87 unit tests

The tasks:

Add a new signal source (Chainlink oracle, 150 lines)
Refactor position tracking across 5 files (200 lines changed)
Fix a bug in accumulator state machine (10 lines, wrong location)
Deploy and verify on VPS via SSH
Write a test file from scratch (80 lines)

How I measured:

Time from "start" to "all tests pass"
Number of iterations before correct solution
Whether the tool caught type errors before runtime
Whether the tool understood cross-file dependencies

Why Does Claude Code Win for Production Systems?

Claude Code wins for production systems because it's the only tool that understands your entire codebase, enforces your architecture rules via CLAUDE.md, runs tests autonomously, and catches type errors before runtime. For multi-file work with real money on the line, that autonomy is worth $200/month.

Claude Code is not a copilot. It's an agent that can explore your codebase, understand dependencies, write code, run tests, and fix failures without you touching the keyboard.

Multi-file autonomy

I said "add a Chainlink oracle feed to the signal bot." Claude Code:

Explored the codebase structure (Glob, Grep, lsp_workspace_symbols)
Read existing signal sources to match patterns
Created the new oracle module
Wired it into signal_bot.py
Added it to config.py with safe defaults
Wrote tests
Ran the test suite
Fixed failures without asking

150 lines written. Zero follow-ups needed. 45 minutes elapsed. All tests passed on first try.

Cursor and Copilot could not do this. They would write individual files, and I would have to wire them together, run tests, and tell them what broke. This is the core difference that makes Claude Code a force multiplier for large refactors and architecture work.

The instruction system (CLAUDE.md)

I maintain a project instructions file that Claude Code reads on startup:

- Architecture: "All database operations use async context managers"
- Naming: "Signal modules are signal_<name>.py"
- Error handling: "All state machine transitions log to SQLite"
- Deployment: "Never use sed -i on .env. Always backup first"
- Testing: "Run pytest before deployment. Check lsp_diagnostics for type errors"

Claude Code follows these instructions. Cursor and Copilot don't even know they exist.

Example: I had a bug where config.py loaded .env via load_dotenv() on every import. This caused all instances to read the wrong config. The fix was in my instruction file: "Never use load_dotenv(). Pass ENV_PATH explicitly." Claude Code caught this when reviewing other code. Cursor would not.

Type checking and diagnostics

Claude Code runs LSP diagnostics and pytest before declaring victory. It catches 80% of runtime errors at write time.

# Claude Code ran lsp_diagnostics after editing position_executor.py
# Output: error at line 47: "position_id" is not defined
# Claude Code read the file, found the typo, fixed it
# Never got to runtime

Cursor has inline type hints but doesn't proactively check. Copilot has no type awareness. This automated verification is critical for production systems. I built mine with a two-gate verification system that Claude Code enforces via the instruction system.

Where Claude Code falls short

Terminal-only workflow. Claude Code is a terminal agent. For single-file edits, Cursor is 10x faster. Editing a line in Cursor takes 2 seconds. Editing via Claude Code takes 20 seconds (read, understand, edit, verify, diagnostics).

Expensive. $200/month on the Max plan. For small projects, it's not worth it. For my use case (22 files, multi-file refactors, real money), Claude Code paid for itself by preventing 2 bugs that would have cost $50+ each. If you're wondering if it's worth the cost, check how I built my trading bot. That project shows the real ROI.

Can go off the rails. Agents can hallucinate. I've had Claude Code delete the wrong file, write tests that don't test anything, and suggest changes that break other parts. The safety valve is always: "Did you run tests? Are all diagnostics clean?" This is why I built my AI code verification system: two gates before every deploy.

Learning curve. You need to understand prompts, git, bash, and context management. If you're building ADHD-friendly workflows, Claude Code's instruction system is a game-changer: see how I use it for focused work. Cursor and Copilot work in any IDE without ceremony.

Why Is Cursor the Fastest for Editing?

Cursor beats every other tool on single-file edit speed. Highlight code, describe the change in chat, accept: 5 seconds versus 25 seconds in Claude Code's terminal workflow. If you spend 4 hours a day editing existing files, Cursor saves you 3+ hours per week. That's the one thing it does better than everything else.

Cursor is VS Code with AI built in: tab autocomplete trained on your codebase, inline chat, Composer for multi-file editing, and @codebase context that understands your entire repo.

Inline editing speed

I timed myself editing the same file in both tools.

File: position_executor.py (200 lines). Task: "Add a size calculation that scales with volatility."

Claude Code: Read file, understand context, edit via Edit tool, verify, run diagnostics = 25 seconds
Cursor: Highlight region, type in chat, accept changes = 5 seconds

If you spend 4 hours a day editing code, Cursor saves you 3+ hours per week.

@codebase understanding

Cursor's @codebase context is genuinely good. I asked "Where are all the places we parse market prices?" and it found all three locations across different files. All correct, all in one search.

Claude Code can do this via lsp_workspace_symbols + Grep, but it's more manual.

Where Cursor falls short

Context limits. I hit the limit trying to refactor the entire signal pipeline (22 files, 4,000 lines). It could only see 15 files at once. Claude Code has 1M context tokens and can load your entire codebase. See how I manage context for large projects.

No autonomy. Cursor requires you to drive each file. I asked it to add an oracle feed. It wrote the oracle module perfectly. But it didn't wire it into signal_bot.py, didn't update config.py, didn't write tests. I had to ask four more times.

No instruction system. Cursor has no equivalent to CLAUDE.md. You can't set project-wide rules like "always backup .env before editing." It has no memory of your patterns across sessions. See how I use instruction files for focused work.

When Should You Just Use GitHub Copilot?

Use GitHub Copilot when your primary workflow is writing new boilerplate in languages you already know well. It's the cheapest option ($10-19/month), works in every IDE including Vim and PyCharm, and autocompletes class definitions, imports, and repetitive patterns at 5x your typing speed. Don't expect it to understand your architecture.

Copilot is the narrowest tool: autocomplete. You type, it predicts the next line. And it's genuinely good at that one thing.

I opened a fresh file and typed class PositionExecutor: with def __init__. Copilot predicted the next 8 lines perfectly. Instance variables, type hints, docstring. Hit Tab, done.

For boilerplate you've written 100 times, Copilot is 5x faster than typing.

The trade-off: Copilot has no multi-file awareness. It doesn't know your architecture. It doesn't run tests. It doesn't know if the code it autocompleted is correct.

# Copilot autocompleted:
position_id = order_response['id']  # Fails: 'id' not in order_response

# Should be:
position_id = order_response['tokenId']  # Correct

Copilot doesn't know the difference. It just saw similar patterns on GitHub.

How Do They Compare Head-to-Head?

The table below covers every meaningful dimension: autonomy, cost, speed, context limits, and learning curve. Claude Code dominates multi-file work. Cursor dominates single-file speed. Copilot dominates cost and breadth. No single tool wins every category.

Feature	Claude Code	Cursor	GitHub Copilot
Autocomplete	No	Yes (trained on your codebase)	Yes (trained on GitHub)
Chat with code	Yes (terminal)	Yes (inline)	No
Multi-file understanding	Yes (LSP + Grep)	Partial (@codebase limited)	No
Multi-file editing	Yes (autonomous)	Partial (Composer)	No
Autonomous refactoring	Yes	No	No
Testing integration	Yes (runs pytest)	No (syntax only)	No
Type checking	Yes (LSP diagnostics)	Partial (IDE background)	No (IDE only)
Instruction system	Yes (CLAUDE.md)	No	No
IDE native	No (terminal)	Yes (VS Code)	Yes (all IDEs)
Single-file edit speed	25s	5s	2s (autocomplete)
Multi-file refactor speed	45 min (autonomous)	2-3 hours (manual)	Not feasible
Cost	$200/month	$20/month	$19/month
Learning curve	High (shell, LSP, git)	Low (IDE, chat)	None (autocomplete)

Which Tool Should You Pick?

Pick Claude Code for production systems with multi-file complexity. Pick Cursor if you edit existing code all day and want IDE-native speed. Pick Copilot if autocomplete is enough and you need the cheapest option across all your IDEs. Most serious developers end up using two or all three.

Or use all three. They don't conflict. Cursor and Claude Code live in different workflows (IDE vs terminal). Copilot enhances both.

Use Cursor for inline editing (fastest for single files)
Use Claude Code for multi-file refactors and testing
Use Copilot for autocompleting boilerplate

What Does This Actually Cost?

All three tools together cost $239/month ($2,868/year). That sounds like a lot until you price your time. Claude Code at $200/month prevented two bugs in my trading bot that would have cost $200+ in lost capital. Cursor at $20/month saves 3-4 hours per week. The math works at senior engineer rates.

Tool	Price	Per Year	Use Case	ROI
Claude Code Max Plan	$200/month	$2,400	Large codebases, autonomous work, testing	Prevents 2-3 bugs per month worth $50+ each
Cursor Pro	$20/month	$240	Single-file editing velocity, IDE native	Saves 3-4 hours per week of keyboard time
GitHub Copilot	$19/month	$228	Boilerplate autocomplete, all IDEs	Saves 1-2 hours per week on routine typing
Total	$239/month	$2,868	All three tools together	Best coverage for all workflows

For my trading bot project, Claude Code cost $800 over 4 months. It prevented bugs that would have cost me $200+ in lost capital. ROI: 4x.

For a smaller project (one person, 500 lines), Claude Code is not worth it. Cursor + Copilot at $39/month is the sweet spot.

The Real Difference: Can This Tool Ship Without You?

The only question that matters for production systems: if you step away for an hour, can the tool keep shipping? Claude Code can. Cursor and Copilot cannot. That's the boundary that determines which tool fits your project.

Claude Code: Yes. Full codebase understanding, tests, deployment verification, post-deploy error checking.

Cursor: Partially. It can edit files fast, but you drive the sequence. You run tests. You deploy.

Copilot: No. It's autocomplete. You write the code, it guesses the next line.

For a trading bot with real money on the line, Claude Code's ability to understand the entire system, write tests, and catch errors before deployment is worth the cost.

For editing speed and IDE-native workflow, Cursor wins.

For pure typing speed, Copilot's autocomplete wins.

My workflow today:

Claude Code for new features, multi-file refactors, testing
Cursor for quick edits in the IDE (when I know exactly what to change)
Copilot for autocompleting boilerplate (when I don't want to type import statements)

All three earn their cost.

Sources

GitHub Copilot Official Documentation (GitHub)
Cursor Documentation (Cursor)
Claude Code Documentation (Anthropic)

I Built a 36,000-Line Production Trading Bot With Claude Code

Chudi Nnorukam — Fri, 10 Apr 2026 23:53:59 +0000

Originally published at chudi.dev

I finished the first version of Polyphemus in 6 weeks. Fully autonomous Polymarket trading bot. 4,000+ lines, real money on the line. Couldn't have shipped it without Claude Code. I also wasted $340 in one month using it wrong.

Four months later, the same codebase is 36,000+ lines. Two live instances running pair arbitrage on BTC/ETH/SOL/XRP. Strategy evolved from directional to market-neutral. Eight silent production bugs found and killed before they touched live capital. All caught by a shadow-first deployment gate I built after month two.

The five principles that got it to 4,000 lines are the same ones that got it to 36,000 without entropy. Here's the case study, updated April 2026.

Why Does Claude Get Dumber as Your Project Gets Bigger?

The bigger your codebase grows, the faster Claude's context window fills up. Each session becomes less useful because the window is full of stale context instead of relevant code. By week three of Polyphemus, I was spending 20 minutes re-explaining context Claude had already "seen." By month one, my token bill hit $340. The problem isn't Claude. It's the missing system around it.

Every Claude Code guide starts with CLAUDE.md tips. Not wrong, just backwards.

The first thing I had to understand was not "how do I write better prompts." It was: why does Claude get dumber as my project gets bigger?

The answer is the context window. Every session loads your project into Claude's working memory. As your codebase grows, that memory fills up faster. By week three, I was re-explaining decisions Claude had made with me two days earlier. Architecture choices, naming conventions, API patterns: all gone. I was paying for Claude to relearn the project I'd already taught it.

That's not a Claude problem. That's a system problem. And the symptoms compound fast: re-explaining context is demoralizing, it produces worse outputs because you're summarizing instead of being precise, and eventually you stop correcting Claude because it feels pointless. You start accepting mediocre outputs. You start doing the "hard parts" manually. You've turned an AI assistant into an expensive autocomplete. By month one, I was close to giving up on the whole approach.

Here are the five things that fixed it.

Principle 1: Context is a Resource. Manage it Like One.

Most developers treat Claude's context window like unlimited RAM: load everything, let it sort out what matters. That approach blew my token budget by 58% and produced hallucinations on files Claude "remembered" but didn't actually have in scope. The fix is three tiers: always-loaded project identity (under 500 tokens), per-session task file (under 1,000 tokens), and explicit on-demand file loading. Nothing else.

Tiered context loading in practice:

Tier 1. Always loaded (under 500 tokens). CLAUDE.md at project root. What the project is, file structure, conventions. Nothing else. The map, not the territory.

Tier 2. Per-session (under 1,000 tokens). A CURRENT_TASK.md file. What you're building today, what files are involved, what "done" looks like.

Tier 3. On demand. Specific files, loaded explicitly. "Read src/core/kelly.py before we start."

Result: average session token usage dropped from ~10,000 to ~4,200 tokens. 58% reduction from one workflow change.

The rule that makes Tier 3 work: never reference a file by name without loading it first. "Update the execution module" produces hallucination. "Read src/execution/orders.py, then update the retry logic" produces accurate output.

Principle 2: Claude's Built-in Memory is Better Than Manual Note-Taking

Claude Code has two memory systems: the CLAUDE.md file you write by hand, and Auto Memory, which Claude writes itself based on corrections you make. Most developers only use the first. Using both cuts the manual overhead of session management by more than half and produces more accurate recall than notes you wrote yourself.

I wasted two weeks maintaining a sprawling set of markdown notes before I discovered this. I was carefully updating files that Claude was already tracking more accurately through auto memory.

What auto memory doesn't do: strategic decisions. If you've chosen PostgreSQL over SQLite for a reason, write that in CLAUDE.md. Auto memory captures patterns. CLAUDE.md captures architecture.

The CLAUDE.md that actually worked for Polyphemus:

# Polyphemus — Claude Context

## What this is
Autonomous Polymarket trading bot. Real money. Kelly Criterion sizing. 
Never lets an exception stop the main loop.

## Hard rules
- Never hardcode API keys. Doppler only.
- All amounts in USDC, not cents. One violation cost a real trade.
- Log every trade decision with rationale BEFORE executing.
- MAX_POSITION_SIZE is a ceiling, not a suggestion.

## What we are NOT doing
- No async. Sync is predictable.
- No ML models. Signal threshold is a float.
- No framework for the trading loop. Too much magic.

300 tokens. That's it. Short CLAUDE.md, accurate auto memory, clean context.

Principle 3: Plan Mode Before You Write a Single Line

Plan mode (/plan) lets Claude research your codebase and propose an approach without making any changes. You review the plan, redirect if needed, then approve. On any task touching more than two files, this single step eliminates the most expensive class of Claude mistake: confident, multi-file output that conflicts with existing architecture.

Without plan mode, Claude wrote 200 lines of code conflicting with an architectural decision buried in a different file. Confident. Wrong. Two hours lost.

With plan mode on anything touching more than two files:

Me: /plan Add circuit breaker to execution module.
    Pause trading after 3 consecutive losses.

Claude: [researches without touching anything]
        Proposed approach: [plan]
        Files: src/execution/orders.py, src/core/state.py
        I noticed MAX_LOSS_DAILY in src/core/config.py —
        should the circuit breaker integrate with that?

Me: Yes, but use config module, not state.py.

Claude: Understood. Implementing now...

Claude caught an integration point I hadn't mentioned. I redirected before any code was written. Plan mode costs nothing and consistently saves hours.

Principle 4: Two Gates, Not One

Two-gate verification means every Claude output clears an automated check (type checks, linting, tests in under 30 seconds) before it gets a human review pass using a fixed 6-question checklist. Before this system, 1 in 6 Claude outputs reached production with an error. After: 1 in 40. On a trading bot, that gap is the difference between an incident log and a boring afternoon.

Gate 1 is automated. A bash script: type checks, linting, tests. 30 seconds. Catches ~60% of errors.

#!/bin/bash
python -m mypy . --ignore-missing-imports && echo "✓ Types" || exit 1
python -m ruff check . && echo "✓ Lint" || exit 1
python -m pytest tests/ -q && echo "✓ Tests" || exit 1

If Gate 1 fails, paste the error back: "Fix only what's causing this error. Nothing else." That last sentence matters. Without it, Claude fixes the error and refactors three other things.

Gate 2 is a 6-question checklist. Five minutes, manual, non-negotiable:

1. Does this do exactly what I asked — not more?
2. Are external API calls using the correct endpoints?
3. Is error handling present on every async/IO operation?
4. Are there hardcoded values that should be env vars?
5. Does this break anything that was already working?
6. Can I explain every line if someone asks me tomorrow?

Question 6 catches the most issues. If I can't explain a line, I don't ship it.

Principle 5: Treat Compaction Like a Power Outage. Plan for It.

When Claude's context window fills, it compacts: nuance gets discarded, recent decisions disappear, and the next response starts from a degraded state. The fix is a pre-compaction ritual at the end of every meaningful session. One prompt to update CURRENT_TASK.md, record new decisions, and write a 2-sentence handoff note for the next Claude instance. Recovery time: 90 seconds.

At the end of every meaningful session, one prompt:

We're wrapping up. Please:
1. Update CURRENT_TASK.md with current state
2. Add new decisions to CLAUDE.md's decisions section
3. Write a 2-sentence next-session starter — what the next 
   instance of you needs to know to resume immediately

That third item is the key. Claude writing handoff notes for Claude produces better handoffs than I can write myself. When a new session starts:

Read CLAUDE.md and the "Next session" section of CURRENT_TASK.md.
Confirm your understanding before we continue.

90 seconds. Full speed.

The Numbers, Updated April 2026

These aren't projections. This is the actual state of a production system that started at 4,247 lines in December 2025 and hit 36,096 lines four months later, running pair arbitrage on BTC/ETH/SOL/XRP. Every number below is from a live system, not a benchmark.

Metric	Before System	After System
Lines of code	4,247 (Dec 2025)	36,096 (Apr 2026)
Avg session tokens	~10,000	~4,200
API cost/month	$136 (month 1, unoptimized: ~$340)	$136 ongoing
Error rate to production	1 per 6 outputs	1 per 40 outputs
Silent bugs caught by shadow gate	0	8 (none hit live capital)
Test coverage	41%	73%
Uptime since December	N/A	99.2%
Claude Code sessions	~180 (Dec)	400+ (Apr)

The system rather than the prompts made the difference. Claude Code is a force multiplier. Without a system, it's an expensive way to ship buggy code faster. For a deeper look at verification workflows, see my post on evidence-based AI code verification.

The 6th principle I'd add today: shadow-first before every live deploy. Run a dry-run instance in parallel. Collect evidence. Gate on n_completed >= 50 before promoting. In April alone, that gate caught a bug where set("BTC") was returning {'B','T','C'} instead of {'BTC'}. The bot would have traded the wrong assets live. Eight bugs like that. Zero P&L damage.

Every principle here was learned the hard way: real bugs, real money at risk, real debugging sessions at 2am on a QuantVPS SSH terminal. I also built a self-improving RAG system that captures these learnings automatically so future Claude sessions don't repeat past mistakes.

What I Didn't Cover Here

The five principles in this post are the foundation. There's a full advanced layer above them: hooks that run Gate 1 automatically after every file write, subagents routing cheap tasks to smaller models, agent teams for parallel feature development, and MCP servers giving Claude direct live database access. Each of these requires the foundation to be working first.

The full advanced system is in the Claude Code Guide: Advanced Edition. It includes hooks that run Gate 1 automatically after every file write (no manual step), subagents routing cheap tasks to smaller models (44% cost reduction with progressive context loading), agent teams for parallel feature development, checkpointing for safe architectural experiments, and MCP servers giving Claude direct access to the live database for debugging. You need the foundation before the advanced layer is useful.

The guide includes the complete Polyphemus architecture walkthrough. If you're deploying your own bot, here's my step-by-step VPS setup on DigitalOcean.

If this case study was useful, the best thing you can do is send it to one developer still burning money using Claude Code without a system.

— Chudi

hello@chudi.dev | chudi.dev

Sources

Building a Python Trading Bot: What Actually Works in Production

Chudi Nnorukam — Fri, 10 Apr 2026 23:53:08 +0000

Originally published at chudi.dev

System Architecture Overview

When I started building a trading bot, I expected the hard part to be the trading logic. It wasn't. The hard part was building a system that could run continuously for weeks without losing state, crashing silently, or entering impossible positions.

A production trading bot needs five core modules that work together:

Signal Generation - Monitors price feeds and generates trade signals
Position Management - Executes trades, tracks holdings, and prevents overlapping positions
Exit Strategies - Knows when to close positions and takes profits or cuts losses
State Persistence - Survives process crashes, power failures, and restarts
Health Monitoring - Detects stuck orders, orphaned positions, and api failures

Each module can fail independently, so the system needs to handle partial failures gracefully. A signal can fail without crashing position management. An API call can timeout without losing the position state. The monitoring system watches everything and alerts when something goes wrong.

The entire codebase is about 4,000 lines of Python. Claude Code wrote 95% of it, including the most complex parts: the asyncio event loop, the database schema and queries, and the deployment scripts.

The repo is private for now, but I'm planning to open source the core trading logic once it's hardened further.

Signal Generation

Signals are the input to the entire system. My signals come from two sources: Binance price momentum and Polymarket market odds.

Binance provides real-time price data via WebSocket. I watch 5-minute price movements and detect breakouts above 2-sigma bands. When BTC price breaks upward sharply, I look for corresponding prediction markets on Polymarket that are underpriced relative to the momentum.

The signal pipeline is documented in my post on Binance-Polymarket momentum signal generation. The key insight is that prediction market prices lag price momentum by 30-90 seconds, creating a small window to profit from the difference.

The Momentum Window

Here's how the signal generation actually works in code:

async def detect_momentum_breakout(candles: list[dict]) -> float | None:
    """
    Watch 5-min BTC candles and detect 2-sigma breakouts.
    Returns signal strength (0-1) if breakout detected.
    """
    closes = [c['close'] for c in candles[-20:]]  # Last 20 candles
    mean = sum(closes) / len(closes)
    variance = sum((x - mean) ** 2 for x in closes) / len(closes)
    std_dev = variance ** 0.5

    current_close = closes[-1]
    z_score = (current_close - mean) / std_dev

    if z_score > 2.0:  # Upside breakout
        return min(1.0, z_score / 3.0)  # Cap at 3-sigma
    return None

When a signal fires, the system calculates how many standard deviations above the mean the price has moved. A 2-sigma move occurs about 2% of the time randomly, but when combined with Polymarket underpricing, the edge becomes real.

The efficiency gap between crypto spot prices and prediction markets exists because:

Crypto moves on technicals and sentiment (fast)
Prediction markets move on fundamental news cycles (slower)
Retail traders on Polymarket have longer decision latency than algo traders on Binance

This isn't a edge I'll have forever. As more traders build similar systems, the 30-90 second window compresses. But for now, it's consistent enough to trade.

Signals feed into a queue. The position manager processes signals one at a time, ensuring we never accidentally open two positions on the same market.

Position Management

Once a signal arrives, the position manager decides: do we take this trade, or skip it?

The decision logic checks:

Do we already have a position in this market? If yes, skip.
Is the order book deep enough to execute at reasonable prices? If no, skip.
Has this market been active for more than 24 hours? Recent markets are illiquid.
Are we at our maximum concurrent positions? If yes, skip.

If all checks pass, the position manager places a limit order on the Polymarket CLOB. The CLOB is Polymarket's central limit order book for derivatives trading. It's lower latency than the REST API but requires understanding the order book structure.

See my detailed post on building the Polymarket trading bot for the specifics of CLOB integration.

The position manager tracks every open position in SQLite. Each position stores:

Market ID and outcome tokens
Entry price and quantity
Timestamp and signal strength
Current mark-to-market value
Status (open, closing, closed)

This database survives process restarts. On startup, the position manager reads the database and reconstructs the exact state it was in before the crash.

Exit Strategies

The hardest part of algorithmic trading is exits. Most retail traders focus on entries but skip profitable or know when to close positions. It's the difference between "cool idea" and "actual profit."

I use three exit types:

Profit target - Close 50% of position at 2% profit, rest at 5% profit
Stop loss - Close entire position if it drops 3% below entry
Time decay - If a position hasn't moved in 4 hours, close it (markets that aren't moving are wasting capital)

The exit manager runs every minute, checks all open positions, and executes exits that meet criteria. It places exit orders as limit orders too, so we get the best available prices.

The Math on Asymmetric Position Sizing

Here's why the split profit target works. Say I enter a position at $0.45 on a binary market with $100 per trade:

Winning trades (55% of the time):

Exit 50% at $0.459 (2% profit): +$0.90
Exit remaining 50% at $0.4725 (5% profit): +$2.25
Total on winner: +$3.15 (3.15% return on $100)

Losing trades (45% of the time):

Stop loss hits at $0.4365 (3% below entry): -$3.00
Total on loser: -$3.00 (-3% return on $100)

Expected value calculation:

EV = (0.55 × $3.15) + (0.45 × -$3.00)
EV = $1.73 + (-$1.35)
EV = +$0.38 per $100 bet

That's positive EV at a 55% win rate. Drop to 54% and the math flips negative. This is why signal quality matters more than quantity. A 60% win rate turns $0.38 per $100 into $0.60 per $100. Signal strength compounds.

The split exit structure protects against reversal. If the market hits 2% and I've already cashed out half, the second half can either hit 5% or get stopped out. Either way, I've locked 50% of the winning outcome. That's risk management.

The asymmetry is deliberate. I lose 3% on losers but capture 2-5% on winners because prices move differently on prediction markets. They don't move in smooth linear paths. They bounce. A tight 1% stop gets triggered by noise. A 3% stop lets the position breathe.

State Tracking for Reliable Exits

The position database tracks exit status for each open position:

CREATE TABLE positions (
    id INTEGER PRIMARY KEY,
    market_id TEXT,
    entry_price REAL,
    entry_qty INTEGER,
    entry_time TEXT,
    stop_loss_price REAL,      -- 0.4365 for 0.45 entry
    target_one_price REAL,     -- 0.459 (2% profit)
    target_two_price REAL,     -- 0.4725 (5% profit)
    exit_status TEXT,          -- 'open', 'half_closed', 'closing', 'closed'
    target_one_filled_at TEXT,
    target_two_filled_at TEXT
);

On every minute, the exit manager reads current market price and compares against these thresholds. When target one hits, it updates exit_status to 'half_closed' and records the fill time. This prevents double-exits and ensures the second half of the position doesn't exit prematurely.

Limit orders are crucial here. Market orders on Polymarket can slip 0.5-1% depending on order book depth. A limit order at target_one_price of $0.459 sits on the book until filled. If the market only reaches $0.458, the order stays open. If it bounces to $0.461, it fills at $0.459 (better than market order at $0.461). Over 100 trades, limit order precision saves 0.3-0.5% in aggregate slippage.

The real lesson: don't set stop losses too tight on prediction markets. Binary outcomes mean prices bounce around more than equity markets. A 1% stop gets triggered by noise. 3% gives the position room to breathe while still protecting against real reversals.

Read my post on betting math for binary markets to understand the probability calculations that feed into exit sizing.

The trickiest exit is time decay. Prediction markets converge to 0% or 100% as the event approaches. If I'm long and the market isn't moving, the time decay works against me. Exiting stale positions frees capital for new signals.

One thing that surprised me: the time decay exit generated more total profit than the profit target exit. Not because individual exits were bigger, but because freeing stale capital meant the bot could take 2-3 more trades per day. Capital velocity matters more than any single trade's P&L.

Paper to Live Transition

I paper-traded for 6 weeks before going live. Paper trading means simulating trades without real money, just tracking P&L in spreadsheet.

Paper trading revealed two strategy failures:

Liquidity trap - The culprit was insidious: entry prices looked good because I was catching markets in transition, when stale limit orders sat on the books. But exit? Nightmare. On markets with under < $50K order book depth, I'd win the entry at $0.45 then get forced out at $0.42 because no one was buying. The tight spread at entry reversed hard at exit. Across 30 paper trades, this cost pattern showed up 7 times. Each time: entry P&L looked profitable (+2-3%), but the exit slippage erased it. One trade: up $2.25 on 50% exit at 2% profit, then the final 50% couldn't execute near target. Ended up closing at $0.41 (-4% from entry) because the order book evaporated. That single trade went from +$3 to -$1. Multiply that by 7 failed exits across the paper period, and I'm looking at roughly $2,000 in prevented losses once I added the liquidity check.

The fix was a simple gate before position entry:

async def check_market_liquidity(market_id: str) -> bool:
    """
    Only enter if order book has sufficient depth.
    Skip if spread > 1% of mid-price or total depth < threshold.
    """
    order_book = await polymarket.get_order_book(market_id)
    best_bid = order_book['bids'][0]['price']
    best_ask = order_book['asks'][0]['price']
    mid = (best_bid + best_ask) / 2
    spread_pct = ((best_ask - best_bid) / mid) * 100

    total_depth = sum(qty for _, qty in order_book['bids'][:5]) + \
                  sum(qty for _, qty in order_book['asks'][:5])

    if spread_pct > 1.0:  # Spread too wide
        return False
    if total_depth < 500:  # Not enough size to exit
        return False
    return True

This single filter would have prevented 7 bad trades and saved ~$2,000 in real losses.

Signal timing - The second failure was time-dependent. Signals arriving during European market hours (roughly 2-8 AM UTC, when US traders sleep) got filled at punishment prices. Same signal, same market, but the order book was thin and slow-moving. I'd get a signal on BTC momentum at 5 AM UTC. By the time I placed the order, retail traders on Polymarket hadn't woken up yet. Bid-ask spread was 0.5-1% instead of 0.2%. Fills were 200-300 basis points worse than signals arriving during US peak hours (12pm-11pm UTC). Over the 30 paper trades, only 6 arrived during European dead hours, but those 6 had 0.5-1% worse fills than identical signals during US hours. That's roughly $1,500 in prevented slippage if I'd filtered those out.

The time-of-day filter was even simpler:

async def is_peak_trading_hour() -> bool:
    """
    Only process signals during peak US trading hours.
    12pm-11pm UTC captures most US market activity.
    """
    now_utc = datetime.datetime.utcnow()
    current_hour = now_utc.hour

    # Peak hours: 12pm-11pm UTC (7am-6pm EST)
    if 12 <= current_hour < 23:
        return True
    return False

async def should_process_signal(signal: dict) -> bool:
    if not await is_peak_trading_hour():
        return False  # Skip this signal
    return True

That's it. One hour check prevented $1,500 in unnecessary slippage by avoiding markets where the book moves like molasses.

Both failures would have cost real money live. The 6-week cost in time was worth it.

I ran at least 30 paper trades before going live. That's the minimum to see the major failure modes. Anything less and you're just guessing.

Sources

Polymarket CLOB API Documentation (Polymarket)
How I Built a 4,000-Line Production Trading Bot With Claude Code (chudi.dev)

Deploy Python Agents on DigitalOcean for $6/Month

Chudi Nnorukam — Fri, 10 Apr 2026 23:52:14 +0000

Originally published at chudi.dev

Disclosure: This post contains affiliate links to DigitalOcean. If you sign up through these links, I earn a commission at no extra cost to you, and you get $200 in free credits for 60 days. I ran my trading bot on a DigitalOcean Droplet before migrating to a specialized VPS for lower latency. I recommend DO for Python agents because I used it and it worked.

My Python trading bot worked perfectly on my laptop. Asyncio event loop, WebSocket connections to Binance, real-time order placement on Polymarket. Clean code. Passed review. Ran great locally.

Then I tried to deploy it.

The first attempt was AWS Lambda. Cold starts added 400ms to every signal. The 15-minute timeout killed my long-running WebSocket connections. I spent two days fighting CloudWatch logs before I realized: Lambda was built for HTTP request handlers, not for a process that needs to stay alive.

Here's what I wish someone had told me: deploying a Python agent that runs 24/7 costs $6/month and takes 30 minutes. Not $50. Not $80. Six dollars.

I ran my Polymarket trading bot on a $6 DigitalOcean Droplet for months. It processed live Binance price feeds, placed orders on the CLOB, and managed exits autonomously. 69.6% win rate across 23 clean trades. The infrastructure never failed me. The server was not the bottleneck. It never was.

This is the setup guide that would have saved me those two days on Lambda.

What does a Python agent actually need?

Most developers pick their deployment platform based on what they already know. If you've used AWS before, you reach for EC2 or Lambda. If you're a Heroku person, you spin up a dyno. Nobody stops to ask: what are the actual infrastructure requirements?

A long-running Python agent requires:

A process that stays alive (not a function that runs and dies)
Persistent connections (WebSocket feeds, database connections)
Predictable cost (not pay-per-invocation that spikes when your bot gets active)
Full control over the runtime (Python version, system packages, cron)

Here's what it does not need:

Auto-scaling (your bot is one process)
Load balancers (it's not serving HTTP traffic)
Managed runtimes (you want control, not guardrails)
A $50/month bill for resources you'll never use

That last point stings. If you're running a single Python agent on Heroku ($7-25/mo), Railway ($5 + metered usage), or an EC2 instance you forgot to right-size ($15-80/mo depending on how lost you got in the AWS console), you're paying for infrastructure designed for problems you don't have.

How do DigitalOcean costs compare to AWS, Heroku, and Railway?

I evaluated four providers before my first deploy. Here's the honest comparison:

Provider	Monthly Cost	Best For	The Catch
AWS EC2	$8-80/mo	You already live in AWS	Console is a maze. Surprise bills are real. A t3.micro costs $8, but you'll add EBS, bandwidth, and by month 3 you're at $35 wondering what happened.
Heroku	$7-25/mo	Quick web app deploys	Dynos sleep on the free tier. Paid tier starts at $7 but a worker dyno for a bot is $25. No SSH access. Limited debugging.
Railway	$5 + usage	Git-push simplicity	Usage-based pricing sounds cheap until your bot runs 24/7. A busy month can cost $20-40.
DigitalOcean	$6/mo flat	Bots, agents, anything that runs 24/7	Fewer regions than AWS. You manage your own server. That's it.

I picked DigitalOcean. $6/month flat. No metered surprises. Full root access. The documentation read like it was written by someone who actually uses the product. I went from zero to running bot in 28 minutes.

Here's what that $6 gets you: 1 vCPU, 1GB RAM, 25GB SSD, 1TB transfer. My trading bot (asyncio event loop, multiple WebSocket connections, real-time order placement) used about 200MB of that RAM. The CPU barely touched 5% between trading signals.

Most of you are overpaying. Let me show you the setup.

What do you need before starting?

You need three things: Python 3.10 or higher on your local machine, an SSH key pair (generate one with ssh-keygen -t ed25519 if you don't have one), and 30 minutes of uninterrupted time.

That's literally all the prerequisites.

Step 1: Create a Droplet (2 Minutes)

Log into DigitalOcean and create a new Droplet:

Region: Pick the closest to your data source. For my trading bot, I chose Amsterdam (5-12ms to Polymarket's CLOB in London). For a general agent, pick the region nearest whatever API you call most.
Image: Ubuntu 24.04 LTS
Size: Basic, Regular, $6/month (1 vCPU, 1GB RAM, 25GB SSD)
Authentication: SSH Key (paste your public key from ~/.ssh/id_ed25519.pub)

Never choose password authentication. SSH keys only. This is non-negotiable. I'll explain why in Step 2.

The Droplet spins up in about 60 seconds. Grab the IP address from the dashboard. Test your connection:

ssh root@YOUR_DROPLET_IP

That root prompt means you have a server. Running. Waiting for your code. For $6/month, you now own a machine that will run 24/7 whether or not you're watching.

Step 2: Lock It Down (10 Minutes)

I skipped this step the first time. A week later, I checked the auth log and found 3,000 brute-force SSH attempts from IPs I'd never seen. Nothing was compromised (SSH keys are strong), but it was a wake-up call.

Ten minutes of security setup prevents real problems:

# Create a deploy user (never run your bot as root)
adduser --disabled-password agent
usermod -aG sudo agent

# Copy your SSH key to the new user
mkdir -p /home/agent/.ssh
cp /root/.ssh/authorized_keys /home/agent/.ssh/
chown -R agent:agent /home/agent/.ssh
chmod 700 /home/agent/.ssh
chmod 600 /home/agent/.ssh/authorized_keys

# Disable root login and password auth
sed -i 's/PermitRootLogin yes/PermitRootLogin no/' /etc/ssh/sshd_config
sed -i 's/#PasswordAuthentication yes/PasswordAuthentication no/' /etc/ssh/sshd_config
systemctl restart sshd

# Enable the firewall
ufw allow OpenSSH
ufw --force enable

Log out. Reconnect as the agent user:

ssh agent@YOUR_DROPLET_IP

You now have a locked-down server. Root login disabled, password auth disabled, firewall active. This is what separates a production server from a tutorial project.

Step 3: Set Up Python (3 Minutes)

Ubuntu 24.04 ships with Python 3.12. Set up a virtual environment:

sudo apt update && sudo apt install -y python3-venv python3-pip

mkdir -p ~/my-agent
cd ~/my-agent

python3 -m venv venv
source venv/bin/activate

pip install aiohttp websockets python-dotenv

Always use a venv. I learned this the hard way when a system-level pip install broke apt's Python dependencies on my first Droplet. Took me an hour to untangle. A venv takes 10 seconds to create and prevents that entirely.

Step 4: Deploy Your Agent (5 Minutes)

Here's a production-ready async agent skeleton. This is the same pattern my trading bot used. Replace the inner logic with whatever your agent does:

# ~/my-agent/agent.py
import asyncio
import signal
import logging
from datetime import datetime

logging.basicConfig(
    level=logging.INFO,
    format="%(asctime)s [%(levelname)s] %(message)s",
    handlers=[
        logging.FileHandler("agent.log"),
        logging.StreamHandler()
    ]
)
logger = logging.getLogger(__name__)

shutdown_event = asyncio.Event()

def handle_signal(sig, frame):
    logger.info(f"Received signal {sig}, shutting down gracefully...")
    shutdown_event.set()

async def process_tick(data: dict):
    """Your agent logic goes here."""
    logger.info(f"Processing: {data}")

async def run_agent():
    """Main agent loop. Replace with your real logic."""
    logger.info("Agent started")

    cycle = 0
    while not shutdown_event.is_set():
        try:
            await process_tick({"cycle": cycle, "ts": datetime.utcnow().isoformat()})
            cycle += 1
            await asyncio.sleep(10)

        except Exception as e:
            logger.error(f"Agent error: {e}")
            await asyncio.sleep(5)

    logger.info("Agent stopped cleanly")

def main():
    signal.signal(signal.SIGTERM, handle_signal)
    signal.signal(signal.SIGINT, handle_signal)
    asyncio.run(run_agent())

if __name__ == "__main__":
    main()

Create a .env file for configuration:

# ~/my-agent/.env
API_KEY=your_api_key_here
POLL_INTERVAL=10
LOG_LEVEL=INFO

Test it on the Droplet:

cd ~/my-agent
source venv/bin/activate
python3 agent.py

You should see log output. Press Ctrl+C to stop. If it runs for 30 seconds clean, you're ready for the part most tutorials skip.

How do you keep a Python agent running 24/7 on a Droplet?

Use systemd. This is the critical step separating "I deployed my bot" from "my bot runs in production."

Running your agent in screen or tmux kills it when SSH disconnects, server reboots, or when your code crashes at 3am with nobody watching. I lost 6 hours of trading signals before learning about systemd.

systemd handles three essential tasks:

Automatically restarts your agent if it crashes
Starts it on server reboot without manual intervention
Manages logs for debugging and audit trails

Create a service file:

sudo tee /etc/systemd/system/my-agent.service << 'EOF'
[Unit]
Description=My Python Agent
After=network-online.target
Wants=network-online.target

[Service]
Type=simple
User=agent
WorkingDirectory=/home/agent/my-agent
Environment=PATH=/home/agent/my-agent/venv/bin:/usr/bin
EnvironmentFile=/home/agent/my-agent/.env
ExecStart=/home/agent/my-agent/venv/bin/python3 agent.py
Restart=always
RestartSec=10
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
EOF

Enable and start:

sudo systemctl daemon-reload
sudo systemctl enable my-agent
sudo systemctl start my-agent

Check it:

sudo systemctl status my-agent

active (running). Your agent now survives reboots, crashes, and SSH disconnects. Close your laptop. Go to sleep. It keeps running.

Step 6: What are the common mistakes after deployment?

I hit all of these. You'll hit at least two.

1. "ModuleNotFoundError" after deploy

systemd runs its own environment. If ExecStart points to python3 instead of /home/agent/my-agent/venv/bin/python3, it uses the system Python which doesn't have your packages. Exact path. Every time.

2. Agent dies silently after 6 hours

An unhandled exception in the main loop. Without the try/except wrapper, the agent crashes, systemd restarts it, it crashes again on the same data, and you hit the restart rate limit. The backoff sleep is not optional.

3. Disk fills up from logs

journalctl handles systemd logs, but your agent.log file grows without bounds. I discovered this after a 2GB log file ate my 25GB disk. Add log rotation:

sudo tee /etc/logrotate.d/my-agent << 'EOF'
/home/agent/my-agent/agent.log {
    daily
    rotate 7
    compress
    missingok
    notifempty
}
EOF

4. SSH disconnect kills the agent

Only happens if you started with python3 agent.py & in a shell session. systemd doesn't have this problem. If you're still running bots in tmux: stop. Use systemd.

How do you deploy code changes to your running agent?

When you update your agent code:

# From your local machine
scp agent.py agent@YOUR_DROPLET_IP:~/my-agent/

# Restart the service
ssh agent@YOUR_DROPLET_IP "sudo systemctl restart my-agent"

# Verify clean start
ssh agent@YOUR_DROPLET_IP "sudo journalctl -u my-agent -n 10 --no-pager"

Three commands. Under 10 seconds. I started with scp and switched to git-based deploys after the third time I forgot to push a dependency file. For a single agent, scp is fine.

What should you verify before going live?

Before you trust your agent with real work or money:

[ ] SSH key auth only (password auth disabled)
[ ] Firewall active (ufw status shows SSH allowed, everything else denied)
[ ] Non-root user running the agent
[ ] systemd service with Restart=always
[ ] Error handling in the main loop (catch, log, backoff, continue)
[ ] Signal handlers for SIGTERM/SIGINT
[ ] Log rotation configured
[ ] Monitoring (check logs daily until stable)

If your agent handles money, also add: position limits, stop-losses, health check endpoints, and alert notifications. I documented the full trading bot architecture, risk management, and signal detection patterns in my Polymarket trading bot guide.

When do you outgrow a $6 Droplet?

I migrated away from DigitalOcean when my trading strategy demanded sub-10ms round-trip latency to Polymarket's CLOB. The Amsterdam region provided 5-12ms, which worked for my initial strategy. When I needed 3-5ms consistency, I switched to a specialized VPS provider colocated near the exchange.

That migration took 4 months. It only mattered because I was doing latency arbitrage where 100ms cost me money.

For most Python agents, you will not outgrow a $6 Droplet for years.

You'll know it's time to upgrade when:

Milliseconds matter: Your agent's profitability depends on execution speed
Multiple agents: You're running 4+ processes and hitting CPU/RAM limits
GPU inference: Your agent runs ML models that need a GPU
Compliance: You need certifications or regions DO doesn't offer

Until then, every month you spend more than $6 on infrastructure for a single Python agent is money you didn't need to spend.

Start Here

If you've been running your bot on Lambda hitting execution timeouts, paying $25/month for a Heroku worker dyno, or avoiding deployment because AWS console complexity paralyzes you:

Sign up for DigitalOcean (claim $200 in free credits for 60 days, enough to test this entire setup cost-free)
Follow the 6-step process above (30 minutes total, no dependencies)
Replace the example agent skeleton with your actual logic
Run through the production checklist and monitor for 48 hours

Result: $6/month. 30 minutes setup time. Your agent running 24/7 on infrastructure you control completely.

For trading bot builders: Start with my guide on building a Polymarket trading bot to understand signal detection, order placement, risk management, and profitability metrics. Then return here for the deployment infrastructure. My bot achieved 69.6% win rate on this exact setup before migrating for latency reasons.

For general AI agents: This Droplet setup works equally well for data crawlers, scheduled scrapers, webhook processors, LLM orchestration systems, and autonomous agents. The pattern applies to any Python process that needs 24/7 uptime without paying cloud premium prices.

What are you deploying? I'm curious what agents people are running on VPS these days.

Sources

DigitalOcean Droplet Documentation (DigitalOcean)
systemd Service Units (freedesktop.org)
Python asyncio Documentation (Python Software Foundation)
DigitalOcean SSH Key Setup (DigitalOcean)

Claude Code Hooks Tutorial: 4 Production Patterns for Code Guardrails

Chudi Nnorukam — Fri, 10 Apr 2026 23:51:56 +0000

Originally published at chudi.dev

I ran a secret scanner on every project for months before I realized Claude Code was writing .env files with real credentials baked in. Not because it was malicious. Just because the context had a key, and it needed a value.

The fix took five minutes once I knew hooks existed.

Claude Code hooks let you run any shell command automatically when tool events fire. Before a file gets written, after a bash command runs, when Claude finishes a task. You get full context about what's happening via stdin, and for PreToolUse hooks, you can block the operation entirely.

This is the guide I wish I had when I started.

What Are Claude Code Hooks and Why Do You Need Them?

Claude Code is an autonomous agent. It reads files, writes code, runs commands, and makes decisions faster than you can review each one. That autonomy is the point. But it creates a gap: how do you enforce standards without reviewing every action manually?

Hooks close that gap. They're your enforcement layer — running in the background, checking every operation against your rules, and either approving it or blocking it before any damage is done.

Think of them as middleware for your AI agent. The tool fires an event, your hook intercepts it, does its check, and returns a decision. If the hook returns {"continue": false}, Claude stops. If it returns {"continue": true} (or nothing), Claude proceeds.

What Are the Four Claude Code Hook Events?

Claude Code exposes four events you can hook into (see official hooks docs):

PreToolUse — fires before any tool runs. You can inspect the tool input and block execution. This is where guardrails live.

PostToolUse — fires after a tool completes. You get the tool output. Use this for logging, formatting, or triggering follow-on actions.

Notification — fires when Claude sends a notification (waiting for input, task complete, etc.). Good for custom alerts.

Stop — fires when the agent finishes a task. Use this for cleanup, summaries, or Slack notifications.

There's also SubagentStop which fires when a subagent finishes, if you're running parallel agents.

Where Do You Configure Claude Code Hooks?

Everything goes in ~/.claude/settings.json. The structure looks like this:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "/Users/you/scripts/scan-secrets.sh"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "/Users/you/scripts/auto-format.sh"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "/Users/you/scripts/notify-complete.sh"
          }
        ]
      }
    ]
  }
}

The matcher field is a regex matched against the tool name. Write|Edit matches both the Write tool and the Edit tool. Leave it out to match all tools for that event.

What your hook receives

Every hook gets a JSON object via stdin. For a PreToolUse hook on the Write tool, it looks like this:

{
  "session_id": "abc123",
  "hook_event_name": "PreToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/Users/you/project/.env",
    "content": "STRIPE_SECRET_KEY=sk_live_abc123..."
  }
}

For a Bash tool, tool_input contains command instead of file_path. For Edit, you get file_path, old_string, and new_string. The shape matches the tool's schema.

PostToolUse hooks also get tool_response — the actual output the tool returned.

What your hook must return

This is the part that trips people up.

If your hook writes anything to stdout, it must be valid JSON. The Claude Code protocol reads stdout as structured data. If you print plain text, you'll get protocol errors.

#!/bin/bash
# WRONG - will break the protocol
echo "Scanning for secrets..."
echo '{"continue": true}'

# RIGHT - suppress all non-JSON output
exec 2>/dev/null
echo '{"continue": true}'

The valid return fields are:

{
  "continue": true,
  "suppressOutput": false,
  "decision": "approve",
  "reason": "No secrets found"
}

continue: false blocks the tool. suppressOutput: true hides the hook output from Claude's context. reason gets shown in the UI when you block.

If your script exits with code 0 and returns nothing, Claude proceeds. If it exits non-zero, Claude treats it as a blocking error.

Hook 1: Secret scanner

This is the one I wish I'd had from day one. It runs before any Write or Edit and blocks the operation if it finds credentials.

#!/bin/bash
# ~/.claude/scripts/scan-secrets.sh

exec 2>/dev/null

INPUT=$(cat)
CONTENT=$(echo "$INPUT" | python3 -c "
import json, sys
d = json.load(sys.stdin)
ti = d.get('tool_input', {})
print(ti.get('content', '') + ti.get('new_string', ''))
" 2>/dev/null || echo "")

# Check for common secret patterns
PATTERNS=(
  'sk_live_[A-Za-z0-9]+'
  'xoxb-[A-Za-z0-9-]+'
  'AKIA[A-Z0-9]{16}'
  'ghp_[A-Za-z0-9]{36}'
  'rpa_[A-Za-z0-9]+'
  'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9'
)

for pattern in "$\{PATTERNS[@]}"; do
  if echo "$CONTENT" | grep -qE "$pattern"; then
    echo "{\"continue\": false, \"reason\": \"Blocked: potential secret detected matching pattern $pattern\"}"
    exit 0
  fi
done

echo '{"continue": true}'

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit|NotebookEdit",
        "hooks": [{ "type": "command", "command": "/Users/you/.claude/scripts/scan-secrets.sh" }]
      }
    ]
  }
}

Now every file write goes through the scanner. If it finds a Stripe live key, Slack token, or AWS key, it blocks with a reason Claude can read and explain.

Hook 2: Auto-formatter

After Claude edits a TypeScript or Python file, run the formatter automatically. No more "Claude wrote valid code but wrong indentation."

#!/bin/bash
# ~/.claude/scripts/auto-format.sh

exec 2>/dev/null

INPUT=$(cat)
FILE=$(echo "$INPUT" | python3 -c "
import json, sys
d = json.load(sys.stdin)
print(d.get('tool_input', {}).get('file_path', ''))
" 2>/dev/null || echo "")

if [[ -z "$FILE" ]]; then
  echo '{"continue": true}'
  exit 0
fi

case "$FILE" in
  *.ts|*.tsx)
    command -v prettier &>/dev/null && prettier --write "$FILE" &>/dev/null
    ;;
  *.py)
    command -v ruff &>/dev/null && ruff format "$FILE" &>/dev/null
    ;;
esac

echo '{"continue": true}'

PostToolUse on Edit:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "/Users/you/.claude/scripts/auto-format.sh" }]
      }
    ]
  }
}

The formatter runs silently after every edit. Claude's next read of the file sees clean, formatted code without any back-and-forth.

Hook 3: Slack notification on task complete

I work with Claude running in the background while I do other things. The Stop hook lets me know when it's done without watching the terminal.

#!/bin/bash
# ~/.claude/scripts/notify-complete.sh

exec 2>/dev/null

TOKEN="$\{SLACK_BOT_TOKEN:-}"
CHANNEL="$\{SLACK_NOTIFY_CHANNEL:-}"

if [[ -z "$TOKEN" || -z "$CHANNEL" ]]; then
  echo '{"continue": true}'
  exit 0
fi

INPUT=$(cat)
SESSION=$(echo "$INPUT" | python3 -c "
import json, sys
print(json.load(sys.stdin).get('session_id', 'unknown'))
" 2>/dev/null || echo "unknown")

curl -sf -X POST https://slack.com/api/chat.postMessage \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d "{\"channel\":\"$CHANNEL\",\"text\":\":white_check_mark: Claude finished task (session: $SESSION)\"}" \
  > /dev/null

echo '{"continue": true}'

{
  "hooks": {
    "Stop": [
      {
        "hooks": [{ "type": "command", "command": "/Users/you/.claude/scripts/notify-complete.sh" }]
      }
    ]
  }
}

Now when a long refactor finishes, my phone buzzes.

Hook 4: Approval gate for destructive bash commands

This one requires more care. Some bash commands are irreversible — dropping databases, deleting branches, modifying production configs. The PreToolUse hook on Bash lets you intercept these.

#!/bin/bash
# ~/.claude/scripts/approve-destructive.sh

exec 2>/dev/null

INPUT=$(cat)
CMD=$(echo "$INPUT" | python3 -c "
import json, sys
print(json.load(sys.stdin).get('tool_input', {}).get('command', ''))
" 2>/dev/null || echo "")

DESTRUCTIVE_PATTERNS=(
  'rm -rf'
  'drop table'
  'DROP TABLE'
  'git push --force'
  'git reset --hard'
  'kubectl delete'
  'systemctl stop'
)

for pattern in "$\{DESTRUCTIVE_PATTERNS[@]}"; do
  if echo "$CMD" | grep -qF "$pattern"; then
    echo "{\"continue\": false, \"reason\": \"Blocked: '$pattern' requires explicit approval. Run the command manually if intended.\"}"
    exit 0
  fi
done

echo '{"continue": true}'

This doesn't ask for approval interactively — that would deadlock. Instead it blocks and explains. You review the command, run it yourself if it's correct, and Claude continues from there.

Gotchas that cost me time

Shell profile output breaks hooks. If your .zshrc or .bashrc prints anything (greeting messages, nvm output, conda activation), it will pollute the hook stdout. Either suppress it or use exec 2>/dev/null at the top of every hook script.

Hooks run in a non-interactive shell. Your PATH, aliases, and shell functions aren't loaded. Use full absolute paths to commands (/opt/homebrew/bin/prettier, not prettier).

PreToolUse latency adds up. If your hook takes 500ms and Claude runs 50 Edit operations, that's 25 extra seconds. Profile your hooks. Secret scanning should be under 50ms. If it's slow, check for regex backtracking.

The matcher is a regex, not a glob. Write|Edit works. Write* does not.

Empty stdout is fine, but non-JSON stdout breaks things. Add exec 2>/dev/null to redirect stderr, then only ever echo valid JSON.

My actual settings.json hooks section

This is what I run across all projects:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Write|Edit|NotebookEdit",
        "hooks": [{ "type": "command", "command": "/Users/chudinnorukam/.claude/scripts/scan-secrets.sh" }]
      },
      {
        "matcher": "Bash",
        "hooks": [{ "type": "command", "command": "/Users/chudinnorukam/.claude/scripts/approve-destructive.sh" }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "/Users/chudinnorukam/.claude/scripts/auto-format.sh" }]
      }
    ],
    "Stop": [
      {
        "hooks": [{ "type": "command", "command": "/Users/chudinnorukam/.claude/scripts/notify-complete.sh" }]
      }
    ]
  }
}

Four hooks. They cover the 90% case: secrets, destructive commands, formatting, and completion notifications. Everything else I handle manually because the hook overhead isn't worth it for low-frequency events.

Where to go from here

Hooks are composable. You can chain multiple hooks on the same event. You can use them to log every tool call to a file for auditing. You can build approval workflows that post to Slack and wait for a reply before proceeding.

The pattern I'm building toward: a full audit log of every Claude action, with replay capability. Every Write, Edit, and Bash call gets logged with the session ID, timestamp, and tool input. When something goes wrong, I can reconstruct exactly what happened and in what order.

That's the next post. For now, start with the secret scanner. It's the one hook that pays for itself the first time it catches something.

If you're using Claude Code for real projects, you already know the trust issue. You can't review every edit. Hooks are how you stop trusting blindly and start trusting with guardrails.