For the past few months, my collaborator Ismael Faro and I have been building a Python framework for creating self-evolving AI agent systems. It was powerful, with a smart library, an agent bus, and tools for evolution. But it had a problem: it was becoming incredibly complex. Even using AI coding agents to help improve the framework felt slow and cumbersome.
While using Claude Code to work on this, I had a realization. The LLM was so good at understanding and manipulating the project structure that the Python code itself was starting to feel like unnecessary boilerplate.
So, as an experiment, I tried to see what the absolute minimum viable agent framework would look like. What if I threw out all the Python and just kept the core concepts, but defined them in simple markdown?
It worked. Surprisingly well.
I'm sharing the result today. This is the framework-core. It's an entire agentic framework in just 3 markdown files:
https://github.com/EvolvingAgentsLabs/framework-core
SystemAgent.md: The "kernel" prompt that tells the LLM how to plan, execute, and learn.
SmartLibrary.md: A markdown list that acts as a "package manager" for other markdown-defined tools.
SmartMemory.md: An append-only log where the agent records its experiences to improve over time.
The "runtime" is just a powerful LLM (like Claude in a VSCode project). You give it a high-level goal, and it uses these three files to orchestrate a solution.
I then tried to use this for non-coding, white-collar tasks—legal analysis, marketing campaign generation—and it worked there too. The agent was able to identify missing capabilities (like a "RiskAnalysisTool") and write the markdown for the new tool itself before using it.
This led me down a rabbit hole, and I ended up building a full-fledged OS simulation on top of this core concept, which we're calling LLMUNIX. It has a virtual file system, a process manager, and a command interpreter, all defined in markdown. You can see that more advanced project here:
https://github.com/EvolvingAgentsLabs/llmunix
This is all "alpha" and a space for experimentation under our new Evolving Agents Labs organization. I'm sharing this because the simplicity of the approach surprised me. It feels like it democratizes the ability to create complex agentic systems. If you can write a to-do list, you can design an AI agent.
I'd love to get the HN community's feedback. Is this a novelty, or is there a real future in treating markdown as a programming language for LLMs? What are the limits I'm not seeing yet?
Thanks for checking it out.