Jon Atkinson - Blog

The Hypocrisy of Agentic Coding Critics

2026-03-26T12:00:00Z

Every week I read another post arguing that LLM coding agents are fundamentally untrustworthy. The code is buggy. The output needs reviewing. The agent doesn’t fully understand the domain. It hallucinates progress. It tests only the happy path.

All valid criticisms. I’ve been managing software engineers for years, and this list sounds awfully familiar.

Consider engineers, real ones with degrees and salaries and opinions about typing systems and ORMs and Kubernetes:

Produce code containing bugs. Every sprint. Consistently. 100% of the time.
Provide cursory code reviews, approving changes they haven’t actually read.
Begin work on features without fully understanding the domain, figuring they’ll learn as they go.
Are optimistic about progress, sometimes to the point of fiction.
Test only the happy path, because the edge cases are tedious and the deadline is Thursday.
Throw commits to live on a Friday afternoon without running the test suite, then disappear for the weekend.

None of this is controversial. Every engineering manager has lived through all of it. And none of it stops us from hiring engineers, trusting them with production systems, or building entire organisations around their output.

Instead, we built disciplines to compensate. Code review processes. QA teams. CI pipelines. Incident reviews. Post-mortems. The history of software engineering is largely the history of building systems to catch human mistakes before they reach production. We didn’t reject human engineers because they were fallible. We built structures around their fallibility because their contribution was worth the effort.

Now consider the common arguments against LLM coding agents:

The code needs human review.
The agent might introduce subtle bugs.
It doesn’t understand the broader architecture.
It can produce plausible-looking output that’s fundamentally wrong.
It works best on the straightforward cases and struggles with nuance.

Read that list again. Swap “agent” for “new hire” and nothing changes. These are the same failure modes we’ve been managing in humans for decades. The difference is that when a human exhibits them, we call it a development opportunity. When an LLM exhibits them, we call it a fundamental flaw and reach for the ‘slop’ accusation.

So why the double standard?

I think the discomfort is less about the quality of LLM output and more about the loss of a familiar model. We know how to manage humans. We have intuitions about when someone is struggling, when they’re bullshitting, when they need support. We’ve built careers around those intuitions. An LLM doesn’t fit neatly into that model, and that’s unsettling.

But if you step back from the emotional response, the engineering problem is the same: you have a contributor that produces imperfect output, and you need processes to ensure that imperfect output doesn’t reach production unchanged. We solved this problem already. We solve it every time we onboard a new team member.

There’s also something worth acknowledging about professional identity. For many engineers, the craft of writing code is the job. The idea that a machine can do a version of it, even an imperfect version, feels like a challenge to something personal. That’s understandable, and I don’t think dismissing that feeling is helpful. But it shouldn’t be confused with a technical argument about capability, the the technical argument is frequently pushed above the emotional reaction.

We need to concentrate on structures, not perfection.

The value of a coding agent isn’t that it produces perfect code. Neither does anyone on your team. The value is that it produces reviewable code at a speed and volume that changes what’s possible.

Organisations built management structures around messy, nondeterministic humans because the value of human contribution was obvious despite the mess. The same logic applies here. The question was never whether the output is flawless. It never has been, for anyone. The question is whether you can build processes around the tool that capture its value while containing its weaknesses.

And in many cases, the processes already exist. Code review catches bugs regardless of who or what wrote them. CI pipelines don’t care about the author. Tests either pass or they don’t. Type checkers don’t have opinions. Linters are indifferent to feelings. The infrastructure we built to manage human fallibility works just as well for managing LLM fallibility.

In some cases it works better, because an LLM will never take your review comments personally, never push back on making the ‘right’ call because it’s Friday afternoon, and never quietly revert your suggested changes in a follow-up commit.

So, the more productive conversation isn’t “should we use LLM agents?” but “what structures do we need to adapt?” Some existing processes transfer directly. Others need rethinking.

Code review, for instance, needs to evolve. When a human writes code, the reviewer can assume a certain baseline of intent: the author understood the requirements, made deliberate choices, and can explain their reasoning. With LLM-generated code, those assumptions don’t hold. The reviewer needs to verify not just correctness but appropriateness. That’s a different skill, and it’s one we should be actively developing in our teams rather than using its absence as a reason to avoid the tool.

Similarly, testing becomes more important, not less. If you’re integrating LLM-generated code, your test coverage needs to be comprehensive enough to catch the kinds of mistakes LLMs characteristically make. This isn’t a new problem. It’s the same argument we’ve always made for good test coverage. The LLM just makes the case more urgent.

The real risk isn’t that LLMs produce imperfect code. It’s that teams adopt them without the structures that make any contributor safe. An LLM without code review is dangerous. So is a human without code review. The failure mode is identical: unreviewed code reaching production.

If your processes can’t catch bad code regardless of its source, the problem isn’t the LLM. The problem is your processes.

If you’re going to argue that LLMs aren’t ready for production engineering work, I think you need to grapple with why the same flaws are acceptable in human engineers. If the answer is “humans understand what they’re doing,” I’d gently suggest sitting in on a few more code reviews. Understanding is a spectrum, and a significant amount of production code was written by people who were working it out as they went.

The honest assessment isn’t that LLMs are reliable. They are not, and pretending otherwise does everyone a disservice. But they’re a new kind of contributor with a familiar set of failure modes, and we already have decades of experience managing those failures in humans. The question is whether we’re willing to adapt our playbook, or whether we’d rather pretend that human-only engineering was working flawlessly all along.

Because it wasn’t. We just got used to it.

Thanks to Ben for listening to me rant about this in person, which turned into this post.

Nobody buys software from Intel

2026-02-05T12:00:00Z

When did you last care which chip was in your laptop? Not which laptop, or which operating system, but which actual silicon processor was doing the work. Unless you’re a gamer or someone running heavy compute workloads, the answer is probably never. You bought the machine because of what it could do, not because of what was inside it. Intel and AMD are invisible.

I’ve been thinking about this a lot recently, because I think it’s where LLM providers are heading. The companies pouring billions into training frontier models are building the CPUs of the AI era. They employ brilliant people, burn staggering amounts of capital, and produce genuinely remarkable technology. And if history is any guide, that’s not the comfortable position it sounds like.

The substrate

Intel employs over 100,000 people. They spend north of $15 billion a year on research and development. The engineering required to design and fabricate modern processors is among the most complex work humans have ever attempted. The same is true of AMD, Qualcomm, Apple’s chip division, and the handful of other companies pushing the boundaries of what silicon can do.

And yet, nobody buys software from Intel. Outside of very specific workloads, very few users pick an application because of which chip it runs on. When you open a browser or launch an IDE, the processor underneath is an implementation detail. It’s infrastructure. It’s the substrate on which everything else grows.

This wasn’t always the case. There was a time when “Intel Inside” was a genuine selling point, when clock speed was the metric that mattered, when consumers actually cared about the difference between a Pentium III and a Pentium 4. But the value migrated upward. Operating systems, applications, services, platforms. Silicon became a commodity. Still essential, still incredibly sophisticated, but invisible.

LLMs are starting to follow the same path. The difference between GPT-4o and Claude and Gemini, for most practical tasks, is shrinking. A year ago, model choice felt like it mattered enormously. Today, I still have preferences, but I’d struggle to articulate why in terms that would survive a blind test. Ask me why I prefer Claude over GPT for coding work, and I’ll give you an answer that’s more vibes than evidence. The models are converging, and the gap narrows with every release cycle.

What Anthropic is actually selling

Claude Code is the most interesting thing Anthropic makes right now, and it isn’t a model. It’s a product. A tool you install, configure, learn to use, build habits around. The underlying model matters, obviously, but what keeps me opening my terminal every morning is the workflow, not the weights. I’ve spent thousands of dollars on Claude Code at this point. I didn’t spend that money because of the model’s benchmark scores. I spent it because the tool makes me more productive, and the experience of using it keeps getting better.

Think about what Anthropic gets from Claude Code that they don’t get from API access alone. They’re watching how people actually use the tool in real working environments. They see which workflows succeed and which ones frustrate. They see where people get stuck, where they lose trust, where they give up. That telemetry is extraordinarily valuable, and it’s driving development decisions as much (possibly more) than the underlying model research. When Anthropic decides what to improve next, they’re not just looking at abstract capability evaluations. They’re looking at what real users do in real sessions.

Consider the trajectory. Claude Code launched as a fairly basic CLI tool. Within months it had hooks, custom commands, MCP server integrations, project-level configuration. Those features didn’t come from model improvements. They came from watching people use the product and understanding what was missing. Product development, not research.

The feedback loop here is the real competitive advantage: real usage generates insight, insight improves the product, the improved product attracts more usage. This is a product flywheel, not a model flywheel. Benchmark scores don’t capture it. Training compute doesn’t explain it. It’s the accumulated understanding of how humans and AI tools actually collaborate on real work.

OpenAI is doing the same thing with Codex and ChatGPT. Google with Jules and Gemini’s integrations. Cursor has built an entire company on the premise that the product layer is where the fight happens. The model underneath is important in the way that a good engine is important in a car. Sure, there are enthusiasts who care very much about an engine being a V8, or supercharged; but among the general consumers in the car-buying demographic, nobody test-drives an engine.

Models, tools, product

If you think of the stack as three layers (models at the bottom, tools in the middle, products at the top), each layer depends on the one below it. The model layer is where the raw capability lives. The tool layer is how that capability connects to the real world: file systems, APIs, databases, code execution. The product layer is what the user actually touches.

The model layer is converging, as I said. The tool layer is where the most interesting work is happening right now. Context management, agentic workflows, knowing when to ask the user a question versus when to just act. These are the problems that separate “impressive demo” from “useful daily driver.” I’ve been using agentic coding tools for long enough now to know that the gap between those two things is enormous, and it lives almost entirely in the tool layer.

When Claude Code decides to run my test suite after making a change, that’s a tool-layer decision. When it reads my project’s Makefile to understand how I’ve configured things, that’s tool-layer intelligence. When it stops and asks me a clarifying question instead of guessing, that’s tool-layer judgement. None of these things are about the model being smarter in some abstract sense. They’re about the product being better at the practical work of collaborating with a human.

This is also where the gap between providers becomes most visible, at least for now. I’ve tested Codex, Jules, and Claude Code against the same tasks, and the differences in outcome had almost nothing to do with the underlying model’s raw capability. They came down to practical things: did the agent read the README? Did it understand how to install the dependencies? Did it run the full test suite or just a subset? These are tool-layer failures, not model-layer failures. The model was smart enough in every case. The tooling around it was what determined success or failure.

Diminishing returns

The model race will cool off. It has to.

Each generation of improvement costs more and delivers less visible gain for most users. This is the same trajectory as CPU clock speeds in the 2000s. Remember when Intel and AMD were in a raw performance war, pushing clock speeds higher and higher? They kept improving, but the improvements stopped mattering to most people. A 3GHz chip and a 3.5GHz chip felt identical for email and web browsing. The manufacturers pivoted to efficiency, power consumption, and integrated features instead.

LLMs are approaching a similar threshold. The difference between a model that scores 90% on a coding benchmark and one that scores 93% is meaningful to researchers but largely invisible to someone using the tool to build a Django application. I can feel this in my own usage. Six months ago, a new model release would change how I worked. Today, I upgrade, notice it’s a bit faster or a bit better at long context, and carry on with my day. The improvements are real. They just don’t change my behaviour anymore.

When that happens across the board, the companies that invested in the layers above the model will be the ones standing. The ones still chasing benchmark points will be selling a commodity. A very sophisticated commodity, sure. But a commodity nonetheless. And the margins on commodities are thin, no matter how clever the engineering underneath.

Or maybe they won’t let it happen

The CPU analogy has a flaw, and it’s worth being honest about it.

Intel and AMD grew up in a less aggressive era of technology capitalism. They largely accepted their role as component suppliers. They let the value migrate upward without fighting particularly hard to capture it. Intel tried to build products a few times (remember Intel’s phone chips? Their TV ambitions?) but never with the conviction needed to succeed.

LLM vendors have the benefit of hindsight. They can see what happened to chipmakers and choose differently. OpenAI, Anthropic, and Google are already vertically integrating. They’re building the models AND the tools AND the products. They’re not content to be substrate. They want to own the full stack.

This is a rational strategy, and they might pull it off. The current generation of AI companies are far more aggressive about capturing value across the entire chain than Intel ever was. They have the talent, the capital, and the motivation.

But history is full of companies that tried to own everything and failed. Vertical integration is hard to sustain when the layers above you move faster than you can. Microsoft tried to own the browser, the search engine, the phone, the social network, the music player. They succeeded at some and failed spectacularly at others. Being the best at one layer doesn’t guarantee competence at the layers above. The skills required to train a frontier model are entirely different from the skills required to build a product that people love using every day. Great research labs don’t automatically produce great products. Ask Google about that one.

The question is whether these companies can simultaneously be the best model provider, the best tool builder, and the best product company. That’s a lot of battles to fight at once. Startups like Cursor are already demonstrating that a focused team building exclusively at the product layer can compete with, and sometimes outperform, the vertically integrated giants. If the model layer truly commoditises, there will be more companies like Cursor, not fewer. Small teams with good product instincts, plugging into whichever model is cheapest or best for their use case, iterating faster than the big labs can. That’s the world Intel accidentally enabled for PC software. It might be the world that OpenAI and Anthropic accidentally enable for AI tools.

I don’t know which way this goes. Anyone who tells you they do is selling something. But I keep coming back to the CPU analogy because the structural forces feel so similar: brilliant engineering becoming invisible infrastructure, value migrating upward, the consumer caring less and less about what’s underneath.

When I open my terminal tomorrow morning, I won’t be thinking about which model is running. I’ll be thinking about whether the tool helps me get my work done. That instinct, multiplied across millions of users, is what turns a technology into a substrate. The LLM providers can see it coming. Whether they can avoid it is another question entirely.

Developing Good Engineering Taste

2026-01-14T13:45:00Z

I was talking with a group recently about LLM-assisted engineering. I was asked how to cross the capability gap: how to feel in control with LLMs rather than dependent on them. My reply was the predictable: develop “good taste” in engineering. Which is the standard advice now, but what does that actually mean in practice?

It’s one of those things that’s obviously real; some engineers have better taste than others, and generally good taste develops over time, but it’s frustratingly hard to pin down the strategies to speed up that process. We all know it when we see it. A senior glances at a pull request and immediately spots problems. A tech lead reads a design proposal and knows it won’t scale. That’s taste and experience. But how do you get there? And how do you get there in an era where you interact with your systems via an LLM proxy?

Read Lots of Code

The best way to develop taste is exposure to quality. You can’t recognise good if you haven’t seen it.

Study well-maintained open source projects. Django itself is excellent. So is Flask. The requests library, and similar mature codebases are good places to begin.
Read the code of experienced colleagues during reviews. Not just to approve, but to learn. Ask yourself why they structured things the way they did. Role play. What did my colleague see that made them choose this design; what have they experienced in the past which informed this?
Look at commit histories of mature projects to see how they evolved. The journey matters as much as the destination. Sometimes the most instructive thing is seeing what got deleted.
Pay attention to why certain patterns emerge repeatedly across unrelated projects. If three different codebases independently arrived at the same abstraction, there’s probably something there.

This isn’t passive reading. You’re building a library of reference points in your head. When you’ve seen enough solutions to similar problems, you develop intuition for what works.

Build the ‘wrong’ reflex

When reviewing LLM-generated code (or your colleagues, or your own), practice asking:

“Would I want to maintain this in six months?”
“Is this the simplest thing that could work?”
“What happens when requirements change slightly?”
“Am I creating coupling or debt I’ll regret?”
“What would I have to explain to a new team member about this?”

This becomes instinctive with practice, but you have to actively engage with it rather than just accepting what works. The LLM doesn’t care about your future self. You have to. Projects usually move pretty fast, and if a design seems self-evident right now, consider that in a year a design may not make sense without the current context.

The key word here is feel. Early on, you need to think through these questions explicitly. Eventually, code that violates these principles just looks ‘wrong’. But you don’t get to the instinctive stage without going through the deliberate stage first.

Understand the Why Behind Patterns

LLMs are excellent at producing code that follows patterns. They’re terrible at knowing when to break them. Part of having good taste is understanding:

Why we use certain abstractions, not just that we do
What problems specific patterns actually solve
The tradeoffs involved in different approaches
When the conventional wisdom doesn’t apply

An LLM will happily apply the repository pattern to a three-line script. It’ll add dependency injection to something that will never have more than one implementation. It’ll create an abstraction layer between two things that should just talk to each other directly. Knowing when that’s absurd is taste, and these things should be triggering that same ‘wrong’ reflex.

This is where reading about software design (not just code) becomes valuable. Understand the problems that led to the solutions. When you know that a pattern emerged to solve a specific pain point, you can recognise when that pain point isn’t present and the pattern is invalid.

Work Outside the LLM Safety Net

This is uncomfortable but necessary. Set challenges like:

“Implement this ticket without any AI assistance.”
“Create a hypothesis about this issue using only docs and code reading. Test the hypothesis.”
“Refactor this module and write a sentence to explain every single edit you make.”

The struggle builds the intuition that makes LLM output assessable. If you’ve never felt the friction of solving something hard yourself, you won’t recognise when the LLM is handing you something easy that looks hard. You won’t know what is appropriate versus what is just verbose.

I imagine this is the reason musicians still practice scales even though they could just play the finished piece. The fundamentals create the foundation that makes everything else possible. Engineers who skip the fundamentals can produce output, but they can’t debug it, extend it, or explain it.

Learn to Spot the LLM tells

LLMs have characteristic weaknesses. With experience, you start recognising the patterns:

Overly defensive code which checks for conditions that can’t occur: handling errors that the type system prevents, or adding null checks on things that are never null
Missing edge cases that require domain understanding. A good tell is that the happy path works but the real-world scenarios don’t
Following outdated patterns and libraries from training data and using approaches that made sense five years ago but have been superseded
Intermixing concerns: database calls next to business logic next to presentation concerns

Learning to recognise “this feels like AI-generated code” is part of developing taste. It’s the same instinct that helps you spot code written by someone who doesn’t understand what they’re doing, because in a meaningful sense, the LLM doesn’t. It’s pattern matching without comprehension.

The Meta-Skill

The core of good taste is this: you need to be able to have a conversation with the code, understand the story which it tells, and know when it is lying to you.

That only comes from understanding at a level deeper than syntax. It comes from having written enough bad code yourself to recognise it. It comes from maintaining systems long enough to feel the consequences of piles of shortcuts.

