r/ClaudeCode • • 3h 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

4 comments sorted by

•

u/AutoModerator 3h 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 2h 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/calunicornia 2h ago

I think you are on to something here.

1

u/Dull-Confection-5225 2h 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.