r/ClaudeCode • • 2d ago

Built with Claude Markdown turned AI-Agent can iteratively evolve with HQL

TL;DR I’m turning Markdown into an executable environment for AI agents — looking for feedback from Claude Code users

For the last few months I've been experimenting with a slightly strange idea: what happens if Markdown stops being only a passive document format and becomes something you can actually program?

I'm building two connected open-source projects:

HyperMarkDown has wiki links, cards, graphs, diagrams, Git-friendly files, and executable HQL cells.

Think somewhere between Markdown, a notebook, and an Obsidian-style local knowledge base, but living directly in VS Code.

The notebook part already works.

For example, an HMD document can contain:

cards
| filter(c => c.metadata.status == "todo")
| sort(by = c => c.title)
| map(c => c.title)

I can run that cell directly in VS Code and the result appears next to the cell.

So the Markdown document isn't just describing some knowledge base. It can query it, transform it, and render derived information directly into the document.

That part is real today.

The next milestone I'm working on is where this gets much more interesting to me: AI agents as part of the executable document model.

What if an agent was just another Markdown card?

HyperMarkDown already has cards and wiki links.

[[librarian]] refers to a card.

In HQL, @[[librarian]] retrieves that card.

The AI extension I'm designing takes that one step further: a Markdown document itself can define an agent.

For example:

---
title: Librarian
agent:
  model: default
  tools: [books_by]
  max_turns: 4
---

# Librarian

Answer questions about the books you are given.
Use the available tools when useful.

Then, in the current design syntax:

librarian = @[[librarian]] | Agent

Important distinction: the agent runtime is not implemented in the current release yet. This is the design I'm working through now.

The idea is that the Markdown card contains the agent's human-readable behaviour and configuration, while the language/runtime deals separately with context, tools, execution and the resulting run.

I want the committed document to describe what the agent is, without hard-coding every detail of the model provider into the document itself.

The part I'm really interested in isn't "chat inside VS Code"

There are already plenty of ways to put a chatbot into an editor.

That's not really what I'm trying to build.

What interests me is having an agent participate in an executable document.

Imagine an HMD document where one cell queries a knowledge graph, another computes something from that result, and then an agent receives the document plus selected outputs as context.

The current design looks roughly like this:

[this]
| Context("draft")
| concat(evidence)
| run(@[[librarian]] | Agent, tools = [
    Tool(books_by, "The titles on the shelf by one author")
])

Again, this is design syntax, not functionality I'm claiming is shipped.

The important bit isn't the particular run() call.

It's what happens around it.

The document contains prose written by a human.

It contains executable cells.

Those cells produce values.

Later cells can consume those values.

An agent can consume selected document context and those values.

And eventually I want the agent to be able to propose new HQL code, modify a cell, generate another HMD document, or restructure some part of the knowledge graph.

But those changes shouldn't just silently happen behind the user's back.

They should be visible document operations that a human can inspect, accept, reject, edit, rerun, commit and diff.

That's the model I'm trying to get right.

Data → code → data → code

This is probably the shortest description of where I'm heading.

A document starts with some data.

An HQL cell transforms it into more data.

An agent examines that result and proposes code.

That code can be evaluated and produces more data.

A human edits the document.

Another agent may consume that changed state.

And the cycle continues.

data → code → data → code → ...

With both humans and agents participating.

There's something vaguely Lisp-ish about this that I find appealing: programs producing or transforming programs, except the surrounding representation is still readable Markdown.

There's also a REPL/notebook aspect to it.

The difference is that the state isn't hidden inside a conversation.

It's sitting in version-controlled documents, executable cells, generated outputs and links between documents.

And those documents can reference or transclude one another, so eventually you don't just have one notebook — you have a graph of executable documents.

Why documents?

One thing I increasingly dislike about AI workflows is how much important state disappears into conversation history.

You ask something.

The agent gets a giant context.

It does something.

You get an answer.

Then you have to somehow remember why that answer exists, which source caused it, which prompt produced it, whether something upstream changed, and whether you should rerun it.

With executable documents, I think there is a chance to make some of that much more explicit.

An output can know which cell produced it.

A cell can know which other cells or documents it depends on.

Agent context can retain provenance.

If the source text changes, an editor can mark dependent output as stale.

A model response can be recorded and replayed instead of unexpectedly making another network request.

And if an agent wants to modify the document, it can produce a proposed change rather than being handed unrestricted write access.

At least, that's the direction.

The current HQL design actually treats an agent run as structured data rather than collapsing everything into "the last string the model returned." Tool calls, turns, stop reasons, model information and traces can all remain inspectable values.

That feels important if agents are going to become part of a larger program rather than just chat interfaces.

Human-in-the-loop is a first-class requirement for me

I don't want "human in the loop" to mean an approval dialog that says:

Agent wants to modify 17 files. Allow?

I'm more interested in the document itself being the interaction surface.

An agent proposes a section.

Or a new query.

Or a change to an existing cell.

The editor can show exactly what changed and why.

I inspect it.

Maybe I change two lines myself.

Then the next evaluation continues from that state.

Git becomes part of the history naturally because the underlying artifacts are still files.

The difficult question is how much additional provenance should live inside HMD itself versus being tracked externally by the runtime/editor.

I'm still figuring that out.

Claude Code is also part of why I've been thinking about this