LLMs are remarkably good at producing plausible code. Plausibility isn’t correctness, and it isn’t quality.

There’s no shortcut to this. But there is a path: read widely, build deliberately, question, and embrace the productive discomfort of feeling overwhelmed. The struggle transforms knowledge into judgment.

Building Momentum with LLM Coding

2025-12-11T12:00:00Z

LLM-assisted coding feels slow at first. Painfully slow. You’re constantly second-guessing the output, reading every line, checking for hallucinated imports and invented APIs. This is where the fear creeps in – the worry that you’re losing your craft, becoming a glorified prompt engineer who can’t actually write code anymore. Every suggestion feels like it needs to be verified, and the verification takes longer than just writing the code yourself would have.

But something shifts if you stick with it. The friction fades. Trust builds. You start to recognise the patterns in the AI’s mistakes and learn to head them off. You develop an intuition for when to accept a suggestion wholesale and when to scrutinise it. The flywheel starts turning.

This momentum isn’t automatic. You have to set things up correctly. The AI is a powerful but distractible collaborator, and your job is to create an environment where it can succeed. Here’s what I’ve learned (my preferred tool is Claude Code, so my examples probably drag that way):

One goal per session. A single context window should contain a single goal. When you finish a feature, reset the session and clear the context before starting the next one. Don’t let the details of feature A bleed into the implementation of feature B. The LLM will try to be helpful by remembering everything, but that helpfulness becomes confusion when it starts applying patterns from yesterday’s authentication work to today’s reporting feature.
Periodic review sessions. Every few major features – I aim for every three or four – run a dedicated review session. Not to build anything new, but to audit what you’ve built together. Ask the LLM to examine the codebase for architectural drift, DRY violations, and emerging patterns that should be formalised. These sessions are invaluable for catching the inconsistencies that accumulate when you’re moving fast. The AI is quite good at spotting its own mess if you explicitly ask it to look.
Save your plans. Lean heavily on planning mode. Before any significant feature, have the LLM create a detailed implementation plan and write it to a file. These plans become institutional memory. When you start a related feature later, you can say “Remember how we planned the notification system? Follow the same patterns for the alerting feature.” The AI doesn’t actually remember, of course, but it can read the file, and that’s close enough.
One log file. Bring everything from your application – backend, frontend, workers, whatever – into a single log file. Don’t make the LLM waste time and tokens figuring out how to access logs across containers or parse browser console output. When something breaks, you want to paste a log snippet and say “what’s happening here?” not spend five minutes explaining where logs live.
One project API. Give your project a well-documented Makefile with clear targets: make test, make serve, make deps, make lint. Instruct the LLM to only interact with the project through that interface. You don’t want it trying to figure out how to run your test suite from first principles every time. Provide the control panel; don’t make it rummage through wires.
Don’t optimise for token limits, ever. This is a luxury opinion, I know, but if you’re trying to structure your work to stay inside a context limit, you’re fighting the wrong battle. You’re crippling your workflow and diminishing the AI’s capabilities to save a few quid. Just buy the unlimited account. The productivity gains will pay for it many times over.
Invest in your tests. Parallelise them. Organise them into groups so you can run fast feedback loops on related code. Instruct the LLM to run the tests constantly – after every significant change, not just at the end of a feature. Most LLM coding tools support hooks; I use a stop hook to automatically run tests every time the AI finishes responding. The AI should never be allowed to move on without knowing whether it just broke something.
Alert on idle. While you’re setting up hooks, add one that alerts you when the LLM is idle. A sound, a terminal bell, whatever works. These tools can be remarkably fast when they’re in flow, and you don’t want to be the bottleneck.

The pattern here is simple: treat the LLM like a capable but context-limited collaborator. It’s possible to build real momentum and genuine trust, just as you would with a human partner. But you have to be the responsible party in the relationship. You maintain the structure. You enforce the discipline. You set the AI up to succeed, and then it will.

Thanks to my friend Vim for listening to me ramble about all this. It helped me get my thoughts together.

GitHub's spec-kit and the cloud agent endgame

2025-10-23T14:30:00Z

I’ve been playing with GitHub’s spec-kit this week. It’s pitched as a workflow tool for local LLM agents – think Claude Code, Cursor, Windsurf. The idea is structured development: specify requirements first, then plan, then implement. It works. The /speckit.constitution command establishes project principles, /speckit.clarify resolves ambiguity, /speckit.analyze validates consistency. Useful stuff for keeping local agents on track.

But spec-kit isn’t really about improving your local workflow. It’s a sketch of GitHub’s cloud agent infrastructure.

Look at the constitution concept. For a local agent, it’s helpful context. For an autonomous agent working independently in the cloud – maybe handling issues across a backlog without constant oversight – a constitution becomes essential. It’s the strongest steering signal available. The difference between an agent that stays aligned with your project’s architectural philosophy and one that drifts into technically-correct-but-architecturally-wrong solutions.

The gated process (specify, plan, clarify, analyze, tasks, implement) maps directly onto issue-based development. An agent gets assigned a ticket, works through the gates, presents checkpoints. This isn’t how you work with a local assistant watching your every move. This is how an autonomous agent would operate on GitHub infrastructure.

The clarification step is particularly revealing. It’s designed to present multiple-choice options when the agent hits ambiguity. The natural implementation? Present those options directly in the GitHub issue UI. The agent encounters a decision point, generates three viable approaches, presents them as a quick poll. You click one, it continues. Far more efficient than the current pattern of verbose questions in PR comments.

GitHub owns the platform where issues live, where CI/CD runs, where PRs are reviewed. They’re not competing with Claude Code or Cursor. They’re building the server-side infrastructure those tools will interface with, or be replaced by.

The economics push this direction. Human engineering hours cost more while compute costs less. LLM capabilities improve while inference overhead shrinks. Eventually, projects will ask why they’re manually triaging straightforward bug reports when an agent could handle most of them with human review only at decision points.

Spec-kit is GitHub showing their hand. The gated process, the constitution, the structured clarification – these aren’t just productivity features for local development. They’re scaffolding for autonomous agents living in GitHub’s cloud, operating with minimal oversight, working within boundaries established by project principles.

The local agent experience – powerful, immediate, under your direct control – is likely transitional. Spec-kit is the blueprint for what’s next.

How I use Claude Code

2025-06-25T09:06:00Z

I’ve been using Claude Code a lot recently, and I’ve settled on a workflow that’s been producing really good results. The short version is: use two separate Claude instances to challenge each other.

The first step, especially when working in an existing codebase, is context gathering. With Claude Code in “plan mode,” I’ll give it a detailed overview of the project structure. Something like:

“Examine this codebase in detail. The dependencies are documented in @pyproject.toml, and take note of the environment variables for configuration in @docker-compose.yml. The tests can be run with make test.”

If there’s any API or package documentation I’ve already downloaded, I’ll put it into the codebase in an api_docs/ folder, and explicitly tell the LLM to “examine the additional documentation in @api_docs/.” I’ve found this particularly effective when working with APIs that publish a Swagger specification; just save a copy in api_docs/ and let the LLM learn.

With the groundwork laid, I’ll then set out the upcoming context, still in planning mode:

“Our goal is to plan the delivery of feature X, Y, Z. Create for me a phased plan to build these features. Each phase should follow a theme, and each phase should contain an explicit test and documentation task. Ask any clarification questions as you need.”

This usually leads to a few rounds of question and answer as we refine the context. Eventually, as the questions dry up, I’ll instruct Claude to “Now, write this plan to .implementation_plan.md.”

This is where the second Claude instance comes in. My first prompt to this instance is:

“Based on this codebase, and the plan in .implementation_plan.md, critique this plan and help me understand where it’s underspecified, or lacking in necessary context. Tell me where you think the plan is weak, and where you would struggle.”

This burns a lot of tokens, as this second instance does a lot of reading and thinking in the background, essentially delivering the phase without writing the source files, but it’s worthwhile. I consistently get useful feedback that I can then feed back to the first instance.

I’ll then challenge the first Claude with the output from the second:

“Based on this critique, consider the points raised, and improve the plan.”

After another round of this (and it’s usually only two exchanges at most), the .implementation_plan.md is usually pretty robust.

At this point, I’ll put the first Claude instance into “auto mode.” I usually grant broad permission to any tools Claude might need; the only tools I insist on running manually are git commit and git push. My prompting now goes phase-by-phase: “Consider the codebase, and begin implementing the first phase of .implementation_plan.md.”

Usually, Claude needs a little prompting to actually run the tests after creating them, but I’ll also run them manually to keep an eye on things. I’ve noticed Claude can be a bit overzealous with testing, generating complex mocks and factories. I don’t mind these existing, but I like to keep a handle on test suite bloat, and I’ll encourage Claude to mark tests as slow if necessary and exclude them from the default test scripts.

At the end of each phase, I’ll ask the second Claude instance to “evaluate the progress in this codebase against the current .implementation_plan.md, and provide feedback.” This often produces useful challenges for the primary Claude instance, and a few rounds of back-and-forth helps ensure the phase is genuinely “complete” and nothing has been missed.

I’ll then finish the phase with a test run, a commit, and the instruction to “update .implementation_plan.md with the progress so far.” This is followed by /clearing the context of the first Claude. I find this “reset” helps prevent the LLM from going off-track. Then it’s back to the start for the next phase.

Generally, I find Claude’s phased plans are unafraid of front-loading the difficult work. The early phases are usually the most complex, with later phases focusing on simpler tasks like UI work or optimization. So, once the early phases are complete, delivery becomes smoother and less hand-holding is needed from the second Claude instance.

notion-to-json

2025-06-18T19:08:00Z

I was a big Notion user. For a while, it was my go-to for everything: project management, note-taking, knowledge bases, and a lightweight CRM. It’s a useful way to quickly build databases and organize data in a slightly more robust way than a spreadsheet, and the WYSIWYG editor is a bonus.

But there’s a catch: data is effectively held hostage. Notion’s export formats are, to put it mildly, dreadful. They’re fine for static snapshots, but useless for anything involving programmatic access or integration with other tools. I like having control over my data, and the idea of it being locked away in a platform which is tiptoeing towards the cliff of enshittification felt increasingly uncomfortable.

So I built notion-to-json.

It’s a simple command-line tool that extracts JSON from Notion pages and databases, ready to be ingested elsewhere. It’s also a good agnostic way of taking a backup of your Notion workspace, independent of their export functionality. This is the kind of software that’s notionally “easy” to create, but the details and edge cases add a lot of friction. As I’ve found with recent projects, Claude Code is excellent at dealing with those kinds of problems. The whole project took a few hours from start to finish, and includes:

Export all pages and databases from your Notion workspace.
Systematic traversal of nested content.
Progress tracking with an okay terminal UI.
Rate-limited API calls to respect Notion’s limits.

The code is available on Github.

# Using pip
pip install notion-to-json

# Using uv
uv pip install notion-to-json

# Using uvx (no installation needed)
uvx notion-to-json --api-key YOUR_API_KEY

mastodon-to-bluesky

2025-06-14T14:34:00Z

I’ve been using Bluesky more and more recently. It’s a pleasant enough place to post, though I’m still not entirely convinced by the AT Protocol, but that’s a topic for another day).

As I’ve been spending more time on Bluesky, I realised I wanted to bring over my old posts from Mastodon. Manually copying and pasting everything seemed tedious, especially with image attachments and thread structures. So I wrote a tool to automate the process.

It’s a command-line Python application, on Github. It handles fetching your Mastodon posts, converting the content, downloading media attachments, splitting long posts into threads, and posting everything to Bluesky.

I’ve tried to make it as robust and feature-rich as possible, including things like incremental transfers (so you can run it multiple times without creating duplicates), a dry-run mode for testing, filtering options, and automatic retry logic.

I’ve packaged the tool using the uv tool, which I find really convenient for managing command-line utilities. If you haven’t used uv before, go and learn about that. I promise it’s more important than migrating your social posts. As follows:

uv tool install mastodon-to-bluesky

For one-time use, you can use uvx:

uvx mastodon-to-bluesky transfer --help

Or, if you prefer the traditional pip approach:

pip install mastodon-to-bluesky

You’ll need access tokens for both Mastodon and Bluesky. The README on Github has detailed instructions for obtaining these. Once you have them, the basic transfer command looks like this:

uvx mastodon-to-bluesky transfer \
--mastodon-instance https://your.mastodon.instance \
--mastodon-token YOUR_MASTODON_TOKEN \
--bluesky-handle you.bsky.social \
--bluesky-password YOUR_BLUESKY_APP_PASSWORD

You can store your credentials in a configuration file or use environment variables.

There are also various options for controlling the transfer process. For example, to do a dry run without actually posting anything to Bluesky:

uvx mastodon-to-bluesky transfer --dry-run

Or to transfer only posts from a specific date range:

uvx mastodon-to-bluesky transfer --since 2024-01-01 --until 2024-12-31

The tool handles downloading media attachments (up to four images per post, due to Bluesky’s limitations) and splitting long posts into threads. It tries to preserve as much of the original formatting as possible, including mentions, hashtags, and links.

One of the things I focused on was making the tool robust. It tracks transferred posts to avoid duplicates and has automatic retry logic with exponential backoff for handling rate limits and transient errors.

There are some limitations, mainly due to differences between the Mastodon and Bluesky platforms. For example, Bluesky doesn’t support backdating posts, so all transferred posts will have the current timestamp. The original Mastodon timestamp is appended to each post.

I’m pretty happy with how the tool turned out. It scratched my own itch, and hopefully it’ll be useful for others migrating from Mastodon to Bluesky. It’s another example of how quickly you can build this kind of software with LLM assistance. The whole project took about 3 hours from start to finish.

Good practice is good for LLMs too

2025-06-08T20:00:00Z

LLMs are changing how we write software. In the face of this unheaval, it’s tempting to think these tools somehow absolve us from following good engineering practice. We have fifty or so years of layered wisdom, and sticking close to this knowledge not only makes your codebase more robust, it enhances the LLM capabilities and developer experience.

One of the most important practices, now more than ever, is comprehensive test coverage. Ideally, your test suite should be granular enough to run relevant tests after each AI tool use. I’ve been using pytest for years, and recently added pytest-watch to my workflow. It’s a small thing, but being able to see tests run automatically in the background as I’m prompting the LLM gives me immediate feedback and catches regressions early. You need automated, fast QA looking over the AI’s shoulder.

Branch discipline is another essential practice. With LLMs, it’s easier than ever to generate (and just as easily discard) large chunks of code. Keeping your LLM-assisted work on a dedicated, short-lived branch with a single, clearly defined purpose makes it trivial to revert changes if things go sideways. This isolates the impact of any AI-induced chaos to the specific feature or code area you’re working on. Put up the safety net.

Another thing I’ve started doing recently is keeping a detailed work diary. This is invaluable for rebuilding LLM context over multiple sessions, especially when working on larger features or complex refactoring. While your commit history provides a record of what changed, the work diary captures the why – the reasoning behind decisions, alternative approaches considered, and future plans. We talk a lot about building context for the LLM, but remember your own personal context is an extremely lossy system.

DRY – Don’t Repeat Yourself – is a fundamental principle of good software design. It’s even more important when working with LLMs, as they have a tendency to reinvent wheels (sometimes quite badly). A well-defined application architecture, with clear separation of concerns, helps guide the LLM towards reusing existing code rather than generating duplicates. For example, in Django projects, I usually have a models.py, views.py, and a services.py for business logic. This isn’t anything special, but I stick to the conventions, and keep everything in it’s right place. The more you stick to a predictable structure, the easier it is for the LLM to understand the context and generate code that fits seamlessly into your existing codebase. The agents are easily distracted, but a clear set of instructions and a tidy workspace – they’re much more likely to produce something useful.

Finally, good task ergonomics are essential. A root Makefile or justfile with clearly defined tasks (setup, deploy, lint, test) provides the LLM with a standardized way to interact with your project. This saves tokens and reduces the risk of the LLM trying to figure out novel (and probably incorrect) ways to perform common operations. Provide the AI with a well-labeled control panel instead of making it rummage through a box of wires.

LLMs are powerful tools, but they’re not magic. The good practices we developed to work with humans still apply to working with a cloud AI.

Codex, Jules, and Claude Code comparison

2025-05-23T09:28:00Z

I’ve tried three of the newer agentic code assistants this week: OpenAI Codex, Google Jules, and Claude Code.

I asked each of them to operate in the same codebase, which is a personal app which I built to track my finances. It’s a pretty straightforward Django CRUD application, which tracks account balances over time, does some lightweight reporting, and can produce charts of the account balances, that kind of thing. There is very little Javascript, and it uses Bootstrap for the UI.

I gave each agent the same task:

"""
I'm not happy with the name `accounts` as the application which deals with financial accounts. The name `accounts `is overloaded in web application development, and it might clash with other models in the system. I've decided it should not be used in this context.
Instead, this should be renamed to `money`, and all the side effects should be dealt with:
- Updating URL patterns throughout.
- Updating the `accounts:` namespace in all {% url %} tags.
- Updating import statements throughout.
- Ensuring the tests continue to pass.
At the same time, let's squash the migrations.
"""

This is a pretty simple request, one which I’d expect a junior software engineer to be capable of performing, though it would rely on some knowledge of Django patterns, understanding migrations, and how to find and update references to a package.

OpenAI Codex

I setup the repository access via the web UI, gave it the task, and it immediately began working.

The agent’s security model allows it internet access during the container bootstrap, but not after. The repository is pretty simple in layout, and the deployment is Herokuish, so I’d expect the AI to pickup from the requirements.txt file that this was a Python project, and know to install the dependencies. Instead, the container started, and no dependencies were installed.

Looking through the thinking log of the agent, it noticed very early that the dependencies were not installed, but decided to continue anyway. It then performed the task, but it’s approach was quite superficial (replacing the string accounts with money wherever it was found).

The AI then tried to run the tests, but not in the way that is documented in the README.md, or present in the Makefile (the correct way to run the tests is just make test, which will deal with migrating, running the tests, calculating coverage etc.). Instead it tried to use the standard Django ./manage.py test approach. Regardless of approach, this failed, as no dependencies were installed.

Rather than stop, the AI then decided that the tests not running wasn’t a problem, and YOLO’d up a PR with the changes. The total runtime was about 20 minutes.

I pulled the PR locally, and ran the tests, which failed catastrophically due to a Python syntax error which was introduced in a migration file.

This was a very poor impression, and it reinforces my opinion that OpenAI has lost their first-mover advantage. The product felt rushed and incapable.

Grade: F

Google Jules

