I think you’re probably missing why it’s exhausting. The problem is not writing English, it’s the rate of change. Programming is meditative, it is a thinking process, the code you output is an artifact of your thinking. Agent-based development… there is no thinking, no meditation, you’re delegating the thinking to a machine, you’re just barking what you want at it, incessantly, endlessly.
For businesses it makes sense to abandon programming in favor of delegating to agents that can do more in less time, but for programmers, it is a loss. Either be a programmer and code, or be a delegator and delegate, you aren’t going to make the life of a delegator suck any less by trying to trick yourself into thinking you’re programming.
Agree with programming is meditative but disagree that agent-based development means there is no thinking. Agent-based development means more thinking like a lower level manager. You spend more time making architecture decisions, making decisions on the user interface, trying to manage your time and your agents time to increase the amount of work produced in the same time, asking the agent about the code and making new decisions. For many people who went in programming thats not their strong suite and hence is really exhausting. Instead of living in the code you are managing the code and using a part of the brain you are not good at.
I would disagree that there is no thinking. I think a strong understanding of the fundamentals of coding are still wildly important to get good quality code, and a big part of that is thinking or reasoning through a particular problem. It’s just now we have a way of using common language in order for that to happen instead of having to learn or keep up with every new tool and framework in order to do so. The new programming language is just in your native tongue.
I’m not a full time dev, but I code quite a bit doing Systems and OPs stuff, but AI has opened up an entirely new world to me and it has expanded my ability to think through a problem. It’s the ultimate rubber ducky. I love to watch the reasoning process while I’m in opencode so I can interrupt if I see it going down a path that doesn’t make sense.
It’s opened another world to me that allows me to implement ideas I’ve had for years without the time to invest in the skills needed to even try the idea.
I don’t mean to imply that making things with these tools is lesser, or that it doesn’t require some skill, but it is fundamentally different to programming. I’m glad you’re able to bring new things to life with these tools, that’s a great thing :)
My broader philosophical take is that we, programmers, lived through a golden age where our skills used on our terms were some of the most valuable skills. The golden age is over, our skills aren’t useless, they can still be applied to making things with modern tools, but it is no longer on our terms, no longer programming, no longer the meditative thinking process it once was.
For non-programmers, this is their golden age, the reign of programmer tyranny is over.
I think the reverse direction is more important: taking a massive complex problem/codebase and decomposing it to short pseudocode. Then you could edit the pseudocode and compile it back into the system.
That's the way software engineers working on large projects work anyway: you first gather context on the state of the system and read it at a level you can understand. Then you propose a change on the simplified representation, and then holistically update the machine-runnable format ("implementation").
I'd be interested in tools that formalize/automate this process more.
I don't think it's particularly difficult, or clever. You can prompt your way into this with frontier models, especially if your codebase is designed for it from the ground up (architecture well factored, documented, tested, harnessable, so that it even has a pseudocode representation in the first place).
The biggest issue is you end up leaning heavily on the quality of the model. Lower fidelity models tend to make a mess and add tech debt that you must frequently repay with intentional cleanup passes from a higher quality model, or else the rate of useful progress will fall off a cliff. At least that's my experience.
As I see it, there's a bit of internal contradiction: your declared intent is to not write code, but you had to circle back to code (albeit more relaxed and vague) because human English is (compared to proglangs) imprecise. Pseudocode, however, is not far away from it, still not strict, and LLM is still a stochastic generator. So it will continue to randomly deviate from what you want it to do. I guess it could be an enhancement, but who knows, maybe in a year from now, you will get tired with pseudocode not being precise, and go back to writing code :wink:
Afaik there's no language - the pseudocode can be written however you want. And the costing money to compile? If you're prompting an llm you're already doing that, just with prose instead of pseudocode. I'm not sure this approach is a good idea, but it might be - and imo it's worth trying :)
I'm not sold on the pseudocode approach, but I agree with the declarative aspect. Declarative specs have become central to my process and I've built this tool to support it:
Rather than writing exhaustive specs, I preserve only the intent and what must be true as discrete assertions. This preserves the leverage you get from LLMs - anything it can reliably infer does not need to be specified. It also (mostly) separates intent from code or architecture decisions, which keeps specs flexible.
I’ve been thinking about something along these lines for some time. I really like the direction of this.
The challenge I see more broadly is we (as engineers now empowered by LLMs) are trying to find the right level of abstraction to operate in. Writing long form sentences and (sometime) reviewing the output feels too far away. But having an LLM work directly with you in an IDE feels too close to “the old way”.
Personally for me the approach here still feels a little too close to the lower level old way, but it’s better than the two approaches above.
Right level of abstraction is a good way of putting it. It's basically like creating a custom DSL, but flexibility of LLMs allow the DSL to be ad-hoc.
At what point will you need formal rigid syntax? Or is not having rigid syntax the point? If the latter, how much "informational noise" or ambiguity can you inject before the "DSL compiler" gets confused?
Scaling is another bit. Convertible Psuedocode a great pattern for writing functions, but is it useful for writing modules? If you're writing a paragraph to change behavior of a function, you're underutilizing LLMs. Paragraphs are best for spec'ing modules, and the LLMs already fill in the blanks. Not sure if it would be faster to psuedocode the entire module (although maybe just the interface would be a sweet spot...)
Yeah exactly. The module/directory level is currently untested. I'm working on a desktop version so I can talk to a file system, and then I'll be able to explore those problems.
My guess is that if you simply write `use some_fn from $repo/some/path`, the LLM _should_ be smart enough to infer in most cases. But we'll have to see how reliable that is.
Are there examples of how this would work when you need the pseudocode to reference abstract application concepts?
I'm not totally convinced this is a useful way to express something like "Change the data flow so that we bulk query from the DB upfront and pass it down to all callsites"
I think its an interesting approach, much more than most other new agent harnesses at least.
I guess you still need the chat to discuss with the AI? For example, ask it to compare solution A and B, or to explain how to do X. A bit like you can use plan mode today. Then given the result, you can write the hz file (or even have an agent write it).
But I wonder how it works on a more complicated project than fizzbuzz. Can I suggest you use Huzzah to develop itself, and then share the hz file(s)? That will show both how it works on a more complicated project, and something that is developing over time.
Why not just put an instruction into your favorite harness’ system prompt: “If I give you pseudo code, spell out my intent, and then write and test it in real code.”
Not a dumb question - you can totally do this. I was doing this for a while. Before Claude Code really took off, this was my primary way to use Cursor. I'd write some pseudocode, highlight it, and just write to the AI "make it real". Works like a charm.
The issue is that with very large or complex codebases, you tend to forget what was AI generated and what was written by a human. And it's also extremely tedious and difficult to read AI generated code. So if you want to _understand_ a complex bit of code, the natural tendency is to ask an agent to summarize it for you. This can work but also has lots of problems.
What you really want is a system that persists both your written intent, and the actual source code. And you want to provide a source map between them, so that you can understand which bits of human pseudocode are responsible for which bits of generated code.
The real value is in persisting your expressed intent.
I think there's a lot to like about this approach, especially persisting my intent.
I think it will be interesting to see how this plays out when it comes time to debug.
At that time, someone else may be reading my pseudo code and implicitly assuming that the code was translated correctly. If the code wasn't translated correctly, wouldn't the human who naturally assumes it was miss the bug every time?
Huzzah would benefit from having a guard identify pseudo code with two potential interpretations and ask the human to clarify so the reliability of the interpretation does not suffer.
Okay, but then why not make this a new sort of fuzzy language, rather than building a new app with it's own UI?
I think having to open a web interface is a big entry barrier.
Imagine if those pseudocode files could live in your codebase, and the CLI tool would just “build” the actual code, with sourcemaps. You could edit the code in your favorite editor and run “build” commands in your favorite shell.
(TBH, I haven't looked deeply inside the repo and maybe it's exactly how it works. I just saw that demo and readme tell you to open a http://localhost:5173 as if you can use it only via custom UI.)
I'm not sure how to do syntax highlighting for this pseudocode in any IDE, but you could start with supporting something like Alabaster theme, the whole point of which is to highlight as little as possible.
I say this because I really think that if the setup was simpler lots of people would use it. It's a kind of concept that when you read about it, you think “Wait, how did I not came up with this”. Finally some interesting concept in this endless stream of skills, MCPs, loops etc.
Though catching back up on that project- it seems it's evolved pretty substantially, becoming much higher level than the initial pseudocode driven version I remember
I understand your approach and applaud it. I have been doing two things that keep me doing the parts I love. Instead of pseudo code I write in a simple managed language like JavaScript or Python. My instructions to the agent is simple. Code gets no comments. It is intentionally brief and for me at least understandable. Second. I have a document for each code file that holds the an enumerated list of rules used to develop the file - The comments if you will but in a format I can deal with line by line, just like the code. This is substantially more rewarding for me as I change both the code and the document and limit terminal interactions to must-see/do stuff.
I think the way I would want to work with AI for web apps would be like this:
You install a fancy chrome extension or custom browser.
You go through the app on this browser. You notice something you want to change. You can then submit a prompt via this extension saying the change you want.
The trick is, the chrome extension has been following your movements through the app. This way the chrome extension can generate a lot of data the AI can use for a good prompt. I.e. The extension can get a screenshot of where you are in the app and all the pages you went through to get there. The extension can get the console logs and traces and stuff.
So with all this, the AI system gets all the material needed for a good prompt to make a good change.
In an ideal world, the AI system could then save all these details and when the change is made, guide you through the UX again. And you can check if the change was made as you wanted.
So kinda like AI flavored manual UX testing where you click around and record your findings.
A do-what-I-mean interface using pseudocode seems like an interesting idea to explore, but perhaps it should be automatically reformatted by the AI to conform to some grammar? The idea would be a documentation standard (like Markdown), not an actual programming language.
Sometimes you might also want examples and then BDD testing software (like Yadda) might make sense?
I like the direction of capturing the human intent as a durable artifact, but I dislike how you've gotten there.
Let's look at your fizzbuzz example. Unfortunately, if you wanted to have the agent implement fizzbuzz for you, it looks like, in your example, you would have to already know how to effectively write fizzbuzz. Specifically, you call out the use of the modulo.
In your prompt, for the traditional agentic development path, you already declared the intent. There is some imperative language in there, sure, "Create a function that ...", but also there is the declarative state, that doesn't require knowledge of specific programming syntax or semantics.
What I've relied on is a more formal location/syntax for acceptance criteria are in code. These are then used to generate tests, and implementations. It isn't perfect, and more investment is needed, but it starts getting at the root of the problem.
I've settled into a habit of asking codex to write down summary of key decisions in a ledger as I end a unit of work. It keeps iterating natural but maintains a system of record on decisions in the same repo. The "ledger" is the new code.
I believe these are called Architectural Decision Records. Matt Pocock's skills [0] make use of them. They're one of the more useful things I've gotten out them.
This approach reminds me of PDL (Program Design Language), described in Steve McConnell's excellent book Code Complete (1993). He recommended writing code using PDL pseudocode first. People can review your PDL before you write the code implementing the PDL, leaving the PDL as code comments.
When the project scales, the transformation of intent into such pseudocode becomes a big deal. Having the pseudocode as an intermediate level to check agents' artifacts is interesting media, but I couldn't see how this would actually work with Huzzah tbh.
I like the distinction between imperative and declarative styles, but I still use imperative chat sessions to work through what the declarative plan should look like. I feel like this approach loses that.
I think that this would be easy to criticize without interfacing with their underlying idea here.
It's cool that with a tool like this you don't NEED to get all aspects of your code finalized and ready. It's possible to be vague when you want to and specific when you need to.
I'm not sure if that itself would work well in practice, but the project is still quite cool nonetheless.
I think "the pseudocode is persisted alongside the generated code" just reinvented jira/linear tickets and PR descriptions. We have ways of using git and tracing the code write to the thought process behind it.
What about multi-file / larger changes? How would you express files being connected, imports, and exports? Or are you thinking the hz files are disposable per change?
The intention is for the files to persist, and I didn't mention it, but a core part of the system is that the editor persists source maps. So at any point in time, you can map any generated line back to the line of pseudocode that generated it.
I'll be looking into multi-file stuff soon - it's an interesting can of worms to think through.
I think the idea of having a human-written persistent document describing the operation of the code is a great idea. This document acts as the prompting interface instead of the chat window and changes can still be tracked. Surely something as simple as a skill.md can be made for such a setup, right?
I think the pseudocode style is a seperate axis to this setup.
What I find interesting about this + a random bucket of associations because I’ve fallen under the spell of Satan’s Lettuce:
Just a few days ago someone was talking about a machine - human patois.
This (your project) sits somewhere between Lean and BDD cucumber syntax.
At the same time Claude spits out phrases like “a container paying the price of -42px”.
Recently I was listening to a lecture about metaphor in poetry, the misconception that poems are riddles whereas we use metaphors all the time in our language because they convey the meaning more precisely.
It was a very nice post, at least I learned that I was not the only one in a vacuum in this regard. I will try Huzzah and share my views under this topic.
the endgame is a team whose git history is all generated commits, while the one file that actually captures intent is a terse text nobody thought to commit.
A good commit message is not a record of human intent, it's a record of changes in human intent. You can read a change log to see the evolution of a codebase, sure.
But before AI arrived on the scene, source code was a single artifact that directly expressed the intended behavior of a piece of software as it currently exists. After AI, the artifact is still there, but it's no longer the true record of human intent.
> Welcome to my Github! I'm a web engineer who's been building front-ends since 2009. Most of my work is either closed source or behind paywalls, but here is where I tinker on side projects in my spare time.
No need to dismiss the person - you can just say you don't like the approach
Writing fizzbuzz requires that you understand algo + you credit card, while agent requires only your credit card. I believe most of people will pick the 2nd one.
Yes for many non-technical people who are building stuff for the very first time, this is absolutely true. Natural language will always be easier for them. But experienced engineers are wanting to use AI for very complex codebases, and AI struggles significantly beyond a certain point.
Would need to try out in a complex project to have opinion. However I already see few problems.
Slower development due this loop of generating code from you mini spec. I would snap and start writing code at one moment.
Different agent different code, off by one errors that agent deducts itself, and you miss because spec doesn't force you to write correct code. Those might be caught by unit tests, but then why not generate code based on tests, as uncle Bob does...
curious if you’ve tried Kiro or spec-driven development? that seems like it would solve at least some of the issues you raised with agent based development, albeit in a different way without the emphasis on pseudo code
yeah in the blog post I should have outlined the things I first tried to solve the problem. I tried a variant of gherkin rules, using them for the behavioral spec for a project. It works reasonably well, but without a direct source map from the rules to the code, you still end up with a very difficult-to-understand codebase.
not sure if the hz file artifact is needed, you can enter pseudocode directly into chat or even on an existing code file and with minor comment agents will be able to work with it. i write this type of pseudocode to existing code files often to great results.
Yes, I also wrote this kind of pseudocode. But to make full use of it, you'd want to persist it, and to maintain a map between the lines of your pseudocode and the lines of your real code. It's not practical to do this manually, you'd want these mechanics built into your editing system.
Definitely an approach worth exploring! I actually started to look into semi formal spec language like Quint because I wanted something more structured then prose, so I feel like this goes into the right direction.
Another LLM could use the pseudocode to generate black box test cases without access to the generated code. How to define the API between tests and the implementation would require some more work.
It takes a great deal of bravery to publish work like this. I see the comments are filled with people who have never used an agent to develop code and are quite sure this is the dumbest thing they've ever seen.
You are like that bad manager who will hire 10x super engineer and then stifle their work with useless policies and meetings and team building activities “to make sure the productivity are better and work is consistent and team harmony is there!!”. The whole idea of using multi billion weight model is you don’t restrict it with your limited knowledge, you only guide it and review after to make sure it aligns with your goals, definitely the model will bring new tools or tricks you never knew it existed let alone they are useful, just like that super engineer doing things on their own approach, you only guide and align to the goal, here in building your software and in the company to your business goals.
I wrote this but as a compiler. It was ~2 years ago and local models have gotten WAY better; I was having too many issues with adherence (syntax errors, etc) and dropped it.
The compiler comes with a model embedded or can use an external model. It uses Cosmopolitan Libc and can zip things together into one binary. I will take some time to dust it off and share it.
But the idea was basically, you have your natural language source files or a one-shot prompt and it "compiles" them into a single, shareable fat binary that works across all popular platforms and architectures.
It was pretty fun to use with remote frontier models but the local model story simply wasn't good enough at the time for me to feel proud releasing it. I think that's probably changed now and passable results can be had even with small modern 7B/14B models.
I just use a lot of folders, like folder for ever class and manager class with it and anything else. So its kind of organized by folders like plugins. Much easier to reason about. The biggest problem is the central class that glues everything is now 30 thousand lines, but its mostly repetitive delegation, init update, draw, delete. Still should be some nicer solution than having a huge class in center.
You seem to be conflating two things: how to prompt, and how to share sessions. You can already use pseudo-code today if you want to. As for sharing, you can commit (a link to) it, use `git notes` (as I do), or a service like entire.io.
I think you should work on your differentiation. The session management stuff is the greater concern, in my opinion; pseudo code is not a novelty.
Help me understand - what do you mean be "share sessions"? And yes you can definitely use pseudo code today - that in and of itself is not a novelty at all. The specific novelty is the fact that the editor assumes two equivalent sources - your pseudocode which acts as a prompt, and the source code generated from that prompt. The editor also provides a source map for the two, so that as a codebase grows in size and complexity, it's trivial to link a specific section of code back to a human's written intent.
I see, thank you. So the difference in this case is that you're effectively writing very terse documentation. If I as a human interpreter want to understand why a range of code came into existence, I'm very unlikely to want to read another engineer's session. I'd have no way of knowing how far back into the session to read - some conversations can be very complicated. It also requires persisting everyone's sessions, which I'm sure is a pretty pricey problem. The truth is that for a given chat session, the messages themselves aren't extremely valuable, because they're part of the working development of the code.
What I'm after is a condensed distillation of human intent using semi-formal symbolic language, which should be vastly easier to read and understand for engineers and teams.
A really nice rig, which you can use in an existing repo, is to have ollama and aider simply log everything that happens in the session, through tee, into a log directory which you do - indeed - check into the repo.
> almost exclusively with coding agents
Do your own commits too (don't just let the ML do them), and in those commits, keep your prompts.
Learn to use your AI skills with succinct and calculated, forthright projection.
Which is to say, it is your own personal set of words now which define your control over your computer.
The words are tools. But what are your methods?
> .. tedious to write full sentences for every change I want .. interaction paradigm ..
Your own command of your speaking/thinking language can be extended as far and as wide, now, as you can possibly imagine. In fact, you must control AI/ML with imagination now, in multiple ways.
One of those ways is to iterate on expansion of your own ontology. There has to be an input from the AI before an adequate human output can send the AI directly at the heart of it. This improvement loop is on you. Get smarter with the loop.
Well, I get this by checking all my aider logs into a submodule of my main source tree. All my prompts, all the happy little mistakes and bright, shiny things, commit by commit. Sure, the logs grow and grow, but you know what .. I learn a hell of a lot by reading them.
Time-stamped. So, nice graphs if I wanted them, one of these days we'll do it, me and the AI.
The commit point for where I cut the exhaustion between me and the immense power of the AI/ML tooling, is when there is a new build, and I have tested it, personally.
I get exhausted if there is no delivery factor, to me personally, from whatever method I'm wrangling the tools with. Like if I really push too hard on the prompt, things get gnarly.
But, I've been here before over the decades, there are methods.
Even in the AI/ML age .. tooling and methodology requires a discipline - what is true now more than ever is that if a method fails, the usual approach of building another tool is not necessarily the best approach.
Methods can be sharpened just like tools. But every tool carries a cognitive load.
The methods are there to make that load useful. Are you a user?
So then just do a build and run it. See if is worth it.
I think you’re probably missing why it’s exhausting. The problem is not writing English, it’s the rate of change. Programming is meditative, it is a thinking process, the code you output is an artifact of your thinking. Agent-based development… there is no thinking, no meditation, you’re delegating the thinking to a machine, you’re just barking what you want at it, incessantly, endlessly.
For businesses it makes sense to abandon programming in favor of delegating to agents that can do more in less time, but for programmers, it is a loss. Either be a programmer and code, or be a delegator and delegate, you aren’t going to make the life of a delegator suck any less by trying to trick yourself into thinking you’re programming.
Agree with programming is meditative but disagree that agent-based development means there is no thinking. Agent-based development means more thinking like a lower level manager. You spend more time making architecture decisions, making decisions on the user interface, trying to manage your time and your agents time to increase the amount of work produced in the same time, asking the agent about the code and making new decisions. For many people who went in programming thats not their strong suite and hence is really exhausting. Instead of living in the code you are managing the code and using a part of the brain you are not good at.
I would disagree that there is no thinking. I think a strong understanding of the fundamentals of coding are still wildly important to get good quality code, and a big part of that is thinking or reasoning through a particular problem. It’s just now we have a way of using common language in order for that to happen instead of having to learn or keep up with every new tool and framework in order to do so. The new programming language is just in your native tongue.
I’m not a full time dev, but I code quite a bit doing Systems and OPs stuff, but AI has opened up an entirely new world to me and it has expanded my ability to think through a problem. It’s the ultimate rubber ducky. I love to watch the reasoning process while I’m in opencode so I can interrupt if I see it going down a path that doesn’t make sense.
It’s opened another world to me that allows me to implement ideas I’ve had for years without the time to invest in the skills needed to even try the idea.
I think it’s just how you use the tool.
I don’t mean to imply that making things with these tools is lesser, or that it doesn’t require some skill, but it is fundamentally different to programming. I’m glad you’re able to bring new things to life with these tools, that’s a great thing :)
My broader philosophical take is that we, programmers, lived through a golden age where our skills used on our terms were some of the most valuable skills. The golden age is over, our skills aren’t useless, they can still be applied to making things with modern tools, but it is no longer on our terms, no longer programming, no longer the meditative thinking process it once was.
For non-programmers, this is their golden age, the reign of programmer tyranny is over.
"We're reinventing coding from first principles" /s
I think the reverse direction is more important: taking a massive complex problem/codebase and decomposing it to short pseudocode. Then you could edit the pseudocode and compile it back into the system.
That's the way software engineers working on large projects work anyway: you first gather context on the state of the system and read it at a level you can understand. Then you propose a change on the simplified representation, and then holistically update the machine-runnable format ("implementation").
I'd be interested in tools that formalize/automate this process more.
I'm working on a bidirectional version of this! The big challenge is keeping the various versions of the thing in sync through edits.
Clever! :)
Difficult! :(
I don't think it's particularly difficult, or clever. You can prompt your way into this with frontier models, especially if your codebase is designed for it from the ground up (architecture well factored, documented, tested, harnessable, so that it even has a pseudocode representation in the first place).
The biggest issue is you end up leaning heavily on the quality of the model. Lower fidelity models tend to make a mess and add tech debt that you must frequently repay with intentional cleanup passes from a higher quality model, or else the rate of useful progress will fall off a cliff. At least that's my experience.
As I see it, there's a bit of internal contradiction: your declared intent is to not write code, but you had to circle back to code (albeit more relaxed and vague) because human English is (compared to proglangs) imprecise. Pseudocode, however, is not far away from it, still not strict, and LLM is still a stochastic generator. So it will continue to randomly deviate from what you want it to do. I guess it could be an enhancement, but who knows, maybe in a year from now, you will get tired with pseudocode not being precise, and go back to writing code :wink:
I'm confused, it looks like you've just written a new terse language that now costs money to compile?
Afaik there's no language - the pseudocode can be written however you want. And the costing money to compile? If you're prompting an llm you're already doing that, just with prose instead of pseudocode. I'm not sure this approach is a good idea, but it might be - and imo it's worth trying :)
Yes, there's no language. And exactly - we're effectively already doing this, but with waaay more words.
> I'm not sure this approach is a good idea, but it might be
After the last year, I feel like this sentence could replace half my outbound emails.
I have to admit, I am unsure if this article was some sort of parody.
Technically speaking everything costs money to compile in the form of electricity. This is just...inefficient compilation.
I'm not sold on the pseudocode approach, but I agree with the declarative aspect. Declarative specs have become central to my process and I've built this tool to support it:
https://github.com/spekk-ai/spekk-cli
Rather than writing exhaustive specs, I preserve only the intent and what must be true as discrete assertions. This preserves the leverage you get from LLMs - anything it can reliably infer does not need to be specified. It also (mostly) separates intent from code or architecture decisions, which keeps specs flexible.
I’ve been thinking about something along these lines for some time. I really like the direction of this.
The challenge I see more broadly is we (as engineers now empowered by LLMs) are trying to find the right level of abstraction to operate in. Writing long form sentences and (sometime) reviewing the output feels too far away. But having an LLM work directly with you in an IDE feels too close to “the old way”.
Personally for me the approach here still feels a little too close to the lower level old way, but it’s better than the two approaches above.
Excited to see where you take it!
Right level of abstraction is a good way of putting it. It's basically like creating a custom DSL, but flexibility of LLMs allow the DSL to be ad-hoc.
At what point will you need formal rigid syntax? Or is not having rigid syntax the point? If the latter, how much "informational noise" or ambiguity can you inject before the "DSL compiler" gets confused?
Scaling is another bit. Convertible Psuedocode a great pattern for writing functions, but is it useful for writing modules? If you're writing a paragraph to change behavior of a function, you're underutilizing LLMs. Paragraphs are best for spec'ing modules, and the LLMs already fill in the blanks. Not sure if it would be faster to psuedocode the entire module (although maybe just the interface would be a sweet spot...)
Yeah exactly. The module/directory level is currently untested. I'm working on a desktop version so I can talk to a file system, and then I'll be able to explore those problems.
My guess is that if you simply write `use some_fn from $repo/some/path`, the LLM _should_ be smart enough to infer in most cases. But we'll have to see how reliable that is.
Are there examples of how this would work when you need the pseudocode to reference abstract application concepts?
I'm not totally convinced this is a useful way to express something like "Change the data flow so that we bulk query from the DB upfront and pass it down to all callsites"
I think its an interesting approach, much more than most other new agent harnesses at least.
I guess you still need the chat to discuss with the AI? For example, ask it to compare solution A and B, or to explain how to do X. A bit like you can use plan mode today. Then given the result, you can write the hz file (or even have an agent write it).
But I wonder how it works on a more complicated project than fizzbuzz. Can I suggest you use Huzzah to develop itself, and then share the hz file(s)? That will show both how it works on a more complicated project, and something that is developing over time.
Dumb question:
Why not just put an instruction into your favorite harness’ system prompt: “If I give you pseudo code, spell out my intent, and then write and test it in real code.”
Not a dumb question - you can totally do this. I was doing this for a while. Before Claude Code really took off, this was my primary way to use Cursor. I'd write some pseudocode, highlight it, and just write to the AI "make it real". Works like a charm.
The issue is that with very large or complex codebases, you tend to forget what was AI generated and what was written by a human. And it's also extremely tedious and difficult to read AI generated code. So if you want to _understand_ a complex bit of code, the natural tendency is to ask an agent to summarize it for you. This can work but also has lots of problems.
What you really want is a system that persists both your written intent, and the actual source code. And you want to provide a source map between them, so that you can understand which bits of human pseudocode are responsible for which bits of generated code.
The real value is in persisting your expressed intent.
I think there's a lot to like about this approach, especially persisting my intent.
I think it will be interesting to see how this plays out when it comes time to debug.
At that time, someone else may be reading my pseudo code and implicitly assuming that the code was translated correctly. If the code wasn't translated correctly, wouldn't the human who naturally assumes it was miss the bug every time?
Huzzah would benefit from having a guard identify pseudo code with two potential interpretations and ask the human to clarify so the reliability of the interpretation does not suffer.
Okay, but then why not make this a new sort of fuzzy language, rather than building a new app with it's own UI?
I think having to open a web interface is a big entry barrier.
Imagine if those pseudocode files could live in your codebase, and the CLI tool would just “build” the actual code, with sourcemaps. You could edit the code in your favorite editor and run “build” commands in your favorite shell.
(TBH, I haven't looked deeply inside the repo and maybe it's exactly how it works. I just saw that demo and readme tell you to open a http://localhost:5173 as if you can use it only via custom UI.)
I'm not sure how to do syntax highlighting for this pseudocode in any IDE, but you could start with supporting something like Alabaster theme, the whole point of which is to highlight as little as possible.
I say this because I really think that if the setup was simpler lots of people would use it. It's a kind of concept that when you read about it, you think “Wait, how did I not came up with this”. Finally some interesting concept in this endless stream of skills, MCPs, loops etc.
I really feel the pain here, I have myself tried things ol these lines... I will give Huzzah it a try.
My concern, however, is that all of these options might ultimately be slower than just prompting.
I mean, at this point, another option would be to just go back to actually writing the code ourselves, like we did back then in 2024 ??
I'm surprised it wasn't mentioned yet, but it seems pretty similar in concept to codespeak https://news.ycombinator.com/item?id=47350931
Though catching back up on that project- it seems it's evolved pretty substantially, becoming much higher level than the initial pseudocode driven version I remember
I understand your approach and applaud it. I have been doing two things that keep me doing the parts I love. Instead of pseudo code I write in a simple managed language like JavaScript or Python. My instructions to the agent is simple. Code gets no comments. It is intentionally brief and for me at least understandable. Second. I have a document for each code file that holds the an enumerated list of rules used to develop the file - The comments if you will but in a format I can deal with line by line, just like the code. This is substantially more rewarding for me as I change both the code and the document and limit terminal interactions to must-see/do stuff.
I think the way I would want to work with AI for web apps would be like this:
You install a fancy chrome extension or custom browser.
You go through the app on this browser. You notice something you want to change. You can then submit a prompt via this extension saying the change you want.
The trick is, the chrome extension has been following your movements through the app. This way the chrome extension can generate a lot of data the AI can use for a good prompt. I.e. The extension can get a screenshot of where you are in the app and all the pages you went through to get there. The extension can get the console logs and traces and stuff.
So with all this, the AI system gets all the material needed for a good prompt to make a good change.
In an ideal world, the AI system could then save all these details and when the change is made, guide you through the UX again. And you can check if the change was made as you wanted.
So kinda like AI flavored manual UX testing where you click around and record your findings.
A do-what-I-mean interface using pseudocode seems like an interesting idea to explore, but perhaps it should be automatically reformatted by the AI to conform to some grammar? The idea would be a documentation standard (like Markdown), not an actual programming language.
Sometimes you might also want examples and then BDD testing software (like Yadda) might make sense?
I like the direction of capturing the human intent as a durable artifact, but I dislike how you've gotten there.
Let's look at your fizzbuzz example. Unfortunately, if you wanted to have the agent implement fizzbuzz for you, it looks like, in your example, you would have to already know how to effectively write fizzbuzz. Specifically, you call out the use of the modulo.
In your prompt, for the traditional agentic development path, you already declared the intent. There is some imperative language in there, sure, "Create a function that ...", but also there is the declarative state, that doesn't require knowledge of specific programming syntax or semantics.
What I've relied on is a more formal location/syntax for acceptance criteria are in code. These are then used to generate tests, and implementations. It isn't perfect, and more investment is needed, but it starts getting at the root of the problem.
I've settled into a habit of asking codex to write down summary of key decisions in a ledger as I end a unit of work. It keeps iterating natural but maintains a system of record on decisions in the same repo. The "ledger" is the new code.
I believe these are called Architectural Decision Records. Matt Pocock's skills [0] make use of them. They're one of the more useful things I've gotten out them.
[0] https://github.com/mattpocock/skills
This approach reminds me of PDL (Program Design Language), described in Steve McConnell's excellent book Code Complete (1993). He recommended writing code using PDL pseudocode first. People can review your PDL before you write the code implementing the PDL, leaving the PDL as code comments.
https://en.wikipedia.org/wiki/Program_Design_Language
https://codecourse.sourceforge.net/materials/Code-Complete-A...
Isn't this just spec-driven development in a different language?
When the project scales, the transformation of intent into such pseudocode becomes a big deal. Having the pseudocode as an intermediate level to check agents' artifacts is interesting media, but I couldn't see how this would actually work with Huzzah tbh.
I like the distinction between imperative and declarative styles, but I still use imperative chat sessions to work through what the declarative plan should look like. I feel like this approach loses that.
this is a question whole software industry is trying to solve. "how can we make sense of the ai generated codebase"
what you did is spec-driven development, instead of use-cases and requirements you have pseudo-code.
spec-driven did not work in my case, likely yours suffer the same "issue of walls of text no one wants to read".
You could write that pseudocode as a prompt for the agent and get the same result. Use plan mode to understand what agent wants to do.
Am i missing anything?
I think that this would be easy to criticize without interfacing with their underlying idea here.
It's cool that with a tool like this you don't NEED to get all aspects of your code finalized and ready. It's possible to be vague when you want to and specific when you need to.
I'm not sure if that itself would work well in practice, but the project is still quite cool nonetheless.
I think "the pseudocode is persisted alongside the generated code" just reinvented jira/linear tickets and PR descriptions. We have ways of using git and tracing the code write to the thought process behind it.
Hmm. Interesting idea.
What about multi-file / larger changes? How would you express files being connected, imports, and exports? Or are you thinking the hz files are disposable per change?
The intention is for the files to persist, and I didn't mention it, but a core part of the system is that the editor persists source maps. So at any point in time, you can map any generated line back to the line of pseudocode that generated it.
I'll be looking into multi-file stuff soon - it's an interesting can of worms to think through.
Having hz files also opens a really interesting idea of using them as a form of static analysis and CI validation.
I think the idea of having a human-written persistent document describing the operation of the code is a great idea. This document acts as the prompting interface instead of the chat window and changes can still be tracked. Surely something as simple as a skill.md can be made for such a setup, right? I think the pseudocode style is a seperate axis to this setup.
What I find interesting about this + a random bucket of associations because I’ve fallen under the spell of Satan’s Lettuce:
Just a few days ago someone was talking about a machine - human patois.
This (your project) sits somewhere between Lean and BDD cucumber syntax.
At the same time Claude spits out phrases like “a container paying the price of -42px”.
Recently I was listening to a lecture about metaphor in poetry, the misconception that poems are riddles whereas we use metaphors all the time in our language because they convey the meaning more precisely.
If the pseudocode is precise, what you want is a compiler. Otherwise the LLM is still making decisions for you.
It was a very nice post, at least I learned that I was not the only one in a vacuum in this regard. I will try Huzzah and share my views under this topic.
the endgame is a team whose git history is all generated commits, while the one file that actually captures intent is a terse text nobody thought to commit.
Are you using Huzzah to development Huzzah? :)
Interesting idea! I wonder if, after some iteration, a variation on this could help curb some of the LLM spaghetti mess
> There’s no reliable record of human intent.
Every engineer I have ever mentored got a lesson on how to write a good commit message that included this. This is exactly that.
Further Huzzah from skimming it over seems to be re-inventing documenting your code.
Together I can only surmise that the author is new out of school or has simply not yet worked on a team with good coding practices.
A good commit message is not a record of human intent, it's a record of changes in human intent. You can read a change log to see the evolution of a codebase, sure.
But before AI arrived on the scene, source code was a single artifact that directly expressed the intended behavior of a piece of software as it currently exists. After AI, the artifact is still there, but it's no longer the true record of human intent.
Two clicks from the article:
> Welcome to my Github! I'm a web engineer who's been building front-ends since 2009. Most of my work is either closed source or behind paywalls, but here is where I tinker on side projects in my spare time.
No need to dismiss the person - you can just say you don't like the approach
Very insightful. The idea of using pseudocode is clever, and the persistence+correlation layer idea is great.
Writing fizzbuzz requires that you understand algo + you credit card, while agent requires only your credit card. I believe most of people will pick the 2nd one.
Yes for many non-technical people who are building stuff for the very first time, this is absolutely true. Natural language will always be easier for them. But experienced engineers are wanting to use AI for very complex codebases, and AI struggles significantly beyond a certain point.
Would need to try out in a complex project to have opinion. However I already see few problems. Slower development due this loop of generating code from you mini spec. I would snap and start writing code at one moment. Different agent different code, off by one errors that agent deducts itself, and you miss because spec doesn't force you to write correct code. Those might be caught by unit tests, but then why not generate code based on tests, as uncle Bob does...
With scale problems arise.
Are we supposed to be able to read the examples with our eyes? It looks like black text on a very dark grey background on my iPhone.
EDIT: same on Firefox on my Mac (macOS Ventura).
Pushing a fix now - thanks for letting me know.
edit: fixed
curious if you’ve tried Kiro or spec-driven development? that seems like it would solve at least some of the issues you raised with agent based development, albeit in a different way without the emphasis on pseudo code
yeah in the blog post I should have outlined the things I first tried to solve the problem. I tried a variant of gherkin rules, using them for the behavioral spec for a project. It works reasonably well, but without a direct source map from the rules to the code, you still end up with a very difficult-to-understand codebase.
This is basically a compiler, but we’re moving up a layer of abstraction.
not sure if the hz file artifact is needed, you can enter pseudocode directly into chat or even on an existing code file and with minor comment agents will be able to work with it. i write this type of pseudocode to existing code files often to great results.
Yes, I also wrote this kind of pseudocode. But to make full use of it, you'd want to persist it, and to maintain a map between the lines of your pseudocode and the lines of your real code. It's not practical to do this manually, you'd want these mechanics built into your editing system.
Terse pseudo code > verbose prose
Coding Encoding Think about the terms
Definitely an approach worth exploring! I actually started to look into semi formal spec language like Quint because I wanted something more structured then prose, so I feel like this goes into the right direction.
Another LLM could use the pseudocode to generate black box test cases without access to the generated code. How to define the API between tests and the implementation would require some more work.
Invented New coding language that transpile to other coding languages and saying it novel approach.
I'd call this one Micropilot.
As in micromanagement.
It takes a great deal of bravery to publish work like this. I see the comments are filled with people who have never used an agent to develop code and are quite sure this is the dumbest thing they've ever seen.
Nice work.
You are like that bad manager who will hire 10x super engineer and then stifle their work with useless policies and meetings and team building activities “to make sure the productivity are better and work is consistent and team harmony is there!!”. The whole idea of using multi billion weight model is you don’t restrict it with your limited knowledge, you only guide it and review after to make sure it aligns with your goals, definitely the model will bring new tools or tricks you never knew it existed let alone they are useful, just like that super engineer doing things on their own approach, you only guide and align to the goal, here in building your software and in the company to your business goals.
Nice work!
I wrote this but as a compiler. It was ~2 years ago and local models have gotten WAY better; I was having too many issues with adherence (syntax errors, etc) and dropped it.
The compiler comes with a model embedded or can use an external model. It uses Cosmopolitan Libc and can zip things together into one binary. I will take some time to dust it off and share it.
But the idea was basically, you have your natural language source files or a one-shot prompt and it "compiles" them into a single, shareable fat binary that works across all popular platforms and architectures.
It was pretty fun to use with remote frontier models but the local model story simply wasn't good enough at the time for me to feel proud releasing it. I think that's probably changed now and passable results can be had even with small modern 7B/14B models.
I just use a lot of folders, like folder for ever class and manager class with it and anything else. So its kind of organized by folders like plugins. Much easier to reason about. The biggest problem is the central class that glues everything is now 30 thousand lines, but its mostly repetitive delegation, init update, draw, delete. Still should be some nicer solution than having a huge class in center.
You seem to be conflating two things: how to prompt, and how to share sessions. You can already use pseudo-code today if you want to. As for sharing, you can commit (a link to) it, use `git notes` (as I do), or a service like entire.io.
I think you should work on your differentiation. The session management stuff is the greater concern, in my opinion; pseudo code is not a novelty.
Help me understand - what do you mean be "share sessions"? And yes you can definitely use pseudo code today - that in and of itself is not a novelty at all. The specific novelty is the fact that the editor assumes two equivalent sources - your pseudocode which acts as a prompt, and the source code generated from that prompt. The editor also provides a source map for the two, so that as a codebase grows in size and complexity, it's trivial to link a specific section of code back to a human's written intent.
Sharing sessions means providing full visibility into what you did with the agent to the team. See https://entire.io/ or https://usegitai.com/
You can already retrieve the session associated with a given line of code.
I see, thank you. So the difference in this case is that you're effectively writing very terse documentation. If I as a human interpreter want to understand why a range of code came into existence, I'm very unlikely to want to read another engineer's session. I'd have no way of knowing how far back into the session to read - some conversations can be very complicated. It also requires persisting everyone's sessions, which I'm sure is a pretty pricey problem. The truth is that for a given chat session, the messages themselves aren't extremely valuable, because they're part of the working development of the code.
What I'm after is a condensed distillation of human intent using semi-formal symbolic language, which should be vastly easier to read and understand for engineers and teams.
> utterly exhausted
Keep your toolchain as simple as possible.
A really nice rig, which you can use in an existing repo, is to have ollama and aider simply log everything that happens in the session, through tee, into a log directory which you do - indeed - check into the repo.
> almost exclusively with coding agents
Do your own commits too (don't just let the ML do them), and in those commits, keep your prompts.
Learn to use your AI skills with succinct and calculated, forthright projection.
Which is to say, it is your own personal set of words now which define your control over your computer.
The words are tools. But what are your methods?
> .. tedious to write full sentences for every change I want .. interaction paradigm ..
Your own command of your speaking/thinking language can be extended as far and as wide, now, as you can possibly imagine. In fact, you must control AI/ML with imagination now, in multiple ways.
One of those ways is to iterate on expansion of your own ontology. There has to be an input from the AI before an adequate human output can send the AI directly at the heart of it. This improvement loop is on you. Get smarter with the loop.
> pseudo-code -> sync -> record of intent
[1] "Idea -> Description -> Result -> Build -> [human] (use)"
Well, I get this by checking all my aider logs into a submodule of my main source tree. All my prompts, all the happy little mistakes and bright, shiny things, commit by commit. Sure, the logs grow and grow, but you know what .. I learn a hell of a lot by reading them.
Time-stamped. So, nice graphs if I wanted them, one of these days we'll do it, me and the AI.
The commit point for where I cut the exhaustion between me and the immense power of the AI/ML tooling, is when there is a new build, and I have tested it, personally.
I get exhausted if there is no delivery factor, to me personally, from whatever method I'm wrangling the tools with. Like if I really push too hard on the prompt, things get gnarly.
But, I've been here before over the decades, there are methods.
Even in the AI/ML age .. tooling and methodology requires a discipline - what is true now more than ever is that if a method fails, the usual approach of building another tool is not necessarily the best approach.
Methods can be sharpened just like tools. But every tool carries a cognitive load.
The methods are there to make that load useful. Are you a user?
So then just do a build and run it. See if is worth it.
Goto [1].