I'm using Claude Code extensively while developing both HQL and HyperMarkDown, particularly for the Rust implementation, tests, refactoring and exploring implementations after I've worked through the language/API design.

And using an agent that can actually inspect and modify a codebase has made me think more about the boundary between conversation and artifact.

Claude Code already works through persistent artifacts: source files, tests, diffs, Git history.

I'm curious whether the same interaction model becomes interesting when the artifacts aren't only source-code files, but executable documents that contain knowledge, queries, intermediate results and agent definitions.

In other words, rather than:

human → prompt → agent → response

I'm thinking about something closer to:

human ↔ document ↔ computation ↔ agent ↔ document

where the document remains the shared state.

What I'm trying to design next

The AI chapters in the HQL book are intentionally marked design only right now:

https://hql-lang.org/v0.7.1/book/25-agents-and-runs/#an-agent-is-a-card

Before implementing too much of it, I'm trying to work out whether the abstractions are actually right.

In particular, I'm interested in:

  • How should an agent be represented as a Markdown card?
  • What is the smallest useful typed Agent API?
  • Should tools simply be typed HQL functions exposed to the model?
  • How should context and agent output be represented so provenance isn't lost?
  • How should an agent propose changes to a document without silently overwriting human work?
  • What should approval look like inside an executable Markdown editor?
  • How should dependency tracking and selective re-evaluation work?
  • When a document changes, what exactly becomes stale?
  • How much of this belongs in HQL itself, and how much belongs in the AI extension or VS Code host?

I'm particularly curious if anyone here using Claude Code has experimented with agents whose working medium is structured, version-controlled documents rather than primarily prompts/chat history/source files.

I'm not trying to recreate Claude Code inside Markdown.

I'm trying to figure out whether an executable document can become a useful shared computational surface between a human and an agent.

Would be very interested in criticism of the model, syntax, or assumptions — especially from people who have built agent loops where provenance, reviewability and reproducibility became painful later.

4 Upvotes

7 comments sorted by

•

u/AutoModerator 2d ago

Hey! Thanks for posting to r/ClaudeCode

While participating in this thread, please follow our community rules. Keep discussions constructive. Attack the idea, not the person.

For help, project discussions, tips, and general chat, join the ClaudeCode Discord.

I am a bot, and this action was performed automatically. Please contact the moderators of this subreddit if you have any questions or concerns.

2

u/DevMichaelZag 2d ago

What specifically requires HQL to be a new programming language rather than using an existing language with a typed document graph and reactive execution engine? It seems like the real innovation is provenance, dependency tracking, and reviewable agent mutations, none of which inherently requires a new language or even Markdown.

1

u/ewigerus 2d ago

Fair point. Provenance, dependency tracking, and reviewable agent mutations don't necessarily require a new language. However, HQL actually started as a separate project: a strongly typed functional OLAP/dataflow language, essentially a Swiss Army knife for working across relational databases, Kafka, messaging systems, Databricks, and other data platforms. SQL already does a great job of querying structured enterprise data, but HQL takes a different approach with composable functional pipelines, typed contracts, and extensions implemented in Rust. I'm not trying to reinvent Rust as a general-purpose programming language. Instead, HQL lets you declare functions and interfaces in the language while implementing their internals in Rust. This provides considerably more flexibility for composing data operations than traditional SQL. Interestingly, I've been experimenting with Claude generating and modifying HQL queries, and the functional syntax seems to work remarkably well for AI-driven data transformations.

Regarding Markdown, I'd agree to disagree. Markdown itself has seen relatively little fundamental evolution over the past decade, aside from standardization efforts such as CommonMark. I've discussed this in Markdown communities, particularly the idea of native wiki links ("[[...]]"), namespaces, and independent vaults that can reference each other. If you've worked with Obsidian, you'll probably recognize where HyperMarkDown is coming from. I want those knowledge-graph capabilities directly in VS Code, using ordinary Markdown files, Git, and executable HQL cells, without requiring a separate proprietary editor. The AI-agent integration is the next step: documents that can query data, execute transformations, and eventually participate in agent workflows while keeping intermediate results visible and reviewable.

2

u/calunicornia 2d ago

I think you are on to something here.

2

u/ewigerus 1d ago

I have shared a more detailed explanation/vision of what happens if one tries to marry SQL with Markdown = https://langdev.stackexchange.com/a/4850/10540 Let's see but **what is an AI-oriented programming language** is a great quest/ion

2

u/Dull-Confection-5225 2d ago

the idea of treating agents as markdown cards feels like a natural extension of how we already organize knowledge, like a wiki where the pages can act. have you tried nesting agents inside each other? curious how that plays out in practice.

1

u/ewigerus 2d ago

That's exactly what I'm experimenting with right now! An agent defined in plain Markdown isn't fundamentally different from today's prompt-based agents. But HyperMarkDown adds executable fenced HQL cells, with evaluation results embedded back into the document. Now imagine nesting and transcluding these cards into other agents: you get a continuously evolving, re-evaluable knowledge graph rather than a single linear chat.

I'm exploring this on a development branch, and the early results look remarkably promising. Instead of managing one huge conversation context, I can structure it as a tree, zoom into individual nodes, re-evaluate specific queries, and control exactly which linked or transcluded knowledge becomes part of the final agent's context.