Jules appears to be a highly beta product, and was clearly struggling with high load when I ran the test.

There were parts of the UI which I really liked, specifically a diff viewer for each file the agent touched. I think this is a really useful visible indicator of progress (or being stuck in a rabbit hole). This is more akin to the in-IDE agents like Cline, and I think it’s a useful middle ground.

Container setup was successful, and the AI found and installed my requirements. It appears that Google trust their Gemini model to access remote resources at any time, so there wasn’t the same limitations as Codex displayed. Interestingly, it seems that their base container has uv installed already, and it prioritied using uv over pip, though this also missed the documented steps in the README.md, which would have pointed it to running make setup.

It follows the pattern which I’ve found particularly useful when using agentic assistants: plan then act, and presented the plan for my approval. The plan was reasonable in it’s approach, and I requested it begin.

For some reason (again, maybe high load), when the agent was about half way through the planned steps, it stopped and asked for my approval to continue. I was happy to give approval, and then it continued to the second-to-last step in the plan (running the tests), and stopped, telling me the code was “Ready for Review”, and prompting me to hit a button to create the PR in my Github repository. Our last step in the plan, to squash the migrations, was never attempted.

The tests passed, the refactoring was successful, but the whole process took around an hour. I’m interested in seeing how this progresses as I think Gemini is the standout model across most tasks at the moment. Jules is a very early product and it shows, but so does the potential. I wonder how many IDE features Google plan on implementing in the browser.

Grade: C

Claude Code

I’ll preface this by saying that I’ve used Claude Code via the CLI extensively since it launched (I’m at least $2000 deep), so I had some preconceptions here. However, the day this launched was also the launch of Opus 4, a significant upgrade to the underlying model.

Setup was the most awkward of the products, relying on the claude CLI tool, and gh for Github operations. The process of authenticating with Github was similar to any other OAuth application, but Claude Code operates entirely as a Github-based tool, and doesn’t have any UI outside of interactions in Issues and PRs.

I copied and pasted my task description into a new ticket, and then notified it to begin work with “@claude work on this ticket”. This triggers two effects: the agent updated the ticket with a detailed plan, and triggered a long-running Github Action to perform the work.

I like being able to see the agent’s plan, though there was no opportunity to amend the plan or provide further guidance. I also liked being able to connect to the Github Action log and see in detail the tools the agent was using, and the detailed, very verbose output from the session.

Claude Code completed the task after about 12 minutes, having run a limited subset of the tests (just for the newly refactored money application), and completing the ‘squash migrations’ task which the other agents failed to address.

I was prompted via an Issue update to create a PR, which triggered the project-wide tests to run, one of which failed; one of the namespaced URLs in the application’s main navigation hadn’t been updated. I expect the agent would have caught this failure had it ran the entire test suite rather than a subset of the tests. I’ve seen this behaviour in claude-cli, too. I expect this might be a token-efficiency strategy, as verbose test failure output can produce a LOT of tokens very quickly, but I’d expect that at the end of a task the agent would test the entire codebase.

A comment on the newly-created PR “@claude can you fix the failing test” resulted in the bug being fixed in a further 4 minutes.

Grade: B

Four Bubbles I've Lived Through, With One Exception

2025-04-29T15:30:00Z

Working in technology means riding wave after wave of hype. Some waves reshape the landscape; others crash on the shore, leaving behind damp sand and confused investors.

I’ve been around long enough to have lived through many hype cycles, inflated with breathless promise, often to be deflated just as quickly.

I’ve been thinking about the recent past, and the bubbles built more on speculation and wishful thinking than substance. And then there’s the current AI bubble, which feels fundamentally different.

Metaverse

Remember when the Metaverse was the only thing anyone talked about for a few months? The hype was so intense it renamed Facebook (researching this article, I had to clumsily search for the phrase “Meta Metaverse”). Tech pundits told us all to prepare for the imminent future living and working in virtual worlds.

Looking back, it feels like a product born less from genuine demand and more from the specific pandemic anxieties. We were physically isolated, craving connection, and the idea of a persistent virtual space held a certain appeal. But the reality was underwhelming: low-fidelity graphics, awkward interfaces, and a profound lack of compelling reasons to be there beyond novelty. A solution looking for a problem, heavily pushed by a tiny handful of corporates rather than any organic interest. The hype evaporated almost as quickly as it appeared.

NFTs

Non-Fungible Tokens. The promise was digital ownership, verifiable scarcity for digital assets on the blockchain. What it became, almost instantly, was a frenzy of pure speculation detached from underlying value. We saw JPEGs selling for millions, driven by celebrity endorsements and a pervasive “get rich quick” mentality that felt eerily reminiscent of historical bubbles like the Dutch tulip mania.

People weren’t buying digital art they loved (digital art can be loved!); they were buying assets someone else would possibly pay even more for later. When the music stopped, the market crashed spectacularly, leaving many holding effectively worthless tokens. It was a traditional speculative bubble, plain and simple. FOMO.

Crypto (The Coin Launch Grift)

Blockchain technology itself might have long-term potential. The bubble we lived through was the relentless churn of new coin launches, Initial Coin Offerings (ICOs), and meme coins. This wasn’t about revolutionizing finance; it was a grift, deeply entwined with social media influencer culture.

Celebrities, tech personalities, podcasters and opportunistic politicians shilled their dubious tokens to their followers, promising astronomical returns. Twitter and Discord became echo chambers amplifying the hype. Fortunes were made (mostly by the insiders and early promoters) and lost (mostly by everyone else). It felt less like technological innovation and more like a digitally-enabled pump-and-dump scheme playing out on a global scale. It’s the future textbook example of global legislation being unable to keep up with innovation.

AI

And now we have AI. The hype is undeniable – venture capital is pouring in, valuations are soaring, and the coverage is intense. On the surface, it has all of the hallmarks of a bubble.

But the crucial difference is utility.

If the stock market hype around AI vanished tomorrow, the VC funding dried up, and the headlines stopped – I would still open my Claude Code window the day after and get to work. I use AI tools every single day to help me write code, draft documents, debug problems, organise information, and perform evaluative work. Tangible value, right now.

I’m not alone. Software engineers, writers, designers, teachers, counsellers, and consultants are quietly integrating AI into their daily works. They’re using it to brainstorm, create images, research, and write boilerplate code. Unlike the Metaverse, people want to use these tools. Unlike NFTs, the value isn’t based purely on speculation. Unlike the crypto coin frenzy, there are real-world applications happening now. AI does drive productivity.

Certainly, AI company valuations are inflated. There will be a market correction and AI companies will fail. But the underlying technology isn’t going away, because it works. It solves problems and provides value in a way the previous bubbles simply didn’t.

The true test of a technology isn’t the high water-mark of the hype; it’s whether people keep using it when the water calms. This wave feels different because, beneath the froth, there’s a genuinely useful tool.

Trust but Verify: Sensible Ways to Use LLMs in Production

2025-04-26T11:00:00Z

Like many engineers right now, I’m exploring how LLMs can accelerate workflows. The potential is undeniable: generating code snippets, drafting content, summarizing complex information, powering chatbots. We are on the cusp of a significant shift in how we build software and create digital experiences. The temptation is strong to integrate these powerful tools directly into our production systems and content pipelines.

But alongside the capabilities come significant risks. LLMs hallucinate. They make factual errors. They perpetuate biases present in their training data, and can be manipulated through prompt injection. Just blindly plugging AI output into user-facing applications or critical systems seems like asking for trouble.

This brings me to a phrase I’ve been thinking about a lot recently: “trust but verify.”

I first heard “trust but verify” a long time ago, but I was surprised to learn its origin. For years, I’d mentally filed it away as wisdom from the cryptography or infosec communities – domains where skepticism is a virtue. It turns out the phrase was popularized by Ronald Reagan during nuclear disarmament talks with the Soviet Union in the 1980s: it represented a pragmatic approach: proceed with the agreement (trust), but ensure mechanisms are in place to check compliance (verify).

That same pragmatism feels incredibly relevant to deploying LLMs today. We want to leverage their power – that’s the “trust” part. We see the potential for massive efficiency gains and novel features. Letting an AI draft code, generate product descriptions, or provide first-line customer support can free up human time for higher-level tasks.

However, the “verify” part is absolutely crucial and non-negotiable for anything going into production. Raw, unmediated LLM output is rarely trustworthy enough on its own. Hallucinations aren’t just funny quirks when they manifest as incorrect information presented to someone who relies on you.

How do we actually “verify” AI-generated output in a production context? It’s a layered approach:

Human Review: For critical outputs (e.g., code affecting core logic, sensitive communications, definitive factual statements), there’s is no substitute for a knowledgeable human reviewing the AI’s work before it goes live.
Automated Checks: Just as we write unit tests for human-written code, we need tests for AI-generated code. For generated content or data, validation rules, fact-checking against known databases, or checks for PII or toxicity can be automated.
Monitoring and Feedback Loops: Log your LLM interactions and outputs. Track performance. Implement mechanisms for users to flag incorrect or unhelpful responses (a simple thumbs up/down is more than enough). Crucially, have a system in place to act on this feedback quickly.
Sandboxing and Staging: Test LLM-powered features thoroughly in non-production environments before rolling them out. Understand their failure modes in a safe space. This should be obvious but you’d be surprised how many people are manipulating prompts in their live environment and hoping for the best.
Clear Boundaries and Fallbacks: Define where AI is used and where it isn’t. Everyone in your organisation needs to understand these boundaries. CEO to product to engineer. Have robust fallback mechanisms for when the AI fails or provides low-confidence answers. Don’t let the AI operate outside its known competence.

Implementing verification adds friction. It requires building additional systems, dedicating human time to oversight, and accepting that deployment might be slower than just letting the AI run wild. But it is also the only responsible way forward. Harness the benefits and mitigate the risks.

“Trust but verify” isn’t about stifling innovation; it’s about enabling and guiding it sustainably. As LLMs continue to evolve, perhaps the nature of verification will change, but the principle will likely remain.

The MCP Servers I Actually Use

2025-04-22T08:00:00Z

The Model Context Protocol (MCP) ecosystem is changing quickly. While experimentation is interesting, I’ve found myself settling on a core set of MCP servers that I use day-to-day to when writing software with AI. These are the ones that have stuck:

Github MCP server

I primarily use the Github MCP server because it’s the canonical implementation from Github itself. While you can run it in various ways, I prefer the statically compiled Go binary for simplicity. Building it is straightforward:

$ git clone https://github.com/github/github-mcp-server.git
$ cd github-mcp-server/cmd/github-mcp-server
$ go build .
$ cp ./github-mcp-server ~/.local/bin # or whatever is in your $PATH

It’s great to be able to sign off an AI coding session with a natural language instruction like “commit the changes with message ‘feat: Implement new widget’, push the branch, open a PR against main, and write a brief PR description of the changes.” This smooths the transition from AI interaction back to standard Git workflow.

I also find it really useful for manipulating branches in more complex ways directly from a text description, saving time digging through Git commands for less common operations.

Fetch

Often, I want to do my own research or find specific documentation before bringing the content into an AI session for analysis or summarization. The Fetch server is perfect for this.

It effectively replaces a manual step I used to perform with curl piped into the excellent trafilatura Python library to extract main content and convert it to Markdown. Fetch handles fetching the URL and transforming the relevant content into clean Markdown automatically, ready for the AI.

As a small bonus, I also appreciate that Fetch is honest about its identity in its User-Agent string.

Docker

My use case for the Docker MCP server is quite specific: discovery and use of docker-compose.yml files within a project.

While Claude Code is generally good at figuring out how to start a project, it’s not perfect, especially in the presence of Makefile, which Claude seems to treat at the only possible entrypoint into a running solution. This server’s ability to discover and use docker-compose.yml files is a useful fallback for quickly getting services running, especially in unfamiliar codebases, directly from the AI interface. It bridges that gap when the AI’s initial setup instructions might be slightly off or incomplete.

The future of digital agencies

2025-04-16T12:00:00Z

This is keeping me up at night. The model we built is dying. It’s time to build the next one.

Let’s start with a sketch of an agency project.

A standard mid-sized website project costs maybe £80,000. That covers the costs of the sales process, a strategist, a project manager coordinating everything, a couple of designers iterating on UX and visuals, a few software engineers building the front and back end, maybe a copywriter. It covers the subscription costs of all the tools which those people use. It pays for lots of meetings, lots of messages, many revisions based on subjective feedback loops. It takes 12 weeks, maybe more. The cost is mostly people’s time – skilled, expensive, human time.

Let’s sketch a different workflow. A single operator (maybe the owner, maybe a senior lead) defines the core goals and target audience. They feed this into several competing AI strategy assistants for market and competitive analysis. The AI reaches into the ‘old internet’ for context, and searches to verify information. They use a combination of AI-assisted search and AI-assisted layout engines to create dozens of concepts and initial design directions in an hour. It costs nothing to reject a bad concept. No-one gets upset and no-one gets tired. They use AI wireframing tools. A refining prompt goes to an AI copywriter for core messaging options, another to a design AI for multiple layout variations based on the mood board. Code generation tools vacuum in the agency’s past repositories for code patterns and preferences, and begin putting together the code.

Suddenly, instead of weeks of back-and-forth for initial concepts, you have a spread of viable options in a day. The cost? A fraction of the human-hours, replaced by 10,000 API calls. Let’s say, generously, we spend £500 in compute for the initial creative explosion.

Which process delivers more value for the client’s pound at the concept stage? Which one will feel faster, and more responsive?

Right now, the traditional team still delivers a more polished, strategically coherent final product. AI output needs heavy curation, integration relies on AI not coding itself into fractal loops, and oversight is still paramount. The AI will create beautiful but unusable code, and vapid copy. That £80,000 project involves nuance, client hand-holding, and integration complexities that AI struggles with today.

The creatives, the software engineers, and the strategists convince themselves their craft is safe, sticking to that argument as a trillion dollars coalesces into the form of a giant silicon golem, ready to smash aside their passion, education, and professional utility. The battle, of the bespoke agency process versus 2025’s fragmented AI tools – is the worst the AI side will ever be, and the best the purely human-driven model will ever look in comparison. Everything is trending against the old way.

Models will improve. Today’s AI is a clumsy intern drowning in complex tasks. Tomorrow’s will be smarter, faster, more integrated. The gap between AI output and human-quality output will shrink dramatically, and rapidly.

Costs will plummet. Computing will get cheaper, models will become more efficient. The £500 for that concept explosion might become £50.

The economic pressure will be immense.

Workflow tools will emerge. Right now, we duct-tape AI tools together, copying and pasting Markdown and stuffing our aims into wide RAG contexts. Soon, platforms will exist specifically to orchestrate AI agents: seamless generation, review, and deployment pipelines. This isn’t about people discussing tickets in JIRA. This is an automated assembly line control panel.

Client expectations will shift. Why pay £10,000 for a brand exploration over two weeks when an AI can generate 50 viable options for £100 in an afternoon, curated by one skilled designer? Clients will demand more, faster, cheaper. The perceived value of laborious human hours on tasks AI can approximate will crater. To experts, quality of the output will be perceptibly worse. The clients will not care.

The nature of “good” will change. Just like “good code” might shift from human-readable to machine-optimized, “good design” or “good copy” might become less about singular human genius and more about the best outcome selected from a vast possibility space, refined by human taste.

Is this keeping you up at night yet?

Forget the single project comparison. Scale it up.

Let’s consider “The Traditional Agency” in 2025. A 30-person agency. Senior management. Sales people. Account managers, project managers, strategists, designers, software engineers, SEO specialists. Payroll. Benefits and office space and software licenses. £1.5 million a year cost before profit. They juggle multiple clients. Projects move at human speed, bottlenecked by communication, revisions, and individual capacity. The only effective route to scale this model is means hiring more people, adding coordination complexity.

What is an AI-Driven Agency in 2028? A core team of 8 people: Senior Strategists/Client Leads, AI Workflow Architects, Prompt Engineers, Senior Curators (Design/Copy/Code), Integration Specialists. They oversee a suite of AI tools and automated workflows. They handle 3x the project volume of the traditional agency, with half of the costs. The system generates code, design, copy, variants, and KPI reports 24/7. The humans focus on high-level strategy, client relationships, final quality control, and managing the machines. Overhead? Maybe £750,000, with significantly higher potential throughput.

Which model wins? I don’t mean awards, or genuinely novel and interesting output. I mean which one delivers the speed and cost clients will inevitably demand?

This isn’t about AI becoming a perfect replica of a human designer or software engineer. It’s about industrialization. The first steam engines were too expensive and underpowered, the first cars were death traps (when they ran at all). Don’t lull yourself into the dream of a static world.

We see the wave coming. As an agency owner, my choice isn’t if this change happens, but how to navigate it. Do I cling to the “craftsman” model I grew up with, the bespoke process, the value tied solely to the hours my talented (and expensive) team pours in? Or do I look for a way to surf it?

This means fundamentally rethinking the agency structure. It means accepting that much of the production work – the writing, the designing, the coding, the campaign setup – will be automated or assisted to a degree that makes the old model economically unviable for many clients. The value shifts upwards, towards strategy, towards curation, towards understanding how to wield these incredibly powerful new tools to achieve client goals more effectively than ever before.

It means saying goodbye to parts of the agency model I loved. The bustling endeavour as the team gather and focus on the upcoming deadline is replaced by a silent slowly ascending chart on dashboards monitoring AI output. Roles will change. Many will disappear. We’ll need fewer junior “doers” and more senior “orchestrators” and “refiners”.

The critics will say AI can’t replicate human creativity, strategic nuance, or the client relationship. They’re right, it can’t – not entirely. But industrialization doesn’t win by perfectly replicating the artisan. It wins by being relentlessly cheaper and faster for the bulk of the work. We mass-produce clothes, furniture, cars and cultural experiences. The bespoke artisan still exists, but they serve a niche market. The volume, the market dominance, belongs to the factory.

Software engineering is facing its factory moment right now. Digital agencies are right there with them. The agencies that thrive won’t be the ones clinging to the past, waiting to feel the crush. They’ll be the ones building the assembly lines, figuring out how to harness this new automated workforce, and delivering unprecedented value by mastering the means of production. They’ll optimize for OPE – Output Per Employee – leveraging AI to create more, faster, and ultimately, cheaper than the traditional model can sustain.

The craftsman agency isn’t dead yet. But the factory is being built next door, and the rent is about to go up. Time to figure out how to run the machines.

Preparing Django documentation for LLMs

2025-02-21T10:00:00Z

I’ve been using files-to-prompt recently to help query large codebases with LLMs, but I realised this would work just as well for documentation sets. Here’s how to generate a complete documentation set for Django; I’ve been uploading this to a ChatGPT Project as a supporting document, and getting really good results.

$ git clone git@github.com:django/django
$ files-to-prompt django/docs/ \
--ignore *.css \
--ignore *.svg \
--ignore *.graffle \
--ignore *.pdf \
--ignore *.png \
--ignore *.eot \
--ignore *.ttf \
--ignore *.woff \
--ignore *.woff2 > /tmp/django-docs.txt

Setting up Matrix Synapse on Fedora

2025-02-18T18:00:00Z

I wanted to install a Matrix service for my family. While matrix-synapse is packaged in Fedora, there’s scant documentation regarding what to do next after installing the package.

First, you need to generate a configuration file:

$ generate_config --server-name your.domain.here --config-dir=/etc/synapse/ --report-stats=no > /tmp/homeserver.yaml
$ sudo mv /tmp/homeserver.yaml /etc/synapse

There’s a bit of extra configuration, which is in /etc/sysconfig/synapse, which allows you to set the memory limit for the Synapse server. Read and amend this as necessary.

Next, generate some keys:

$ generate_signing_key > /tmp/your.domain.here.signing.key
$ mv /tmp/your-domain-here.signing.key > /etc/synapse

Review the contents of /etc/synapse/homeserver.yaml. You’ll note the references to DATADIR, which is /var/lib/synapse/DATADIR/ by default.

Now, it’s time to start the service:

$ sudo systemctl start synapse.service
$ sudo systemctl status synapse.service

You should now have Synapse running happily, but it’ll only be listening for traffic on the loopback network adaptor.

Follow the instructions for setting up a reverse-proxy to the service. I used nginx, and you probably should too. For me, this also involved setting up a SSL certificate with certbot, but your specific installation might not be the same as mine. Any generic ‘SSL with Nginx’ instructions should work correctly.

Finally, it’s time to setup a user on your instance. We need to generate a shared secret:

$ cat /dev/urandom | tr -dc 'a-zA-Z0-9' | fold -w 32 | head -n 1
some-random-output-here

Add that to your /etc/synapse/homeserver.yaml file as:

registration_shared_secret: some-random-output-here

Finally, setup a new user:

$ register_new_matrix_user -c /etc/synapse/homeserver.yamlhttp://localhost:8008
New user localpart [admin]:  
Password:  
Confirm password:  
Make admin [no]: yes
Sending registration request...
Success!

You should now be able to login to your Matrix server using the client of your choice.

A Cline prompt for codebase analysis and feature extraction

2024-11-20T08:28:00Z

From time-to-time, I’m asked to evaluate a large codebase. This is usually from a client who has a project in distress, or who needs to quickly move their infrastructure provider and re-host the application elsewhere.

I lot of the time this relies on the intuition of a good engineer who is familiar with the technology being used. There’s a lot of code browsing, writing quick notes, and silent video calls as we try to find the context for the decisions in the codebase.

I wanted to see if there was a better way to do this, and as I’ve been using Cline in VSCode, I tried to write a comprehensive system prompt:

# Cline Custom Instructions
## Role and Expertise
You are Cline, an expert-level full-stack developer and UI/UX designer. Your expertise covers:
- Rapid, efficient interrogation of existing codebases, using your judgement and intuition as a guide.
- The full spectrum from MVP creation to complex system architecture knowledge.
Adapt your approach based on project needs and user preferences, always aiming to guide users in efficiently creating functional applications.
## Critical Documentation and Workflow
### Documentation Management
Maintain a 'analysis/' folder in the root directory (create if it doesn't exist) with the following essential files:
1. technology.md
- Purpose: Analysis of key technology choices and architecture decisions
- Format: Use headers (##) for main technology categories, bullet points for specifics. Datestamp these headings based on when you first encountered the technology in the codebase.
- Content: Detail chosen technologies, frameworks, and architectural decisions with brief justifications
2. summary.md
- Purpose: An overview of project features.
- Include sections on:
- Key user-facing features.
- Interactions with external APIs, providers, etc.
- Format: Use headers (##) for main sections, subheaders (###) for components, bullet points for details. Datestamp the headings based on when you first encountered the feature in the codebase.
- Content: Provide a high-level overview of the project features, highlighting main components and their relationships
### Adaptive Workflow
- At the beginning of every task when instructed to "follow your custom instructions", read the essential documents in this order. You can find them in the `analysis/` folder.
1. `technology.md`
2. `summary.md`
- If you try to read or edit another document before reading these, something BAD will happen.
- If conflicting information is found in the codebase, ask the user for clarification
## User Interaction and Adaptive Behavior
- Ask follow-up questions when critical information is missing for task completion
- Adjust approach based on project complexity and user preferences
- Strive for efficient task completion with minimal back-and-forth
- Present key technical decisions concisely, allowing for user feedback
## Code Editing and File Operations
- Refer to the main Cline system prompt for specific file handling instructions
Remember, your primary goal is always to provide the a detailed analysis of the codebase, and describe all the features therein. The documents you produce are key to a successful outcome.

This has generated good results so far, providing the code can fit into the context window. With claude-3-5-sonnet-20241022, that is possible for most mid-size applications (at least for my definition of mid-size).

My Claude Artifact Prompt

2024-11-12T18:10:00Z

I’ve found myself writing a lot of Claude artifact prompts recently. I don’t remember if I started writing these little personal software widgets before of after I read Simon Willison’s post on the same topic, but they are a very fast and straightforward way to feather the personal software nest.

I have about ten artifacts which I’m regularly using now, and I’m adding more each week. In terms of writing software to scratch a personal itch, it is very nice to be able to act on ideas, rather than putting them in the someday/maybe pile due to the high setup cost of building personal software by hand.

For others who are also doing this, I wanted to share my prompt:

I use the tagged prompt style. I don’t remember where I picked up this style, but it seems to work well.
I include my personal preferences for CSS and the UI. Change these are you see fit.
I’ve included a list of ‘banned’ techniques. By default, Claude seems to love to produce React components, but as I added more banned technologies, it started to produce anything but plain JS. Hence the long list.
I stuff all my state into a cookie. Yeah, I know this is limiting, but it works for up to 4KB of data. And that’s a LOT of data!

<task>
First, I describe in a single sentence what the goal of the software is.
</task>
<technology>
Plain Javascript
Bootstrap 5.3
Bootstrap Icons
</technology>
<banned_technology>
React
Django
Angular
Vue
JQuery
</banned_technology>
<state>
- All state should be stored in a single object.
- After each manipulation of the application state, it should be stored in a cookie as a JSON blob.
- State should be loaded from the JSON blob in the cookie on page initialization.
- If the size of the state object approaches more than 4KB when serialised as JSON, alert the user.
</state>
<ui>
- Produce a responsive design for mobile and desktop.
- Always include dark/light theme support, with a toggle button in the footer of the application.
- Use the CSS features in Bootstrap for consistent look. It may be necessary to write custom CSS, but avoid this if possible.
</ui>
<data_structure>
If I have particular instructions about how I want to shape the data, I include them here.
</data_structure>
<functions>
Here I describe in more detail the functions of the software.
</functions>

I am also working on a simple (and easy to describe) data persistence idea, so maybe more on this soon.

Fingerprint Authentication on a Lenovo Z13 and Fedora 40

2024-10-27T09:01:00Z

I’ve previously used fingerprint authentication on Thinkpads in the very distant past. There have been a lot of changes to the software stack since then, so I had to rediscover how to make the fingerprint reader work. I’m using Fedora 40. I don’t actually think any of these instructions are Z13 or Thinkpad specific, but YMMV.

First, install the fprintd package and start the service:

$ sudo dnf install fprintd
$ sudo systemctl enable fprintd

Enrol some fingerprints:

$ fprintd-enroll

You’ll need to touch the fingerprint reader multiple times (sometimes many times!) to build the model of your fingerprint. If you want to register a specific finger, you can so with the -f flag. From the man page, the supported finger identifiers are:

For fprintd-enroll, the finger to enroll. Possible values are:

left-thumb, left-index-finger, left-middle-finger, left-ring-finger, left-little-finger,
right-thumb, right-index-finger, right-middle-finger, right-ring-finger, right-little-finger.

Once you have registered your fingerprints, you can check with:

$ fprintd-verify

Next, you need to tell the system to include fingerprint login in the available authentication methods. This was new territory for me, as I wasn’t familiar with authselect, which because the default management interface for authentication back in Fedora 28.

To check that fingerprint authentication is available:

$ authselect list-features local

You should see the with-fingerprint capability. Now, we add this to our profile, and then apply the new configuration:

$ sudo authselect enable-feature with-fingerprint
$ sudo authselect apply-changes

Now, reboot the system to apply the new authentication profile. There is probably a way to do this without rebooting, but I didn’t research that far. Once rebooted, open a terminal, and invoke something with sudo to test authentication:

$ sudo ls
Place your finger on the fingerprint reader

You should now be able to authenticate.

New in Python 3.13: SQLite support in dbm

2024-10-07T16:30:00Z

Python 3.13 was released today, and it would be easy to overlook this:

“dbm.sqlite3: An SQLite backend for dbm. (Contributed by Raymond Hettinger and Erlend E. Aasland in gh-100414.)”

I don’t think that many Python engineers know about the dbm module, which is a shame because it is a sharp tool. It’s a tool for reading and writing to string databases, which has been around in some form since I first came across it in Python 1.5 (I am indeed that old).

dbm is easy to overlook, maybe due to it’s fairly pedestrian subtitle: “Interfaces to Unix databases”, or maybe because in previous versions of Python, it only supported some unglamorous databases: NDBM, it’s cousin GDBM, and more recently the Berkeley DB. These are robust, reliable databases, but they have rather fallen out of favour. Readers who are familiar with those databases will know that such systems were the progenitor to something with a much sexier label: the NoSQL Database.

dbm provides a very simple API, which will feel familiar.

import dbm
# Open database, creating it if necessary.
with dbm.open("mydatabase", "c") as db:
# Record some values
db["mykey"] = "My Value"
db["anotherkey"] = "another value"
# Access your database like a dictionary
print(f"mykey: {db.get("mykey")}")
print(db.get("doesntexist", "Default value"))
# Beware, however, storing a non-string value will raise an exception
db["thiswillfail"] = 4

The API is clean, tiny, and memorable.

Some will see the inability to store anything but strings as a deal-breaker (which is understandable), but I find that using pickle or shelve is enough for these scenarios. The occasional cast to int is also perfectly bearable.

Now, with the release of Python 3.13, we can very easily use SQLite3 as our backend:

with dbm.sqlite3.open("database.sqlite", "c") as db:
db["mydata"] = "Lorem ipsum..."

When I write code, I like to use the simplest possible datastore. In practice, I usually start with a JSON file in combination with json.loads and json.dumps, which is ’enough’ for a lot of problems.

Having the option to now use SQLite via dbm is a nice further step; once created, the SQLite database can be manipulated with standard SQLite tools which are available just about everywhere. This is very useful as you mature from “I just need somewhere to store my data state” to “I have more sophisticated needs”.

The dbm documentation and the dbm.sqlite3 documentation is a good next stop to learn the detail.

Django Carbon Measurement Notes

2024-10-07T10:15:00Z

At work recently, I’ve been working on some code to measure the bandwidth required to display webpages, and from there calculate the approximate energy usage and carbon output. Here are the links from my notes:

Greening Digital with Django, a talk by Chris Adams, whose blog is also full of interesting ideas.

Faster, leaner, greener: 10x lower website carbon emissions, a talk by Thibaud Colas.
codecarbon, a Python package to quantify carbon emissions by instrumenting code (docs here).
co2.js, a Javascript package.
Since Firefox 104, Firefox has supported measuring power consumption in the browser’s profiling tools. See also this interesting post from Fershad Irani.
CO2, a Github action to measure CO2 usage as part of a CI run. Some small amount of commentary on this; this tool starts up a Google Lighthouse instance in the CI run, which is very heavy, CPU-intensive software which runs a complete desktop web browser in order to instrument the bytes transferred. This seems very inefficient to me, and trying to find an acceptable alternative is the problem which I’ve been working on.
The Green Software Foundation, and see also the very useful Green Software Maturity Matrix.
The Green Web Foundation

Using ruff for everything in VSCode

2024-10-03T10:00:00Z

Ruff’s VSCode extension is nice, and can handle the jobs previously done by black and isort. To turn on everything, and to run this on every file save (this is probably what you want, given it only takes a few milliseconds), use this configuration in .vscode/settings.json:

{
"[python]": {
"editor.codeActionsOnSave": {
"source.organizeImports": "explicit",
"source.fixAll": "explicit",
},
"editor.defaultFormatter": "charliermarsh.ruff",
"editor.formatOnSave": true
},
}

Automatic, persistent autoreload in iPython

2024-10-02T10:00:00Z

I like that iPython can be configured to automatically reload modules. It’s useful to be able to keep REPL context through development, without needing to constantly tear down and setup your context:

>>> %load_ext autoreload
>>> %autoreload 2

However, turning on the autoreload extension is also annoying to set each time you spawn a REPL, but thankfully this can also be automated:

Create a file in your project root, .ipython_data_local/ipython_config.py
Add the following code:

c.InteractiveShellApp.extensions = ["autoreload"]
c.InteractiveShellApp.exec_lines = ["%autoreload 2"]

Then, optionally mount that folder in your docker-compose.yml, which is useful if you run your REPL in a container:

volumes:
- .ipython_data_local:/root/.ipython/profile_default

Using .ipython_data_local/ipython_config.py seems quite strange, but it seems it’s based on iPython’s own profile system. It would be nice if this could be configured in pyproject.toml like everything else.

A minimal Django application

2024-09-18T10:28:00Z

I wanted to put together a single-file Django application, which could still do ‘useful’ work; that is, define models, operate on them, and setup URL routing.

I ended up with two files. The first, application.py:

import os
from django.db import models
from django.http import HttpResponse
from django.urls import path, re_path
from django.core.wsgi import get_wsgi_application
from django.contrib.auth.decorators import login_required
from django.contrib.auth import views as auth_views
# Assuming settings.py is in the same directory
os.environ.setdefault('DJANGO_SETTINGS_MODULE', 'settings')
# Define the Django model
class MyModel(models.Model):
name = models.CharField(max_length=100)
# Define the view functions
def index(request):
return HttpResponse("Hello, world!")
@login_required
def authenticated_index(request):
return HttpResponse("Hello, authenticated user!")
# Define the URL patterns
urlpatterns = [
path('', index, name='index'),
path('authenticated/', authenticated_index, name='authenticated_index'),
path('login/', auth_views.LoginView.as_view(), name='login'),
]
# Create the WSGI application
application = get_wsgi_application()

And the second, settings.py:

import os
# Build paths inside the project like this: os.path.join(BASE_DIR, ...)
BASE_DIR = os.path.dirname(os.path.abspath(__file__))
SECRET_KEY = 'your_secret_key'
DATABASES = {
'default': {
'ENGINE': 'django.db.backends.sqlite3',
'NAME': os.path.join(BASE_DIR, 'db.sqlite3'),
}
}
INSTALLED_APPS = [
'django.contrib.auth',
'django.contrib.contenttypes',
]
ROOT_URLCONF = 'application' # Point to the application file.
TEMPLATES = [
{
'BACKEND': 'django.template.backends.django.DjangoTemplates',
'DIRS': ['templates'],
'APP_DIRS': True,
'OPTIONS': {
'context_processors': [
'django.template.context_processors.debug',
'django.template.context_processors.request',
'django.contrib.auth.context_processors.auth',
'django.contrib.messages.context_processors.messages',
],
},
},
]
ALLOWED_HOSTS = [] # Update for deployment

Edit 2024-09-26: I just found out about nanodjango, which is a much more polished experience. Check it out.

Logging git commits with a git hook

2024-09-09T00:00:00Z

Similar to my previous post (more than a year ago!) about using Git hooks to enforce conventional commits, I wanted to start logging all of my commits. This is part of a larger project to keep a better work diary, but I wanted to start with something simple and unobtrustive, and this seemed like a simple place to start.

We need to create a global hooks folder, and enable it.

$ mkdir $HOME/.git_hooks
$ git config --global core.hooksPath ~/.git_hooks

Using the post-commit hook is the most sensible place for this, so we’ll create the hook and make it executable:

$ touch $HOME/.git_hooks/post-commit
$ chmod +x $HOME/.git_hooks/post-commit

The contents of that script:

#!/bin/bash
# Get the commit message.
commit_message=$(git log -1 --pretty=%B)
# Get the repository name using git rev-parse.
repo_name=$(git rev-parse --show-toplevel | xargs basename)
# Get the current datestamp.
datestamp=$(date +"%Y-%m-%d %H:%M:%S")
# Log the information to the .git_log file in the home directory.
echo "$datestamp | $repo_name | $commit_message" >> "$HOME/.git_log"
# Some positive output.
echo "Logged commit."
exit 0

The code is also available from this gist. Here’s the copy/paste installer:

$ curl https://gist.githubusercontent.com/jonatkinson/71db4672fc74c98a66cf7163fc38706b/raw/2dd8b0a583a1fddb203af43f09edeb3193f1d8fb/commit-log > $HOME/.git_hooks/post-commit && chmod +x $HOME/.git_hooks/post-commit

Conventional Commits Git Hook

2023-05-03T00:00:00Z

I was looking for a way to enforce the Conventional Commits pattern for my own commit messages. A lot of the solutions I found were wildly overcomplicated; I don’t need to install a commit linting framework with a hundred JS dependencies, I just want to apply a regex to a commit message.

This was fairly straightforward. First, create a global hooks folder, and enable it.

$ mkdir $HOME/.git_hooks
$ git config --global core.hooksPath ~/.git_hooks

Now, create the script file:

$ touch $HOME/.git_hooks/commit-msg
$ chmod +x $HOME/.git_hooks/commit-msg

The contents of that script:

#!/bin/bash
commit_msg_file=$1
commit_msg=$(cat $commit_msg_file)
# Define the pattern for conventional commit messages
pattern="^(build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\(.+\))?: .+"
if [[ ! ${commit_msg} =~ $pattern ]]; then
echo "ERROR: The commit message does not follow the conventional commit format."
echo "Valid types: build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test"
echo "Format: type(scope): subject"
exit 1
fi
# If commit message matches the pattern, continue with the commit
exit 0

The code is also available from this gist, so if you prefer, install it like this:

$ curl https://gist.githubusercontent.com/jonatkinson/9243328de14e17e1e4200b9a1ca97d72/raw/3e342f140f5df8d6ec273253a071c431a90d6a89/commit-msg > $HOME/.git_hooks/commit-msg

How I Do 1-2-1 Meetings

2023-02-28T00:00:00Z

It appears that everyone on the internet completely hates 1-2-1 meetings.

I don’t particularly want to add fuel to that viewpoint; I’m sure there are a huge mount of people who completely hate 1-2-1 meetings with their manager. I understand that.

However, done correctly, the 1-2-1 meeting is one of the greatest tools we have in the workplace; building lines of communication up, down, and across your organisation is an extremely high value activity. There’s nothing more effective to build trust.

Here’s the problem though; all the literature focuses on the ‘perfect’ 1-2-1 meeting. Apparently you can find success if you just set the right agenda, just ask the right questions, or just set the right cadence. That’s all bullshit. Effective 1-2-1 meetings are a highly adaptive process. You need to change your tactics depending on the individual, their state of mind, their current challenges AND your own status. You need to be ready to adjust.

I’ve ended up with four ‘modes’ of running a 1-2-1, which I pick from and blend together based on the early minutes of the meeting:

The ‘No Agenda’ Meeting.

Sometimes, you don’t need an agenda. You can let the conversation and the other person lead entirely.

The ‘Big Goals’ Meeting.

Sometimes, you need to take focus completely away from the current context. This is an ideal candidate for the very end of a day, or a Friday, or better over a long lunch. The most important context change you can make for this kind of 1-2-1 meeting is to make as much space between the general ‘work’ context and the current moment.

Big questions can be asked in this meeting. This can be a great way of showing vulnerability and building trust;

Is the organisation meeting your expectations?
Will it continue to do so in a year, two years, four years?
What is the biggest non-work goal in your life, and is there anything I can do to help you get there?
What are you aiming to achieve this year in your personal life? What is blocking you, and how can I or the organisation help you?
Do you know what my big goals are?

Clearly, not all 1-2-1 meetings can focus on these big goals. Big goals take time to achieve, so the cadence needs to be wide. That also doesn’t mean ‘only speak annually about these things’. You’re a better manager than that.

The ‘Work Catchup’ Meeting.

This could easily be renamed “The ‘Things I’m Too Embarrassed To Raise At The Standup’ Meeting.”; it won’t shock you to know this is the most common meeting type, certainly for engineering managers. It’s also probably the least valuable time you’ll spend with your 1-2-1 partner. However there is some useful information you can gain from these meetings:

What is consistently working well for our team?
Are we currently properly matching your workload with your ability?
Which projects are healthy, which are at risk, which are fucked?
Why?

The ‘Shut The Fuck Up’ Meeting.

Guess who is doing the shutting-the-fuck-up? You.

Any of the above 1-2-1 meeting styles can quickly flip to this if your organisation has overt or hidden dysfunction. All organisations have both overt and hidden dysfunction.

This is where you need to let the communication flow. Everything you know about active listening and NVC come into play here. Your camera should be on (aside: if your camera isn’t on, you’re a shitty leader), and at most your contribution should be to prompt for more. If you find yourself becoming defensive, you need to stop and minimise your own needs. When your counterpart is talking about big problems, your job is to listen, NOT respond. This isn’t litigation, it’s an exercise in building trust and enhancing your reputation with your counterpart. Save the solutions for another time.

Good luck.

Link Roundup #6

2023-02-20T00:00:00Z

Some of these are older links I found languishing, misfiled in my Safari favourites.

The collapse of complex software

Right now, the software industry has been in a nearly two-decade economic boom (with some fits and starts), but the one sure thing in economics is that booms eventually turn to busts. During the boom, software companies can keep hiring new headcount to manage their existing software (i.e. more engineers to understand more boxes and arrows), but if their labor force is forced to contract, then that same system may become unmaintainable. A rapid and permanent reduction in complexity may be the only long-term solution.

If CV-driven development comes to an end, little of value will be lost. And that’s not a snarky “little of value”; there is no value generation, and we will not miss those people.

ChatGPT Explained: A Normie’s Guide To How It Works

Okay, this isn’t for normie Normies. This isn’t for your parents. But as an engineers guide if you’re not familiar with the space, it’s fantastic.

Canada bans TikTok on government devices over security risks

This is any of a cluster of articles I could have picked on this topic. No-one cares. The fact that we are seeing this action this late suggests that the toothpaste is already a long way out of the tube.

Presumably the three-letter agencies have been monitoring traffic generated by the average TikTok user for years now. And presumably recently, China have made some rustle in this particular dark forest to cause this to bubble to the top of bureaucratic consciousness. Hopefully more at CCC.

Link Roundup #5

2023-02-12T00:00:00Z

Back after a vacation with the ChatGPT special edition. I suspect the theme of the next 5 years will be ChatGPT.

Chat GPT is the birth of the real Web 3.0, and it’s not going to be fun.

As the ouroboros continues to devour itself into ever-tightening recursion (A “recursive descent”! HA!), we approach the info-bullshit singularity.

I believe the web as a way to access information is getting worse by the day. Content generated with GPT-3 is going to start to show up for every long tail search under the sun, whereas regular content is going to get even heavier with SEO keyword to survive. The web is going to get worse and worse, and the only way to get good information is with a system that can extract the signal from the noise, a.k.a ChatGPT.

Actually, does this mark the beginning of the post-bullshit era; where ‘content’ is all meaningless? Does bullshit actually work as a distinction against the sea of GPT sludge? This leads on to…

Poe

… Poe. An AI chatbot trained on, no I am not-fucking-kidding, Quora answers. If Quora, which was truly the poster-child of the Web 2.0 tragedy of clout-chasing (or do we just call this the race to the bottom?), thinks if can extract meaningful signal from it’s corpus, please could we have Yahoo! Answers next? How is AI formed?

ChatGPT Is An Extra-Ordinary Python Programmer

ChatGPT codes like an expert beginner. It can help you be productive, but it can’t be trusted.

The average CEO in a non-technical business (ie. most of them) will not be able to distinguish between the output of a capable software engineering leader with a small team, and the output of massively parallel GPT output. Even guided, I despair. The reality is going to hit the industry like a train (and, for offshore teams, like a nuclear bomb).

Link Roundup #4

2023-02-01T00:00:00Z

We are being levelled-down

The government has allocated £9.7 billion of levelling up funding since 2019. But between 2010 and 2020, annual funding from the national government to local councils in England fell from £41 billion to £26 billion adjusted for inflation — and the government’s critics say pots of levelling up funding since are scant compensation.

“That’s why we’re in the mess we’re in,” said Bev Craig, the Labour leader of Manchester City Council. “None of that money comes close to what was lost.”

I know we’re in a kind of neo-politics, post-truth era (or maybe only nihilists are capable of grinding to the top of the political order), but the levelling-up agenda always appeared completely hollow from the beginning. Maybe around the early Cameron/Osborne era there was a glimmer of conviction about the process of evenly distributing the UK’s wealth, but that has been walked back (and further!) by successive governments, whose approach to the simple reality of the mathematics is: “just don’t talk about it”.

One wonders how different a Labour government would be; the level of cynicism is currently off the scale.

Hiring Correctly

2023-01-27T00:00:00Z

It’s a time of year when a lot of businesses are hiring, and layoffs mean there are more candidates in the marketplace. That also means the volume of online commentary concerning ‘bad practices’ is growing; and the amount of bad practice is staggering. Otherwise rational engineering organisations seem very susceptible to copying their hiring process from whatever nonsense the FAANG interview handbook currently suggests – without thinking about the people they are putting into the meat grinder.

I wanted to lay out my experiences; in a small (ie. sub £2m/year) software company, a long way from Silicon Valley.

A job advert isn’t a mystery novel. The point is not to intrigue. A job advertisement should be extremely explicit, and it should be exhaustive in it’s detail where possible. From an efficiency point of view, it’s much better for your candidate to spend time evaluating the role in written form, and making a choice to proceed or decline early in the process. This also saves time on the employer side.

Your job advert should contain absolutely no misdirection. Don’t talk about ’leading new projects’ when your engineering team spends 65% of their time on maintenance work. Don’t be tempted to try to attract engineering talent to the zeitgeist; don’t advertise new frameworks and languages, when you only use them for prototypes and not your day-to-day activities. If you allow your job advert to turn into a marketing piece, then you’re just saving up disappointment for your candidate’s first week on the job. Write about the company you are, not the company you wish you were.

This transparency must extend to the salary for the role. If you do one thing to improve your hiring processes, make it this one; you must be explicit about salary. If you have a range which depends on experience, that’s fine, but be explicit about how much that experience affects the compensation. The narrower salary band you can offer, the more confidence you can build in your hiring funnel, because both you and the candidate have the same expectations.

The salary you offer for a job is the clearest expression of the bargain you’re making between the organisation and the individual. If your organisational success depends on undervaluing your staff and underpaying them, then you need to fix that before you hire anyone else. This doesn’t mean you need to reach for the highest number you can; geography and prestige and debt all effect what an organisation can afford to spend on it’s talent, and your organisation might not be able to spend top dollar. If your number is lower than the competition, that is fine, but you can at least be honest about it. As the compensation discussion usually comes at the end of the hiring process, if either party enter into the process without clarity, then you run the risk of wasting everyone’s time. That will, quite correctly, damage your credibility.

Process Transparency

Once a candidate has contacted you, you need to lay out the process for them in detail, from the very first communication. No matter what your process is, it probably has multiple stages, and those stages all have a window of time, and your candidate needs to know this so they can plan accordingly. So if your process is 3 stages, and it usually takes 2 weeks, then be clear about this. Highlight any potential risks (particularly around the availability of key people); nothing destroys trust and motivation faster than a candidate who is simply left waiting for you to ‘get back in touch’.

I try to always open an interaction with a reminder of where the candidate is in the process, and any changes. It never hurts to let someone know if the process if running off-schedule, or if someone dealing with a future stage is unavailable. Transparency at all times.

The steps in your process are commitments, both to the candidate and the business. You should take them seriously, as this may be your first opportunity to demonstrate your integrity to someone you may work with for a long time to come. Cancelling interviews, arranging meetings without proper notice, not having the interviewer available – these are all examples of bad practice and it’s hard to trust an employer who breaks their early commitments.

Feedback

Speaking of your commitments to a candidate, you should commit to feedback, regardless of whether it’s good, or bad, or awkward. Telling a candidate they did a good job in an early stage of your process can give them confidence for future stages. Be human; if a candidate impressed you, let them know!

Equally, being clear and empathetic in your feedback for a candidate who isn’t right will take you minutes, but may save that person hours of wasted time in a job search which isn’t well-targeted. Bringing a new employee on board is a collaborative process. I have given clear negative feedback to candidates who I didn’t hire, and then employed those same people a few years later. It costs nothing and builds trust.

No Technical Tests

This might not apply to all organisations: but I strongly advise you to remove the technical test. The technical test is usually a way of uncovering technical proficiency. However, well run interview process, asking the right questions, will uncover the candidate’s technical proficiency naturally. Asking about their experience, examples of work, examples of past mistakes, all of these things develop towards understanding this.

If you absolutely must do technical tests, then do with an unfixed deadline, and pay the candidate for their time. I usually ask a candidate for an up-front day-rate early in the interview process, and work from there. Expect it to take time to come back, and always assume your candidate has, and is entitled to, a private home life which your process should not interfere with. Expecting someone to work their day-job, then spend their evenings doing a technical test, just to meet your arbitrary deadline? Unacceptable.

Meet Candidates In Context

If you are a remote organisation, conduct the process remotely. If you’re an in-person organisation, meet your candidates at your offices. The interview process is all about building context, and your candidate is watching and noticing everything. A candidate would, unsurprisingly, be skeptical about an ‘100% remote’ position when the interviewer is sat in an office, with poor videoconferencing equipment, and a busy office in their background; a clearly dissonant context.

Don’t Use A Recruiter, Until You Find The Right One

There is perennial natural hostility towards recruiters among most software organisations. Low-quality recruiters are a constant annoyance, who treat the recruitment process as having a probability-based outcome. Ignore all recruiters who are playing the numbers by sending unsolicited CVs to cold contacts.

However, there will come an inflection point when you find the right recruiter, and suddenly working with recruiters becomes incredibly valuable. A high-quality recruiter:

has pedigree with a particular technology stack, the narrower the better. A ‘software engineering’ recruiter is no help to you. A ‘Python software engineering recruiter’ is better, but a “Django software engineer recruiter” is best.
understands their candidate base, and networks with them all the time. Note that LinkedIn isn’t networking, and sending emails isn’t networking. I’m talking about real, in-person, taking-people-out-for-dinner networking. Boots on the ground.
is willing to take the time, sometimes months, to understand your business and the type of candidate who will work for you.

If you find a recruiter who works for you like this, then you should stick closely to them, because that is the relationship which will ensure you only encounter high-quality candidates at the top of your hiring funnel. Quality in, quality out.

Link Roundup #3

2023-01-20T00:00:00Z

Amazon is discontinuing its AmazonSmile charity program next month

“Amazon emailed participants of the free program about the news on Wednesday. The email said that AmazonSmile, which launched in 2013, ‘has not grown to create the impact that we had originally hoped.’”

It’s despicable that the Smile programme only managed to have ~$45m/year impact, during a time when Amazon was one of the most valuable companies in the world. I’ll happily acknowledge that is a milquetoast take, but in truth Amazon did a poor job of promoting Smile, and it was difficult for charities to engage their constituents. The programme could have offered a link to automatically enroll: amzn.to/cancerresearchuk, which I raised a couple of times with our AWS account manager. A very disappointing whimper.

Programmer salaries in the age of LLMs

“Just like how a partner at [law firm] Cravath likely sketches an outline of how they want to approach a particular case and swarms of largely replaceable lawyers fill in the details, we are perhaps converging to a future where a FAANG L7 can just sketch out architectural details and the programmer equivalent of paralegals will simply query the latest LLM and clean up the output.”

I don’t understand the asserting that this will only be available to senior FAANG engineers. Software engineers at all levels can benefit from understanding and leveraging LLM assisted practice. Resistance is futile. That isn’t to say that we are removing the ‘craft’ of software engineering (though you could argue that most languages have a standardised ‘style’ and ‘way’, especially at higher levels), but more that the craft is moving to a higher level of abstraction. For better or worse.

Link Roundup #2

2023-01-13T00:00:00Z

Microservices are a Big Ball of Mud

It’s incredible that we still have microservice defenders in 2023. It’s a prime example of the immaturity of software enigneering; the cargo-cult is truly rampant.

The article makes the point that this is ‘over-engineering’, which I take issue with. Over-engineering usually implies a baroque, but working solution, when microservices rarely even work in practice.

In a parallel universe, in which there exists effective way to measure software engineering productivity, the thousands of years of effort wasted on microservices would be exposed.

Is Moving to Mastodon Ethical?

“Everyone is wondering out loud whether Mastodon can take the strain and whether it can provide cool new features. What we haven’t been discussing are two ethical questions: First, is it OK to bail out of Twitter? And if bailing out, is Mastodon a acceptable place to land?”

Of course it is.

While I won’t participate, it’s encouraging to see federation beginning to pierce the mainstream consciousness. Our federated software is our most successful software; email and the web. The model is proven and reliable and scalable, even if it’s only controlled by some independent greybeards rather than a corporation (again, this model worked just fine until about 2010).

No-one makes the case that “racists and abusers have access to email, therefore no-one should use email”.

Link Roundup #1

2023-01-05T00:00:00Z

A few years ago I used to write these short articles with links to interesting things I found on the internet. I stopped doing that because I didn’t have the time to write them. Now I have the time, so I’m going to start doing it again.

Surviving Disillusionment

The software engineering discipline is deeply immature. As we seem unable to rectify this, it’s unsurprising that a lot of software engineering has been relegated to software plumbing (and soon, further relegated to proofreading AI output). So disillusionment is never far from anyone’s mind:

“[…] engineers are faced with two realities. One reality is the atmosphere of new technology, its incredible power to transform the human condition, the joy of the art of doing science and engineering, the trials of the creative process, the romance of the frontier. The other reality is the frustration and drudgery of operating in a world of corporate politics, bureaucracy, envy and greed […]”

Oligopoly Everywhere

Consider that while the internet grapples with centralisation and federation, the same question has been asked for a long time in other media. What are we doing to make the media accessible to outsiders, or independents? Could we ever resist the safety and predictability which centralisation promises, in art, politics, software, and systems?

Where Did Software Go Wrong?

“The Internet was a fantastic assemblage of all the world’s knowledge, and it was a bastion of freedom that would make time, space, and geopolitics irrelevant. Ignorance, authoritarianism, and scarcity would be relics of the meatspace past.

Things didn’t quite turn out that way. The magic disappeared and our optimism has since faded. Our websites are slow and insecure; our startups are creepy and unprofitable; our president Tweets hate speech; we don’t trust our social media apps, webcams, or voting machines. […] Where did it all go wrong?”

A game a week #3

2021-03-28T00:00:01Z

This week didn’t have much consistency. I did a lot of work on this game last Sunday, and then I was busy most of the week, and I barely touched the game. I finished it yesterday. I think this shows in the final product; last week I wrote about being glad of having a refactoring pass on the code, something which I didn’t manage to have this time.

I did make some progress though, I think. I had a conversation with a friend last week about snake.py, and how I did at some points have interesting ideas which I ended up walking back because of the complexity it added to the code. I realised that was stupid, and that I know plenty of tricks to manage complexity in Python code; I just had this ’everything in a single file’ constraint in my head, which didn’t make any sense.

So, with that constraint lifted, and some ideas about common things which I needed to implement in both Week 1, Week 2, and Week 3. So I began extracting some items into an engine package. Right now these aren’t anything special; but there is a useful TwoDArray class which I think I’ll use a lot in the future.

tetris.py

Tetris is a game which I have played a lot; I had a fairly good idea before I began of the data structures behind Tetris, and how its implemented on the NES and the Gameboy. Tetris is interesting, because it has a sort of nested gameplay loop; the playfield advances continuously based on the level, but within that loop you can make multiple inputs and rotations.

I began by putting together an implementation of the data structures for the pieces; there is some interesting dynamics for how the irregular shapes rotate (not always around the pivot you’d expect), and I wanted to create something which was classic-Tetris accurate:

After this, I began placing the pieces in the playfield, establishing constraints on their movement (you can see a bug below where certain pieces can’t move across the whole X dimension due to how the pieces were modeled). So far, this was a really naive implementation:

Next, I began actually modelling the game state. The game is a 2d array of integers. I use certain integers for different tasks: 0 is empty space, 1 is a solid wall (ie. the edge of the playfield), 2 is a ‘settled’ block, 3 is an active block. The falling piece data is additively combined with the playfield for collision detection: so for example, if our active play piece 3 combines with the wall of the playfield 1, then we get 4, which is a collision, and the move can be rejected.

This additive model produces some interesting bugs, for example when you constantly add each game tick rather than correctly resetting state:

I’m pretty sure there are still bugs in this approach; occasionally due to how this collision is calculated, you can get a piece stuck in the wall with the right combination of input mashing and spins.

I’m reasonably happy with the end result; this is a minimum viable Tetris game, but it supports advanced movement (for example, you can properly T-spin if you’re fast enough), and the gameover state works similarly to the Gameboy where you see the blocks overwrite eachother for a few game ticks. This is pleasingly authentic.

Here’s the code.

A game a week #2

2021-03-19T00:00:01Z

I captured the momentum of last week, and began this game on Sunday evening.

There was certainly more time spent on this game, but I spread it out over several evenings. I’ve also shared the first week’s post with a few people, and I’ve had some interesting conversations. I’ve started to develop a rough project list in my head, building complexity. This list is very likely to change.

Tetris
Sokoban
Conway’s Game of Life
A perspective/sprite scale based racing game (think Outrun)
A raycaster

snake.py

This was a level up in complexity from last week. There was a lot more game state to manage, and while I understood the game pretty well before I began, there was some mis-steps.

I managed to build this quite quickly. I probably has the game fully ‘working’ after two short sessions of work, so maybe 3 hours in total. I then has plenty of remaining time to refactor, which I’m glad of. The final version of the code (which would probably be tightened up further) is much more elegant due to the time I could spend analysing the code and making improvements.

I also spent time on ‘game’-related things (on the web, I guess we would call this UX), like a score and a lives system, useful information for the player in intermission screens, and some really basic sound. All these add up to make it feel like a real game rather than pong.py from last week.

I think my primary problem was one of manageing game state. I ended up with an awkward system where the SnakeGame contains the Snake instance, and sometimes when they need to reference each other (like in Snake.collide()), I pass a complete reference to the game. This is pointless, and really both should just be in the global scope for a simple game like this.

I also think there is some subtle duplication between the collision detection functions on the Snake, and the SnakeGame.empty_location() function. empty_location() is used to find a position in the game world which is not occuped by anything else (eg. a wall, or the snake’s body), in order to place down a new item of food. So really this is just the inverse of detecting a collision, so I think I could refactor this more to simplify.

While I was browsing the PyGame documentation, I came across the Rect collision detection functions, too. So I wonder if there’s a ‘stateless’ version of this game which just operates based on collisions between thing on the screen. I expect I’ll explore that more soon, because I want to make better use of the Sprite classes rather than just drawing everything manually as tiles.

Here’s the code.

A game a week #1

2021-03-14T00:00:00Z

Introduction

Like a huge amount of software people, when I was young I learned how to write code because I wanted to make games.

Now fast-forward 30 years, and I’m a full-time software engineer, I lead software teams, working on big, complex projects, but I’ve still never finished a single game.

Looking back, the reason that I never finsihed a game was due to the scale of my vision. Back when I had the time to make games, I never set out to make ‘small’ games. They were always too grand, the vision too large, assuming that any knowledge which I was lacking could be picked up along the way. So each time I set out to write a game, I failed.

I think that I’ve learned more humility since then, and I’ve learned how to learn. I’ve learned about building understanding via incremental steps, immediate feedback loops, and the small victories which bring progress.

I still want to make games.

So I figured that I should start with small games. And build one a week (or whenever I have the time). I just built my first one.

pong.py

This isn’t even Pong. It’s more like a half-finished Breakout clone, though it’s missing the bricks to break. But it does some things which I’d forgotten about: initialising a screen, creating a timed input look, responding to input. These are foreign to me, given that I’ve spent most of my career dealing with the HTTP request/response cycle. Real-time code is a mystery to me (I had to seriously rethink my approach once I typed import threading!)

The stack is unimpressive: Windows, VSCode, Python, PyGame. I use Windows in my ‘real’ job, though I run a remote VSCode server, so it’s effectively Linux. I forgot how many hoops you need to jump through to run simple code on Windows (and how unpleasant the Windows shell is). None of this was insurmountable, but I suppose that building web software all day on Unix-likes spoils you; it’s all so simple and well understood.

The game has no standout features. The ball only follows a 45-degree path; my geometry is terrible, and I didn’t want to exercise it here. The game has a completely linear difficulty progression; I challenge anyone to score more than 20 points before it becomes too fast and unbalanced to keep up.

Nevertheless, I’m pleased that some of the knowledge came back to me, and that PyGame is still around (it’s the same library which 15-year old me was using so long ago), and that it seems that some of my real-world experience has helped me see these things as annoying details to be understood, rather than insurmountable obstacles.

Here’s the code.

Listing all Django URLs in a project

2021-02-16T07:00:00Z

This will list all registered Django URLs in a project, with their arguments.

from django.conf import settings
from django.urls import URLPattern, URLResolver
urlconf = __import__(settings.ROOT_URLCONF, {}, {}, [''])
def urls(ls, acc=None):
if acc is None:
acc = []
if not ls:
return
l = ls[0]
if isinstance(l, URLPattern):
yield acc + [str(l.pattern)]
elif isinstance(l, URLResolver):
yield from urls(l.url_patterns, acc + [str(l.pattern)])
yield from urls(ls[1:], acc)
for u in urls(urlconf.urlpatterns):
print(str(u))

Parallel Rsync

2021-01-17T11:15:39Z

rsync will run in sequential mode by default. This can cause transfers to take a long time, and it’s unlikely to make full use of your bandwidth if you’re copying many small files (for example, when syncing a home folder). This situation can be slightly improved by using xargs to run many parallel rsync operations:

ls /home/yourname | xargs -n1 -P8 -I% rsync -Pa % destination:/home/yourname/

You can adjust the -P argument to change the number of parallel processes to run.

Dokku Cheatsheet

2020-07-12T16:09:06Z

I always forget how to setup new Dokku apps; I do it infrequently enough that it never sticks.

Create the app:

$ ssh host
$ dokku apps:create myapp

Create the database and link it to the app:

$ dokku mysql:create myapp
$ dokku mysql:link myapp myapp

Set some variables. DEBUG and SECRET_KEY are Django-specific, and the other is for SSL provisioning:

$ dokku config:set --no-restart myapp SECRET_KEY=foo
$ dokku config:set --no-restart myapp DEBUG=True
$ dokku config:set --no-restart myapp DOKKU_LETSENCRYPT_EMAIL=me@example.com

Now, on the localhost, setup the repository and push:

$ git remote add dokku dokku@host:myapp
$ git push dokku master

Finally, back on the live server, setup port forwarding (I’m not 100% sure if this is necessary, and note that I run gunicorn on port 8000 in my containers), and SSL:

$ ssh host
$ dokku proxy:ports-add myapp http:80:8000
$ dokku letsencrypt myapp
$ dokku letsencrypt:cron-job --add

Done.

Github Marketplace Endgame

2020-07-02T17:46:06Z

I’ve been thinking recently about Github Marketplace; where it may lead.

I’m responsible for technical purchasing at Giant. That means that I’m ultimately responsible for the purchasing we make; but I’m also required to justify those purchases. We’re an SME, and the expenses cannot easily flex beyond their budget, and there are other people in the business who will examine the expenses line-by-line most months.

This level of scrutiny is challenging; and having to develop organisational buy-in for each purchase is exhausting. Sometimes I need to justify temporary SaaS purchasing for a month or two; sometimes I’m going to take a longer term decision to buy for multiple years. The latter of these committments gives me flexibility, because there’s no expectations of predicting the future and cost changes. That is a roundabout way of saying that I get more questions about spending £100 on a random SaaS transaction for one month than I do spending £100,000 on AWS in a year. I speak to other CTOs, and we’re all in similar positions.

Of course, water takes the path of least resistance; so when I have a purchasing decision to make, no matter how large or small, I’m going to ask two questions:

Can I purchase this through AWS?
Can I purchase this through Github?

Either purchase option subsumes the costs into a larger, more flexible one, and leaves me with little justification to make. It’s an easier position to be in.

Anyway; to the point. I’ve been thinking a lot about Github Marketplace recently, and it’s potential to change engineering purchasing. Currently, my Github seats are the minority part of my overall Github bill; I also buy CircleCI, Codecov, and several other services from the Github Marketplace. And as long as the above two questions remain, I’m going to continue to buy services on the Github Marketplace. And it’s interesting to think about what these could be:

Development instances (Coming soon via Github Spaces)
Further automations and actions.
Code reviews on demand?
Software licensing (it’s not available yet, but I’d love to add my JetBrains purchasing to Github)
Azure services; this seems like a no-brainer.

A future where I buy the engineers on my team their ’tool stack’ in a single place is something I look forward to. A future where I use the Github Marketplace to access freelancers with verified contributions in a given language is unsettling (for reasons I can’t quite pinpoint) but possible.

Of course, there are monopolistic concerns here; but I’m also resigned to convenience winning against all forces of market intervention (at least, over a long enough period). I was a BitBucket contrarian for a long time, but the pull of the single, coherent marketplace is pretty irresistable.

tldr; Buy MSFT.

Digital Workshop

2020-06-24T00:00:00Z

In the neverending quest for the ‘right’ development setup, I’ve been thinking about the concept of how to organise and make available my tools. This is partly motivated by some ’new’ (to me at least) tools and options which are becoming more popular; remote development (as included in VSCode), both in the sense of a remote server, but also a remote environment, like a container.

I’m currently editing this on a remote server; I’ve used this setup for about 90 days or so now. The motivation for this is partly the churn which I was experiencing earlier in the year around technology setup which I was using day to day (just look at the recent post history to get an idea: Arch, FreeBSD, Void, and now Windows 10). Having a volatile setup isn’t condusive to productive work, so I moved all my development tools to a server with Digital Ocean, and as long as my local machine had an SSH client and my SSH key, then I could work.

So far, this setup has been very pleasant. It’s really nice to treat the computers which I use for development as thin clients, and being able to move from my desktop to any laptop I have to hand and keep on working is liberating. Having a reliable environment is comfortable; the metaphor is something like a craftsman being at home in his own workshop.

There are annoyances, however. It takes time to connect to the server (only a few seconds here and there, but those add up), and very occasionally I’ll lose my connection for no apparent reason (I guess maybe wifi congestion in my house). I also lose state between machines; VSCode doesn’t seem to keep track of the buffers which I have open, which means I lose context sometimes. Some of these problems could be solved in other ways; SSH is used as the underlying transport, and I know there are ways to make SSH more robust to losing connection, and I imagine some of these techniques would work.

I also have some underlying anxiety about the way my workshop was built; it’s completely organic. I created the environment in a hurry, and since then I’ve neglected any repeatability; my environment is a mess of apt packages, some static binaries in ~/bin/, plus the usual npm vomit, various tools installed in mysterious ways with curl | bash (for shame!). If I want my homestead to really feel like home, I need to automate the setup.

This lead me to investigate VSCode remote development in a container; this should alleviate the repeatability AND the connectivity problems; assuming on each machine I’m willing to add a dependency (Docker) to go alongside the others (VSCode, SSH). It’s something I intend to explore over the next few weeks. The inventory of tools I need is something like this:

pyenv, pipx, libpython-dev and friends.
build-essential and friends.
git, my .config
git flow
My awscli setup, and associated credentials and configuration.
ripgrep
hugo
kubectl and various other k8s related tools.
node, deno, npm etc.

This is already quite a diverse list; I wonder if this lends itself to also investigating using nix to manage.

Serverless Thoughts #2

2020-06-23T09:30:00Z

After hacking yesterday through a few issues with my AWS account (transferred a domain name from one AWS account to another, but didn’t remove the NS records from the original account led to some DNS confusion and AWS couldn’t then verify certificates in Certificate Manager), I’ve managed to come to a good place with serverless.

I now have a Flask application, with multiple routes, running behind an API Gateway with a custom domain.

It’s available as a cookiecutter repository at flask-serverless.

There was nothing particularly notable about getting to this point. The serverless CLI seems to behave predictably, and recovers from errors (for example, interrupted deployments) well. I was slightly confused about the need to use us-east-1 as the region due to the availability of AWS API Gateway (which seems to be available in other regions, too), but I don’t want to look under that particular rock yet.

My goals for today include configuring DynamoDB to add some models to the application. It would be nice to have a serverless database and application running; I may need to look into some plugins such as serverless-dynamodb-local for development.

Serverless Thoughts #1

2020-06-22T09:30:00Z

I’m on holiday this week, and I wanted to use the time to really get to grips with serverless models of deployment.

My background is in Python development (which I want to stick with; this week isn’t to learn a new language), and mainly around doing full-stack deployments with Django, and all that entails; a persistant relational database, the MVC pattern, and server-side rendering.

I have a background knowledge of AWS Lambda (ie. I know what it is, I know what it can be used for, but I haven’t actually used it), and I’ve a vague set of notions around things like AWS API Gateway, AWS SAM, etc. In short, I am no expert.

I have a very simple application which I want to deploy; a very limited set of views, and a very simple data model which would be suitable for a schemaless store like AWS DynamoDB, or AWS ElastiCache/Redis.

So last night, I began doing some research. In all instances, I was looking to deploy a trivially simple Flask application:

from flask import Flask
app = Flask(__name__)
@app.route('/')
def index():
return "Hello, I'm serverless."
if __name__ == '__main__':
app.run()

I realise this isn’t at all testing any of the factors of the serveless model which are actually interesting; this doesn’t react to events, it doesn’t do anything to mutate the state of another, it’s dull. But, I figured that if I can get Flask installed, that means that I have a reasonable Python runtime, into which I can install Python packages. And that’s good enough for me.

Zappa

Zappa was my first instinct. I’ve heard of Zappa previously; at the time, it made some really interesting claims around easily adapting a WSGI application (such as a Django application) to a serverless environment. I also knew that Zappa was a Python package, so my research was rushed (or non-existant).

pip install zappa

… followed by a deployment with:

zappa init
zappa deploy

This was magical. The deployment went well, it appears that Zappa created the dependant resources which I needed in AWS, and I could curl my Flask application and get the response I expected. Very encouraging. Time to learn more, time to visit the documentation at zappa.io.

Oh.

It’s down. I checked the Github issues; it seems the project is in a state of mid-handover. The original developer has disappeared, or lost interest. There are maintainers who are looking to create releases, but they neither have control over the project domains (and, sadly, are closing tickets which relate to this: #1976). There is a new Pypi release from March 2020, but the project is sending very mixed signals. There’s clearly work ongoing to stabilise the repository and the infrastructure, but I’m wary to depend on Zappa until these issues are resolved and the code comes into common ownership.

Architect

Following from that disappointment, I began researching Architect. This is the open-source element of begin.com. Again, setup was near trivial (even so simple to understand that a quick detour into deploying a deno application took 5 minutes).

arc init
arc deploy

I’m especially intrigued by the idea of embedding your data models in the .arc DSL. This is a fascinating way to get started quickly with an application. It’s an approach which might have real merit. It feels clean and minimal and well designed.

Unfortunately, Architect cannot currently clean up after itself. This is a dealbreaker. It appears there is a package to provide this, but it wasn’t something I wanted to battle with integrating.

So I had to spend 15 minutes cleaning up the mess in my AWS account which was annoying.

Serverless

Next on my list was Serverless. This seems like a ‘mature’ offering; supporting a few languages (but I only really care about Python), with a monetisation models based on selling dashboard access to teams. This is fine; the core of the tool is MIT licenses.

Again, the setup is simple, with the annoying detour of being asked to register an account. The dashboard seems useful. There’s an serverless remove command to clean up.

This seems promising.

Creating a new email user with `postfix` on Void

2020-01-28T12:20:23Z

This is possibly specific to my own super-minimal postfix setup on Void, but to add a new email user:

$ sudo adduser someone
$ sudo passwd someone

Amend /etc/postfix/virtual, as follows:

someone@domain.com someone

Regenerate the virtual alias table:

$ sudo /usr/sbin/postmap /etc/postfix/virtual

And finally restart postfix:

$ sudo sv restart postfix

User services with `runit` on Void Linux

2019-11-23T16:51:00Z

Void Linux uses the very miminalsit service management tool runit. The runsvdir program monitors a folder for service definitions, and then supervises the processes described within. There is a system-wide instance of runsvdir for system services by default on Void, which is responsible for your ttys, sshd, maybe a logger, depending on your configuration.

There will be times when you want to run a service, or a set of services, as a user, rather than as root, and to do this you can use nested runsvdir.

Throughout these examples, replace ‘voiduser’ with your own username.

First, will define a system-wide service for running an instance of runsvdir for the user. This will find it’s set of services in the folder $HOME/service:

$ sudo mkdir -p /etc/sv/voiduser
$ sudo touch /etc/sv/voiduser/run
$ sudo chmod +x /etc/sv/voiduser/run

Add the following to /etc/sv/voiduser/run:

#!/bin/sh
UID=$(pwd -P)
UID=${UID##*/}
if [ -d "/home/${UID}/service" ]; then
chpst -u"${UID}" runsvdir /home/${UID}/service
fi

Now, start this service:

$ sudo ln -s /etc/sv/voiduser /var/service

Now, we create a service file for the user. In this example, it’ll run syncthing, but you can adapt this for any given service:

$ mkdir -p $HOME/service/syncthing
$ touch $HOME/service/syncthing/run
$ chmod +x $HOME/service/syncthing/run

Then the contents of the run file:

#!/bin/sh
export HOME=/home/jonathan/
exec 2>&1
exec /usr/bin/syncthing

That’s it. Now, your system-wide runit will start your user-level runit, and it’ll run the service. You can check your process tree and see syncthing running as your own user.

Thinkpad X230/X220 keyboard swap

2019-11-15T11:15:39Z

I recently replaced the keyboard in my Thinkpad X230 with the keyboard from and X220. There are a few reasons for this; while the chiclet keyboard on the X230 is decent (I’ve used it for about a year without any real complaints), the keyboard from the X220 is a much more typist-friendly layout, with a huge Return key, a more sensible layout for Home/End/PgUp/PgDown, and a huge Escape key which is wonderful for Vim users. There’s also more key travel and a very nice aubible feedback with this keyboard, which appealy to my preferences. The Thinkpad keyboard part also includes the trackpoint, and the mouse buttons (the touchpad is part of the ‘chin’ section, but I have it disabled in favour of the trackpoint anyway). I think that the trackpoint sits slightly higher and is more pronounced, and that the mouse buttons have slightly more travel and click to them; this could also all be just becuase I’m using a new part without the curulative wear my old one had.

Hardware

The process for swapping the keyboard is fairly simple. First, you need to remove the existing keyboard:

Begin by removing the battery.
On the underside of the laptop, there are two screws which hold the keyboard in place; they’re marked below:

< image >

Remove these screws, then turn the laptop back over, and open the lid.
Gently pry the keyboard up from it’s front edge. There are four retaining tabs on the X230’s keyboard, one on each side of the keyboard near the left Control key, and below the arrow keys, and one each side of the space bar.
Once the keyboard has popped up, slide it forward gently to expose the ribbon cable.
Gently pry the ribbon connector upwards from it’s seat.

Now you have the keyboard removed, you need to slightly modify the X220 keyboard to fit.

You’ll notice that while the old keyboard had four retaining tabs on it’s front edge, the X220 keyboard has five, larger tabs. From left to right, we’ll number them 1, 2, 3, 4 and 5.
You need to entirely remove tab 3 (which is adjacent to the middle trackpad button). You can do a neat job of this with a file and a sharp knife. I didn’t have these tools handy, however, so I used a set of fingernail clippers (I know, I’m ashamed). The tabs are made of a sandwich of soft metal and plastic, so very little force was needed.
You need to re-shape tabs 1, 2, 4 and 5 to flatten them. Again, I used the clippers which I had to hand, and snipped the edges of the tabs, then bent the metal to shape and trimmed it as necessary to remove the bezel and create flat metal tabs.

At this point, you’re ready to reconnect the keyboard:

Connect the ribbon cable, slide the keyboard backwards into the tray, and then gently push down on the front of the keyboard. The modified retaining tabs will pop into place with a little push. The keyboard I had was an excellent fit, and even before tightening the screws it felt solid.
Flip the laptop over, and replace the two screws. Be careful with these screws, they’re very soft metal and easy to strip.
Replace the battery, and power on the laptop.

Bringing up KVM on Arch

2019-11-08T19:19:42Z

It’s reasonably simple to bring up a new KVM system on Arch, assuming your hardware supports VT-x or AMD-V (and almost everything does).

First, check that you have the capabilities needed. The first command checks that the CPU supports virtualisation, and thr second whether your kernel has the appropriate modules available:

$ lscpu | grep "Virtualization"
$ zgrep CONFIG_KVM /proc/config.gz

Assuming there are no surprises, now install libvirt and a few helpers. We use qemu as it provides a lot of useful utilities for dealing with disk images (among others), and virt-install is a useful helper script for quickly setting up new virtual machines.

$ sudo pacman -S libvirt dnsmasq qemu virt-install

Start the service:

$ sudo systemctl enable libvirtd.service

Now we use the virsh client to connect to the KVM daemon:

$ virsh -c qemu:///session

Now, we need to create a storage pool, as a precursor to creating a storage volume:

virsh # pool-list --all
Name State Autostart
---------------------------
virsh # $ pool-define-as main dir - - - - /home/jonathan/.local/libvirt/images
Pool main defined
virsh # pool-build main
Pool main built
virsh # pool-start main
Pool main started
virsh # pool-autostart main
Pool main marked as autostarted
virsh # pool-list --all
Name State Autostart
----------------------------
main active yes

Now, create a storage volume (in this example, I’m calling the volume ‘storvol’, but I’d adapt this to your VM’s role, so ‘mail’ or ‘www’ or similar):

virsh # vol-create-as main storvol 20GiB --format qcow2
Vol mail created

Finally, we can create a new VM (or ‘domain’ in libvirt parlance). First, exit virsh with ^D. Then:

$ virt-install --name yourvmname --memory 2048 --vcpus=2 --cpu host --cdrom=/home/user/downloads/archlinux-2019.08.01-x86_64.iso --disk size=10,format=qcow2 --network user --virt-type kvm --console pty,target_type=serial

TabNine on FreeBSD

2019-11-05T12:24:36Z

I’m a big fan of TabNine, a machine-learning powered omni-completer for pretty much any language. It’s a hassle to run with FreeBSD, though. These instructions cover running TabNine with Neovim, but you can ignore the Vim-specific parts if you just want to run the TabNine binary on FreeBSD.

First, install the plugin in your Neovim configuration file:

Plug 'zxqfl/tabnine-vim'

Save your configuration, then :source % and :PlugInstall. Restart nvim, and after a short compliation delay, you’ll see that TabNine fails to load. Time to fix this. First, we need CMake, which te TabNine install script requires. Then we need to enable the Linux binary compatibility layer for FreeBSD:

# For the installer
$ sudo pkg install cmake
# For Linux binary compatibility
$ sudo kldload linux64
$ sudo kldstat
$ sudo pkg install emulators/linux_base-c7

Now, we can manually run the installer. I only have python3.6 installed on my FreeBSD system, yours may differ:

$ cd ~/.config/nvim/plugins/tabnine-vim/
$ python3.6 install.py

Once this has completed, we need to manually ‘brand’ the binary as a linux binary so that the operating system knows to use the Linux compatibility layer:

$ cd ~/config/nvim/plugins/tabnine-vim/binaries/2.1.11/x86_64-unknown-linux-musl/
$ brandelf -t Linux ./TabNine
$ ./TabNine --version
TabNine 2.1.11 (x86_64-unknown-linux-musl)
Jacob Jackson (jacob@tabnine.com)

Now you can just start your editor/IDE normally, and the ./TabNine binary should work normally.

I’ve not upgraded my TabNine since I wrote these instructions, but I expect it will be necessary to re-brand the binary each time it is rebuilt.

The simplest pulseaudio installation on Arch

2019-08-20T10:44:11Z

I’ve previously ended up very confused by pulseaudio. Previously I’ve had over-complicated setups using a global daemon when really the standard Arch packages are very well thought out, and don’t require much setup at all.

For a basic pulesaudio installation from a clean installation, this is all you need:

$ yay -S pulseaudio pulseaudio-alsa ncpamixer
$ systemctl enable --user pulseaudio.socket
$ systemctl start --user pulseaudio.socket
$ ncpamixer # Ensure your audio device isn't muted or anything silly

That’s it. This works well for a simple setup with a single USB soundcard, and the defaults are sensible and automatically detected.

Distributed compilation with distcc on Arch

2019-06-13T00:00:00Z

Sometimes, when I’m working, I’ll prefer to sit on the couch with my laptop, which is a not-very-powerful i5/8GB Thinkpad. Sometimes I want to install some packages from source, or compile some software on my laptop. It’s far from ideal for this job, mainly because it takes some time, and the thermal changes in the laptop make it kind of uncomfortable to actually perch it on my lap.

I also have a very powerful desktop machine on my network (i9/64GB), and another slightly less powerful NAS (i5/8BG). Naturally, I’d like to delegate as much processing to these machines as possible when compiling. Fortunately, distcc makes this nearly trivial.

Before we begin, it’s worth noting that my network is ipv4 only and everything lives on 192.168.1.X. All the machines involved run Arch.

First, on all your hosts, install distcc.

$ sudo pacman -S distcc # on your local machine
$ ssh desktop.local sudo pacman -S distcc # repeat for each remote machine.

Now, on each machine in your cluster, amend the distccd configuration file to allow connections from your network. You should end up with something like this:

$ cat /etc/conf.d/distccd
#
# Parameters to be passed to distccd
#
# You must explicitly add IPs (or subnets) that are allowed to connect,
# using the --allow switch. See the distccd manpage for more info.
#
DISTCC_ARGS="--allow 192.168.1.0/24 --log-level error --log-file /tmp/distccd.log"

Finally, on each machine, enable the service and start it:

$ sudo systemctl enable --now distccd # local
$ ssh desktop.local sudo systemctl enable --now distccd # repeat for remotes.

Now your cluster is ready, but you need to modify your /etc/makepkg.conf to tell makepkg to use the cluster. First, unbang the distcc in BUILDENV:

BUILDENV=(distcc color !ccache check !sign)

Then, enumerate your hosts, with the number of cores you wish to make available on each:

DISTCC_HOSTS="192.168.1.100/10 192.168.1.101/4"

Finally, change your MAKEFLAGS to use your total number of cores. In this care, I’ve for 10 cores on .100, 4 cores on .101, and 4 cores on the local laptop for a total of 18:

MAKEFLAGS="-j18"

That’s it. When you compile anything with makepkg, it’ll spread the compilation load around your hosts. If you want to check on the status of a compilation job, you can run the useful distccmon-text to get streaming updates from the job distributor.

$ distccmon-text 2 # change this number of faster/slower updates

Syncing Gmail with mbsync

2019-05-14T12:18:34Z

I’ve decided that I want to try to reduce my dependence on Google’s services. A large part of my Google footprint is Gmail, which I have used for about 15 years.

I’ve not entirely planned through my migration yet, but I think I want to use email in a more transactional manner, as was intended; I want to retrive emails from a server, store and back them up locally on hardware which I control, and then send via SMTP. I really don’t find having access to my email via a browser that convenient as it’s rare I don’t have a laptop or a phone from which I can SSH into my own computers. Push notifications for email are an annoyance; I’d rather interact with my email on my own schedule in batches.

No matter what the overall plan, the first step is to being to sync a considerable volume of email from Google’s servers to my own computer.

For this, I’m using isync, which can reliably sync email from GMail’s IMAP servers to a local Maildir, in one (or both) directions. Note that while the package is called isync, the binary I’m using is called mbsync, and the configuration file is .mbsyncrc.

That isync can sync mail in both directions is important as I want to initially have my local setup mirror my current GMail setup, with access via either method, and to later transition to only downloading from GMail.

It’s also necessary to setup an ‘App Password’ in GMail, which will allow IMAP access to your mailbox outside of the usual Google Account authentication flow. Once that password has been created, I suggest you encrypt it locally and extract it via gpg (as the configuration below demonstrates).

My configuration file (~/.mbsyncrc) is as follows:

IMAPAccount personal
Host imap.gmail.com
User jon@jonatkinson.co.uk
PassCmd "<run gpg here>"
SSLType IMAPS
CertificateFile /etc/ssl/certs/ca-certificates.crt
IMAPStore personal-remote
Account personal
MaildirStore personal-local
Subfolders Verbatim
Path ~/mail/personal/
Inbox ~/mail/personal/inbox
Channel personal-default
Master :personal-remote:
Slave :personal-local:
Patterns * ![Gmail]*
Create Both
SyncState *
Sync All
Channel personal-sent
Master :personal-remote:"[Gmail]/Sent Mail"
Slave :personal-local:sent
Create Slave
Sync Pull
Channel personal-trash
Master :personal-remote:"[Gmail]/Trash"
Slave :personal-local:trash
Create Slave
Sync Pull
# Get all the channels together into a group.
Group personal
Channel personal-default
Channel personal-sent
Channel personal-trash

The isync configuration files are in an odd, stanza-based format. The concepts are based around groups and channels. A channel is a bidirectional mapping between a two mail stores (in this case the remote IMAP server and the local Maildir, but this could just as easily be two remote IMAP services). From top to bottom, that configuration file does the following:

Define the IMAPAccount, and it’s credentials.
Setup SSL
Setup the IMAPStore on the account.
Setup the local mailbox.
Define a channel to map the remote mail to the local mailbox.
Define a channel for the ‘Sent’ folder.
Define a channel for the ‘Trash’ folder.
Finally, setup a group called ‘personal’ which is made up of those channels.

The first sync will take a long time (for my decade and a half of email, to my home server over a 75mb link it was around a day, but that also accounts for some gentle throttling on the remote IMAP service). I ran this in a screen session:

$ mbsync -Dmn personal

Once the initial sync has completed, subsequent activity will be much quicker. I use the following systemd timer and service to sync every five minutes:

$ cat /etc/systemd/user/mbsync.timer
[Unit]
Description=Mailbox synchronization timer
[Timer]
OnBootSec=2m
OnUnitActiveSec=5m
Unit=mbsync.service
[Install]
WantedBy=timers.target
$ cat ~/.config/systemd/user/mbsync.service
[Unit]
Description=Mailbox synchronization service
[Service]
Type=oneshot
ExecStart=/usr/bin/mbsync -Va

Thinkpad x230 fingerprint reader on Arch Linux

2019-05-11T11:15:39Z

I have a Lenovo Thinkpad x230, with an integrated fingerprint reader. The system runs Arch. This describes how to identify and register your fingerprint, and then use it to authenticate your sudo actions via PAM.

First, identify the model of fingerprint reader which you have.

$ sudo lsusb
Bus 003 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 003 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 001 Device 005: ID 5986:02d2 Acer, Inc
Bus 001 Device 004: ID 0a5c:21e6 Broadcom Corp. BCM20702 Bluetooth 4.0 [ThinkPad]
*Bus 001 Device 003: ID 147e:2020 Upek TouchChip Fingerprint Coprocessor (WBF advanced mode)*
Bus 001 Device 002: ID 8087:0024 Intel Corp. Integrated Rate Matching Hub
Bus 001 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub
Bus 004 Device 001: ID 1d6b:0003 Linux Foundation 3.0 root hub
Bus 002 Device 001: ID 1d6b:0002 Linux Foundation 2.0 root hub

This device is supported by the fprintd package, se we will install this with the package manager (you can probably substitute pacman for yay here if you’re not a yay user):

$ yay -s fprintd

Now it’s time to ’enroll’ your fingerprint. Your fingerprint data will be stored in /var/lib/fprintd/. This process will require you to swipe your right index finger five times. You can see from the output below that I mis-swiped once. Just keep swiping until the process if complete:

$ fprintd-enroll
Using device /net/reactivated/Fprint/Device/0
Enrolling right-index-finger finger.
Enroll result: enroll-stage-passed
Enroll result: enroll-stage-passed
Enroll result: enroll-swipe-too-short
Enroll result: enroll-stage-passed
Enroll result: enroll-stage-passed
Enroll result: enroll-completed

Finally, we will update two files, /etc/pam.d/sudo and /etc/pam.d/su to enable the fprintd backend. Add the following line to both files:

auth sufficient pam_fprintd.so

As a complete example, my /etc/pam.d/su file looks like this:

#%PAM-1.0
auth sufficient pam_rootok.so
auth sufficient pam_fprintd.so
auth required pam_unix.so
account required pam_unix.so
session required pam_unix.so

Save these files, and then you can authenticate with your fingerprint:

$ sudo echo "Hello, world!"
Swipe your finger across the fingerprint reader
Hello, world!

Installing Arch On a Vultr VPS

2019-05-06T00:00:00Z

Abstract

I have been happy using Vultr as my VPS provider for a few months now. Vultr offer a very flexible system of ISO upload before the first boot, which means essentially unlimited options when choosing the operating system for a new VPS (there is also a large library of ISO images to chose from; only occasionally have I actually uploaded my own).

However, booting a fresh ISO on a VPS can be a challenge; the hardware and devices exposed to the VPS are usually unfamiliar. These are my steps for installing Arch after the VPS has been provisioned by Vultr, and you have a working VNC connection to the console.

This assumes a familiarity with Arch. Don’t forget the installation guide is the most comprehensive resource if you get stuck.

General Checks

Check that networking has come up correctly in the live ISO environment:

# ping -c 1 google.com

Update the system clock.

# timedatectl set-ntp true

Update the Arch keyring.

# pacman -Sy archlinux-keyring

Disk Partitioning

Check the available block devices. Your disk will be available as vda or similar, but adapt the following as required. Once you have identified the disk, use fdisk to partition.

# lsblk
# fdisk /dev/vda

Create a new, full-disk partition by pressing N, and using the default values for each question. Your new partition will be available as /dev/vda1/ once complete.

Write the partition table with W.

Finally, we need to create a new filesystem on the disk and mount it. I use ext4, because I’m unfamiliar with btrfs. Your research might indicate that btrfs is more appropriate for your needs.

# mkfs-ext4 /dev/vda1
# mount /dev/vda1 /mnt

Bootstrapping

Now it’s time to bootstrap the system with the base metapackage. This may take a while. If you plan on compiling a lot of code, it might be worth also installing base-devel at this point.

# pacstrap /mnt base
# pacstrap /mnt base-devel

Soon, we are going to chroot into the new system. First, we need to create an fstab:

# genfstab /mnt >> /mnt/etc/fstab

Now, we will switch over to the new system:

# arch-chroot /mnt

Basic Configuration

Now we are chrooted into the system, set the timezone and sync the clock:

# ls /usr/share/zoneinfo/Europe/
# ln -sf /usr/share/zoneinfo/Europe/London /etc/localtime
# hwclock --systohc

Set the root password:

# passwd

Set the system locale to UTF-8. Visit locale.gen and uncomment en_GB.UTF-8 UTF-8, then set the locale:

# vi /etc/locale.gen
# echo 'LANG=en_GB.UTF-8' > /etc/locale.conf

Networking

Now, find the currently active network adaptor. This is usually called ens3 or similar.

# ip addr

Write the configuration file:

# vi /etc/systemd/network/ens3.network

The content should be as follows:

[Match]
Name=ens3
[Network]
DHCP=ipv4

Enable DHCP, DNS and setup resolv.conf:

# systemctl enable systemd-networkd
# systemctl enable systemd-resolved
# ln -sf /run/systemd/resolve/stub-resolv.conf /etc/resolv.conf

Set the system hostname

# echo 'server.domain.com' > /etc/hostname

Install the bootloader

Install grub, and write a configuration file.

# pacman -S grub
# grub-install --target=i386-pc /dev/vda
# grub-mkconfig -o /boot/grub/grub.cfg

Reboot

Now, exit the chroot, and reboot the system.

# exit
# systemctl poweroff

Now, in the Vultr control panel, unmount the ISO, and boot the system again. Reconnect the VNC console.

Post-Boot Setup

Assuming the system has booted successfully (if it hasn’t, then re-insert the ISO, remount /dev/vda1, and reactivate the chroot to investigate), then login as root.

Next, create a new user, and setup sudo:

# useradd --create-home <yourusername>
# passwd <yourusername>
# pacman -S sudo
# visudo

Find the appropriate section of /etc/sudoers, and add something like this:

<yourusername> ALL=(ALL) ALL

Now, logout as root and login again as your newly created user.

# exit

Next, install SSH and edit the configuration file to enable a port. Typically this will be port 22.

$ sudo pacman -S openssh
$ sudo vi /etc/ssh/sshd_config

Finally, enable SSH:

$ sudo systemctl enable --now sshd

You should now be able to login via SSH (root is denied by default). You can continue your onward configuration from there.

Automatically --set-upstream when pushing a new branch

2019-04-08T17:46:06Z

I frequently open a new branch with git flow, and the first time I push to Github, I see the following message:

fatal: The current branch feature/whatever has no upstream branch.
To push the current branch and set the remote as upstream, use
git push --set-upstream origin feature/whatever

It seems redundant that git offers me a solution and then makes my type it myself (especially considering the solution, to use --set-upstream, is actually deprecated). This finally annoyed me enough to figure out how to remedy this:

$ git config --global push.default current

Now to push to a new branch for the first time, just do this:

$ git push -u

Remembering Rob Edwards

2019-02-07T15:56:03Z

This has been a very difficult year.

This year I lost my best friend and business partner. Rob and I had been friends for fifteen years, my entire adult life. We concieved and ran several failed, and one successful business together. Apart from my wife, Rob is the person who knew me best in the world. We did great deal of growing up together. I miss him terribly, and even now months on from his death, I think about him many times every day.

I don’t want to dwell on how I feel about this. I’m sure over time these feelings will lift. But I have a few stories about Rob which I want to tell.

Very soon after Rob and I first met at university, I transferred to the same computer science course as him. We were living down the hall from one another, taking the same modules and following the same schedule. After a few weeks, when our first ‘real’ assignment was due, we decided the share the burden. I don’t remember anything about the work we were asked to do, it was probably implementing some simple algorithm in Java. We did very little work that night. We sat at Rob’s desk, in the glow of our laptops, and talked; first feeling each other out, then sharing jokes, then testing each other’s boundaries, and finally talking about the things we were passionate about. I was 18 years old, and my passions were very nerdy; I probably talked about Linux and Free Software, and I remember Rob talking about the music which he loved. Most importantly I remember the feeling of ‘clicking’ with someone else. Rob gave me space and time to explain what I loved, and joined me in my enthusiasm for technology and the potential of the connected world which was about to become Web 2.0. I remember talking about IRC, about startups, about hacking, robotics, drugs, and the politics which defined us at that age. We laid down some important foundations that night.

Some years later, Rob and I were working on our second business. We had a nice idea, but very little idea of how to execute on the vision. To demonstrate our inexperience, we were focusing on completely the wrong thing, and we prioritised our website rather than any working technology. By this time we were both web developers; I had been part of a couple of digital agencies, and Rob had run a small agency for a few years at the time. We dragged each other to the very peak of Mt. Dunning-Kruger and built a hopelessly over-engineered website. We were using CSS 2.0, AJAX (back when we just called it XMLHttpRequest). We were operating in a hostile environment of IE4/5, and tensions were high. Optimistic, I’d pre-announced our website launch later that day, to our vanishingly small audience on the IRC channels we both frequented, and a nascent social network at the time called twttr. Rob, less optimistic, was worried that making a promise to launch without leaving enough time for testing the site might cause us embarassment, and Rob picked up the phone and told me this in no uncertain terms. Somehow this argument about our deadline devolved into personal attacks and insults. We screamed at each other, and a lot of very unpleasant things were said. Fifteen minutes later, as we simultaneously called each other to make up, we both left long, heartfelt apologies on each other’s voicemail systems. I know I kept a copy of that voicemail for quite a few years, and I Rob did the same. We used to play them to each other when one of us was being unreasonable.

Further years later, and we are on a roof-top in Manchester, having our photo taken. This is no longer just a story about Rob and I. This is a professional photo-shoot, with us both, but also our staff and business partners, the company we had all built together. There is about twenty of us, and we line up and smile. I remember how incredibly proud Rob and I both felt that day. We were proud that so many people believed in us, enough to join us and work with us as we tried to make a mark.

I remember a few weeks before Rob died, he called me for the last time. A few months before, Rob had left the company, and a lot of anger had been spent, a lot of lines had been crossed. Rob called me because he heard that my grandfather was dying, and Rob knew how much this would be upsetting me. It was a nice gesture, and it started the conversation between us again. We spoke that night for three or four hours, on speakerphone. We spoke about a lot of things, not least our failings which had led us to this unhappy point. We remembered and shared old jokes. We talked about our old friends. As the conversation continued, we both opened up to each other, much like that first evening we spent at university solving stupid homework problems. As the conversation drew to a close, Rob became upset, incoherent. It was rare for Rob to become flustered like this, he was usually good at expressing himself. He told me I had always been kind. Kind to my family, and the people who we worked with. He finished with “you were always too kind to me”, which I still don’t entirely understand.

I wish he was still around and I could ask him what he meant by that, but I suppose that’s just how it ends. Our last conversation was rather like Rob himself; fun, sensitive, chaotic, and a little bit engimatic.

Rob Edwards. 1984-2018.

QBasic Development

2019-01-27T20:08:53Z

Introduction

I wanted to put together a decent build system for QBasic programs.

My goal was to be able to use modern tools such as VSCode and git to edit and manage my code from an OSX host, and to easily run on a representative system of the MS-DOS era, which in this case is an i386 system, with 8MB of RAM, running MS-DOS 6.22.

Currently I’m doing this using virtualized hardward (using the incredibly versatile qemu), but I plan on modifying this in future to send the application to real hardware.

My strategy is similar to any other inject-and-run type system; it’s heavily inspired by how most CI pipelines work:

Build a predictable base image which can be quickly replicated.
Build a system to boot that environment and inject my latest code.
Have the code compiled (or interpreted) inside that environment and be able to quickly interact with the results.

Requirements and workspace layout

First, install the packages we need. This assumes you’re running a modern OSX (I’m using Mojave), with brew installed:

$ brew install qemu

Now, I want to layout our working folder as follows:

$ mkdir img
$ mkdir src
$ mkdir live
$ mkdir scripts

Building the base image

make a working folder:

$ mkdir qbasic
$ cd qbasic
$ mkdir msdos-disks/

move some msdos installer files into place:

$ cp *.img ~/qbasic/msdos-disks/

make harddisk image:

 $ qemu-img create dos.img 200M

boot the system (with 8mb of RAM attached) with the first msdos disk:

$ qemu-system-i386 -hda dos.img -fda msdos-disks/disk1.img -m 8

As the installer runs, you’ll eventually need to change disk. Switch to the QEMU console with ctrl-alt-2. Then, the following command to switch image:

(qemu) change floppy0 msdos-disks/disk2.img

… then switch back to the primary output with ctrl-alt-1. My version of MS-DOS came on three floppy disks, so by the time the installed was complete, and I’d ejected the final disk, the QEMU console session looked like this:

(qemu) change floppy0 msdos-disks/disk2.img
(qemu) change floppy0 msdos-disks/disk2.img
(qemu) eject floppy0

Mounting the disk image:

$ hdiutil attach -imagekey diskimage-class=CRawDiskImage -mountpoint ./live/ dos.img
$ hdiutil detach live

Setting up wee-slack

2018-12-21T12:24:36Z

Installing the prerequisites

First, we need to install the base weechat binaries. I like the aspell plugin to be enabled in Weechat, so I’ll install that first:

$ brew install aspell
$ aspell dicts # Check the available dictionaries.

Now, it’s time to install weechat itself. Weechat has just gone through a transition between Python2 and Python3, and at the time of writing, installing from brew is affected by this bug, so we’re going to explicitly install with Python2 support, and we will install the websocket_client library in the Python2 tree.

$ brew install weechat --with-aspell --with-python@2
$ sudo /usr/local/opt/python@2/bin/pip2 install websocket_client

Installing `wee-slack`

Now it’s time to install the wee-slack plugin. There are more secure ways to do this, but this will work for the purposes of this guide:

$ mkdir -p ~/.weechat/python/autoload
$ cd ~/.weechat/python/autoload
$ wget https://raw.githubusercontent.com/wee-slack/wee-slack/master/wee_slack.py

Now, launch weechat, and you’ll see the following message:

ERROR: Failed connecting to Slack with token starting with INSERT
VALID KE: invalid_auth
ERROR: Token does not look like a valid Slack token. Ensure it is a valid token and not just a OAuth code.

To register, in the weechat console, type:

/slack register

Follow the prompts onscreen. The redirect after authentication will fail, and this is expected, however you need to copy the code parameter from the redirect URL.

Return to weechat, and enter the following:

/slack register [your code parameter here]
/python reload slack

You should now be connected to your Slack instance. You can navigate using common IRC commands such as /join and /query. If you’re setting up weechat for the first time, it will feel more comfortable to turn on mouse mode, which you can do like this:

/set weechat.look.mouse on
/mouse enable

In general, wee-slack works well. Certain integrations which post rich snippets to Slack (for example, the Bitbucket plugin) are quite visually noisy in Weechat, so I want t figure out how to filter or rewrite these to be more concise. But that’s for another day.

Remote Working Roundtable

2018-12-21T12:23:46Z

I was recently invited to participate in a DaaS/Remote Working roundtable discussion at UKFast. I’m not sure I could add anything much on DaaS; it’s not a technology which we frequently use, but I did try to offer what I could on remote-working culture and benefits.

The recording is available (after the registration-wall) here.

Personal VPN Setup

2018-12-21T12:21:27Z

I feel the need to start this post with something impactful about industrial-scale data capture and the weaponsiation of software exploits; this would be covering a well-trodden path, and it’s unnecessary. You need a personal VPN to help secure your privacy your personal data.

I’ve run my own VPN on Digital Ocean (DO) for a few years now. This isn’t ideal; I’d rather run this on hardware which I racked myself, but it’s cheap, and DO have datacentres in privacy-friendly European jurisdictions.

Previously, I have been using the excellent streisand scripts to maintain this service. streisand is a very comprehensive, mature package, and I recommend it for people who live in really hostile environments as it provides a lot of connectivity options to bypass VPN blocking and suchlike. However, there is quite a bit of churn in streisand (probably for good reason; that project faces evolving threats), and each of the last three times I’ve run the install scripts, it’s recommended different defaults, and different VPN clients. This isn’t optimal; I want to install my VPN, and forget about it for a few years at a time, and most importantly I want effortless connectivity from my devices which run OSX and iOS.

This has led me to a much slimmer, more focused solution: IKEv2-setup. The project self-describes as:

A Bash script that takes Ubuntu Server 18.04 LTS … from clean install to production-ready IKEv2 VPN with strongSwan.

Most importantly, IKEv2-setup supplies a .mobileconfig profile for OSX and iOS, with on-demand connectivity; this means that I can be reasonably sure that all my internet traffic will be routed via the VPN.

First, setup a new Ubuntu 18.04 server using the hosting provider of your choice. You also need to setup a DNS record to point to this server (for example vpn.example.com). I’ll assume you can login and get a root shell. Make sure that everything is up-to-date:

$ apt-get update && apt-get upgrade

Download the IKEv2-setup script from Github:

$ cd /root/
$ curl https://raw.githubusercontent.com/jawj/IKEv2-setup/master/setup.sh > setup.sh

Now, read carefully the contents of setup.sh and understand what each step does. If there are any steps which you don’t understand, ask someone with a little more Linux knowledge to review. Installing untrusted software from the internet is dangerous; you need to understand what is about to happen to your server.

Once you are ready to continue, run the script:

$ /bin/bash setup.sh

You’ll be asked for your DNS name, and a VPN username and password, and an SSH username and password (for the passwords, I recommend generating two long different password with pwgen --numerals 32). After these questions, the script will proceed to run; save the output if you’re particularly interested in the changes which were made.

Once the process is complete, further configuration instructions will be located in /home/<username>/vpn-instructions.txt. For OSX and iOS configuration, download the /home/<username>/vpn-ios-or-mac.mobileconfig file. From OSX, you can just double-click the file in Finder, and the profile will be installed. Optionally you may want to visit Network.prefpane and configure the VPN icon in your statusbar. You can then AirDrop this same file to your iOS device and configure the same username and password there.

It’s probably sensible to leave logging enabled on your server for a few days to debug any connectivity problems, however once the service is stable, you can disable any logging as follows:

rm /var/log/syslog && ln -s /dev/null /var/log/syslog
rm /var/log/auth.log && ln -s /dev/null /var/log/auth.log

Recursively updating S3 bucket permissions

2018-12-21T12:20:59Z

If you want to recursively apply a permission to an S3 bucket (for example, to add the public-read permission), then you can use the aws CLI tool to copy from a bucket to itself, and update the metadata as it does so. It’s quicker that using the AWS console, anyway.

$ aws s3 cp s3://bucketname/optional/path/ s3://bucketname/optional/path/ \
--recursive \
--metadata-directive REPLACE \
--acl public-read \
--cache-control max-age=31536000

Listing ElasticBeanstalk applications with the aws CLI tool.

2018-12-21T12:20:23Z

You can easily list EB applications in your default AWS account with the following query.

$ aws elasticbeanstalk describe-applications --query 'Applications[*].{Name:ApplicationName}' --output=text

How To Fire Someone

2018-12-21T12:19:42Z

Don’t hide the message. Be direct and begin with the reason: “I have bad news, you are being let go due to X”.

Make eye contact as you do this, and wait for the reaction. In this situation there is still an opportunity to build trust in each other, and communicate that each party will act properly. Most people react calmly; more often than not professional instinct takes over.

Once that is said, acknowledge the difficulty ahead, and put them at ease. Offer genuine help if you are in the position to give it. “I know this isn’t what you want to hear, but I am going to do my absolute best to make this as smooth as possible”.

All the salary, compensation and notice period calculations should be performed ahead of time, and you need to immediately summarise these. On recieving this news most people feel immediately threatened and need the reassurance they are going to be treated fairly. “You will be paid in full for your notice period of £X, and your holiday allowance which is £Y”. Stick to the dates outlined in the calculations. If there is any disputes at this point over money owed or compensation due, defuse it and accept there may have been a mistake (very rarely does this actually happen). Just say “we will look into any other money owed and make it 100% right with you before you leave”. This conversation is not about money but sometimes its easier to vent anger or shock by pretending that it is.

In general, most people move very quickly go into planning mode. I usually offer unlimited time away to attend interviews, and offer use of any company facilities and equipment to help them search. Equally some people don’t want to attend the office at all.

I usually finish by asking about messaging. I try to give the employee control over the story to their colleagues. Some may be embarrassed, especially if this action is being taken due to performance or conduct reasons. Give the person time to think about this. There is usually zero impact to the company for someone to say “I decided to look for something new” rather than “I was fired”, so unless you have very good reason, you don’t need to control the narrative.

Finally, offer a further meeting very quickly, such as lunch the next day. This offers them a chance to speak again about their feelings once they have processed them.

Remember at all times that we need to be human, decent and honest to each other and sometimes the best thing you can do is quietly listen.

Django coverage reports without unit tests

2018-12-21T00:00:00Z

I was recently working on a Django project which had a lot of development effort spent over a wide range of features which never made it to launch. We wanted to analyse the codebase, in part to identify where we had over-delivered on features which didn’t make the cut, but also to help the development team find and remove the now ‘dead’ code.

The first tool which sprang to mind was coverage.py, which can be used to evaluate unit test coverage. After a little digging, you can use the same coverage engine to detect which code is used while Django’s runserver is active. The following examples assume you have a working Django and Python environment, and you’re installing into a virtualenv:

$ pip install coverage
$ coverage run manage.py runserver --noreload

This will spawn a single-threaded server, which coverage can monitor. You can now exercise your code at will, either by manually testing the site or running some browser automation with TestCafe or Selenium. The quality of your coverage results will be influenced by how thorough you are at this stage.

Once you’re finished, ^C the coverage process, and it will create a .coverage file in the working directory. You can now generate and view a more useful HTML report with coverage html && open htmlcov/index.html. You’ll notice this is very noisy; it includes all your dependencies in env/, and also various files which Django evaluates in full on startup. These skew your results, and make the document more difficult to read, so it’s useful to exclude some results using --omit:

Anything in the virtualenv folder (in my case env/).
Any __init__.py files.
All Django migrations.
All Django admin.py files.
All instances of urls.py.

The final command was as follows:

$ coverage html --omit=*env*,apps/*/admin.py,apps/*/__init__.py,apps/*/migrations/*.py,apps/*/urls.py

Jon Atkinson - Blog

The Hypocrisy of Agentic Coding Critics

Nobody buys software from Intel

The substrate

What Anthropic is actually selling

Models, tools, product

Diminishing returns

Or maybe they won’t let it happen

Developing Good Engineering Taste

Read Lots of Code

Build the ‘wrong’ reflex

Understand the Why Behind Patterns

Work Outside the LLM Safety Net

Learn to Spot the LLM tells

The Meta-Skill

Building Momentum with LLM Coding

GitHub's spec-kit and the cloud agent endgame

How I use Claude Code

notion-to-json

mastodon-to-bluesky

Good practice is good for LLMs too

Codex, Jules, and Claude Code comparison

OpenAI Codex

Google Jules

Claude Code

Four Bubbles I've Lived Through, With One Exception

Metaverse

NFTs

Crypto (The Coin Launch Grift)

AI

Trust but Verify: Sensible Ways to Use LLMs in Production

The MCP Servers I Actually Use

Github MCP server

Fetch

Docker

The future of digital agencies

Preparing Django documentation for LLMs

Setting up Matrix Synapse on Fedora

A Cline prompt for codebase analysis and feature extraction

My Claude Artifact Prompt

Fingerprint Authentication on a Lenovo Z13 and Fedora 40

New in Python 3.13: SQLite support in dbm

Django Carbon Measurement Notes

Using ruff for everything in VSCode

Automatic, persistent autoreload in iPython

A minimal Django application

Logging git commits with a git hook

Conventional Commits Git Hook

How I Do 1-2-1 Meetings

The ‘No Agenda’ Meeting.

The ‘Big Goals’ Meeting.

The ‘Work Catchup’ Meeting.

The ‘Shut The Fuck Up’ Meeting.

Link Roundup #6

Link Roundup #5

Link Roundup #4

Hiring Correctly

The Job Advert

Process Transparency

Feedback

No Technical Tests

Meet Candidates In Context

Don’t Use A Recruiter, Until You Find The Right One

Link Roundup #3

Link Roundup #2

Link Roundup #1

A game a week #3

tetris.py

A game a week #2

snake.py

A game a week #1

Introduction

pong.py

Listing all Django URLs in a project

Parallel Rsync

Dokku Cheatsheet

Github Marketplace Endgame

Digital Workshop

Serverless Thoughts #2

Serverless Thoughts #1

Installing `wee-slack`