Creator of lat.md here. There are two videos with me talking about lat in more detail [1] and less detail [2]. But I'm also working on a blog post exploring lat and its potential, stay tuned.
Neat idea. The biggest problem I've had with code knowledge graphs is they go stale immediately -- someone renames a package and nobody updates the graph. Having it as Markdown in the repo is clever because it just goes through normal PR review like everything else, and you get git blame for free. My concern is scale though. Once you have thousands of nodes the Markdown files themselves become a mess to navigate, and at that point you're basically recreating a database with extra steps. Would love to see how this compares to just pointing an agent at LSP output.
> My concern is scale though. Once you have thousands of nodes the Markdown files themselves become a mess to navigate
The agent will update the graph.
If you have thousands of nodes in md it means you have a highly non-trivial large code base and this is where lat will start saving you time - agents will navigate code much faster and you'll be reviewing semantic changes in lat in every diff, potentially suggesting the agents to alter the code or add more context to lat.
You still have to be engaged in maintaining your codebase, just at a higher level.
I would say that when you treat your Markdown as the authoritative source, I of course don't get it automated but that is my choice. It takes knowledge of the domain, but when you have deep specific knowledge that is worth so much more than automated updates. I use AI to get the initial MD but then I edit that. Sure it doesn't get auto updated, but I would never trust advice on the fly that got updated based on AI output on the internet.
I've been doing similar work since Claude code updated their "slash command"(later merge to skills), first 3-4 long content docs, gradually split to modular groups. I designed it for loading the docs based on what agent is actually doing. The maintenance part is honestly not that hard, for me, I created some CI jobs that diffs the docs against the codebase and flags drift handles of it.
The pattern works.
But I keep catching myself spending more time on how to organize context than on what the agent is actually supposed to accomplish.
Feels like the whole space has that problem right now.
This is one of the things that GitHub Spec Kit solves for me. The specify.plan step launches code exploration agents and builds itself the latest data model, migrations, etc etc. Really reduces the need to document stuff when the agent self discovers codebase needs.
Give Claude sqlite/supabase MCP, GitHub CLI, Linear CLI, Chrome or launch.json and it can really autonomously solve this.
Can you offer any insights how this compares to building an AST or RAG over your codebase? Several projects do that and it autoupdates on changes too. The agent does a wide sweep using AST/RAG search followed by drill down using an LSP. This sped up my search phase by 50%. How Will this project help me?
I think it's a great idea and I'm considering building this in lat too. Code embedding models can definitely speed up grepping further, but they still wouldn't help much when you have a business logic detail encoded across multiple complex files. With lat you'd have it documented in a paragraph of text + a few [[..]] links into your code.
good catch. Makes me wonder if we could feed the Agent with a repository of known vulnerability and security best practices to check against and get ride of most deps. Just ask _outloud_ so to speak.
The staleness problem mentioned here is real. For agentic systems, a markdown-based DAG of your codebase is more practical than a traditional graph because agents work within context windows. You can selectively load relevant parts without needing a complex query engine. The key is making updates low-friction -- maybe a pre-commit hook or CI job that refreshes stale nodes.
I definitely agree with the need for this. There's just too much to put into the agents file to keep from killing your context window right off the bat. Knowledge compression is going to be key.
I saw this a couple of days ago and I've been working on figuring out what the right workflows will be with it.
It's a useful idea: the agents.md torrent of info gets replaced with a thinner shim that tells the agent how to get more data about the system, as well as how to update that.
I suspect there's ways to shrink that context even more.
> I suspect there's ways to shrink that context even more.
Yeah, I'm experimenting with some ideas on that, like adding `lat agent` command to act as a subagent to search through lat and summarize related knowledge without polluting the parent's agent context.
We've been doing this with simple mkdocs for ages. My experience is that rendering the markdown to feel like public docs is important for getting humans to review and take it seriously. Otherwise it goes stale as soon as one dev on the project doesn't care.
I found having smaller structured markdowns in each folder explaining the space and classes within keeps Claude and Codex grounded even in a 10M+ LOC codebase of c/c++
managing agents.md is important, especially at scale. however I wonder how much of a measurable difference something like this makes? in theory, it's cool, but can you show me that it's actually performing better as compared to a large agents.md, nested agents.md, skills?
more general point being that we need to be methodical about the way we manage agent context. if lat.md shows a 10% broad improvement in agent perf in my repo, then I would certainly push for adoption. until then, vibes aren't enough
I'm working on a blog post and on benchmarks. Here [1] Armin suggested I take something like quickjs, built lat base for it, and compare side by side how, say, claude code works with lat vs. without.
I'm very early into this and need to build proper harness, but I can see sometimes lat allowing for up to 2x faster coding sessions. But the main benefit to me isn't speed, it's the fact that I can now review diffs faster and stay more engaged with the agent.
Very cool, interested to read more once you post! FWIW I've been building eval infras that does something adjacent/related — replaying real repo work against different agent configs, and measuring the agent's quality dimensions (pass/fail, but also human intent alignment, code review, etc.). If you want to compare notes on the harness design, or if having an independent eval of lat vs. no-lat on quickjs would be useful, happy to chat :)
Cool. I've been thinking about tools to help coding agents lately, and I've always wondered if I could do a better job than actual Claude Code / Codex. They can do the `rg`s and kick off multiple agents and the skills, etc, and I couldn't find a way to actually prove there's a ROI of using something like Agent Lattice. Curious to see the results!
One anecdote: I added lat to quickjs codebase and asked questions like "how does quickjs gc circular object graphs" and was able to get an answer in 12 seconds vs 2 minutes without lat. But take this with a grain of salt, I need better benchmark harness. Benchmarks are hard to do in general, for LLMs it's its own hell. :)
So the graph is human-maintained, and agents consume it and `lat check` is supposed to catch broken links and code-spec drift. How do you manage this in a multi-agent setup? Is it still a manual merge+fix conflicts situation? That's where I keep seeing the biggest issues with multi-agent setups
Curious if you've seen a difference between agents finding things through the graph structure vs just vector search over a docs directory. The section constraints and check validation seem like the real quality wins here, wondering how much the wiki link topology adds on top of that.
I have a vitepress package in most of my repos. It is a knowledge graph that also just happens to produce heat looking docs for humans when served over http. Agents are very happy to read the raw .md.
I was thinking the same. Especially now that Obsidian has a CLI to work with the vault.
The one thing I saw in the README is that lat has a format for source files to link back to the lat.md markdown, but I don't see why you couldn't just define an "// obs:wikilink" sort of format in your AGENTS.md
Because lat gives agents more tools and enforces the workflow.
Unlike obsidian, lat allows markdown files link into functions/structs/classes/etc too.
This saves agents time on grepping but also allows you to build better workflows with tests.
Test cases can be described as sections in `lat.md/` and marked with `require-code-mention: true`. Each spec then must be referenced by a `// @lat:` comment in test code. `lat check` flags any spec without a backlink, so you can review and maintain test coverage from the knowledge graph.
> Test specs with enforcement — test cases can be described as sections in lat.md/ and marked with require-code-mention: true. Each spec then must be referenced by a // @lat: comment in test code. lat check flags any spec without a backlink, so you can review and maintain test coverage from the knowledge graph.
if you mean this paragraph - imo that's still too hand-wavy compared to enforcement through generative tests for spec conformance.
The problem is that for any non-trivial question agents have to grep A LOT to understand the high-level logic expressed in code. In big projects grepping can take minutes some times. Lat short-circuits grepping significantly with `lat search` that agents happily use.
One of the things that I've been chewing on lately is the sync problem. Having a CI job that identifies places where the docs have drifted from the implementation seems pretty valuable.
> To check that a module’s docstrings are up-to-date by verifying that all interactive examples still work as documented.
To perform regression testing by verifying that interactive examples from a test file or a test object work as expected.
To write tutorial documentation for a package, liberally illustrated with input-output examples. Depending on whether the examples or the expository text are emphasized, this has the flavor of “literate testing” or “executable documentation”.
Creator of lat.md here. There are two videos with me talking about lat in more detail [1] and less detail [2]. But I'm also working on a blog post exploring lat and its potential, stay tuned.
AMA :)
[1] https://x.com/mitsuhiko/status/2037649308086902989?s=20
[2] https://www.youtube.com/watch?v=gIOtYnI-8_c
Neat idea. The biggest problem I've had with code knowledge graphs is they go stale immediately -- someone renames a package and nobody updates the graph. Having it as Markdown in the repo is clever because it just goes through normal PR review like everything else, and you get git blame for free. My concern is scale though. Once you have thousands of nodes the Markdown files themselves become a mess to navigate, and at that point you're basically recreating a database with extra steps. Would love to see how this compares to just pointing an agent at LSP output.
> My concern is scale though. Once you have thousands of nodes the Markdown files themselves become a mess to navigate
The agent will update the graph.
If you have thousands of nodes in md it means you have a highly non-trivial large code base and this is where lat will start saving you time - agents will navigate code much faster and you'll be reviewing semantic changes in lat in every diff, potentially suggesting the agents to alter the code or add more context to lat.
You still have to be engaged in maintaining your codebase, just at a higher level.
We all know this isn't for humans. It's for LLMs.
So better question is why there isn't a bootstrap to get your LLM to scaffold it out and assist in detailing it.
Adding a command to bootstrap lat for an existing code base is a good idea, I'll work on it.
Other than that the goal of lat is to make the agent use it and update it and it has tools to enforce that.
You’re replying to an LLM, too, fwiw.
GraphRAG is for LLMS... markdown is for humans.. humans that exist in the meantime
I would say that when you treat your Markdown as the authoritative source, I of course don't get it automated but that is my choice. It takes knowledge of the domain, but when you have deep specific knowledge that is worth so much more than automated updates. I use AI to get the initial MD but then I edit that. Sure it doesn't get auto updated, but I would never trust advice on the fly that got updated based on AI output on the internet.
I think you can have your workflow with lat and it might make it even nicer. Would love feedback from you.
yeah, AI for the skeleton + human for the "why" is probably the right split.
I've been doing similar work since Claude code updated their "slash command"(later merge to skills), first 3-4 long content docs, gradually split to modular groups. I designed it for loading the docs based on what agent is actually doing. The maintenance part is honestly not that hard, for me, I created some CI jobs that diffs the docs against the codebase and flags drift handles of it.
The pattern works.
But I keep catching myself spending more time on how to organize context than on what the agent is actually supposed to accomplish.
Feels like the whole space has that problem right now.
This is one of the things that GitHub Spec Kit solves for me. The specify.plan step launches code exploration agents and builds itself the latest data model, migrations, etc etc. Really reduces the need to document stuff when the agent self discovers codebase needs.
Give Claude sqlite/supabase MCP, GitHub CLI, Linear CLI, Chrome or launch.json and it can really autonomously solve this.
Can you offer any insights how this compares to building an AST or RAG over your codebase? Several projects do that and it autoupdates on changes too. The agent does a wide sweep using AST/RAG search followed by drill down using an LSP. This sped up my search phase by 50%. How Will this project help me?
I think it's a great idea and I'm considering building this in lat too. Code embedding models can definitely speed up grepping further, but they still wouldn't help much when you have a business logic detail encoded across multiple complex files. With lat you'd have it documented in a paragraph of text + a few [[..]] links into your code.
> "chalk": "^5.6.2",
security.md ist missing apparently.
Why would you even need chalk on modern Node.js? It can style natively now.
Good idea. :)
https://github.com/1st1/lat.md/commit/da819ddc9bf8f1a44f67f0...
good catch. Makes me wonder if we could feed the Agent with a repository of known vulnerability and security best practices to check against and get ride of most deps. Just ask _outloud_ so to speak.
Fixed
The staleness problem mentioned here is real. For agentic systems, a markdown-based DAG of your codebase is more practical than a traditional graph because agents work within context windows. You can selectively load relevant parts without needing a complex query engine. The key is making updates low-friction -- maybe a pre-commit hook or CI job that refreshes stale nodes.
This is what lat is doing. `lat init` would install hooks to double check that Claude/Codex/OpenCode update lat.md when they finish the work.
I definitely agree with the need for this. There's just too much to put into the agents file to keep from killing your context window right off the bat. Knowledge compression is going to be key.
I saw this a couple of days ago and I've been working on figuring out what the right workflows will be with it.
It's a useful idea: the agents.md torrent of info gets replaced with a thinner shim that tells the agent how to get more data about the system, as well as how to update that.
I suspect there's ways to shrink that context even more.
++
> I suspect there's ways to shrink that context even more.
Yeah, I'm experimenting with some ideas on that, like adding `lat agent` command to act as a subagent to search through lat and summarize related knowledge without polluting the parent's agent context.
We've been doing this with simple mkdocs for ages. My experience is that rendering the markdown to feel like public docs is important for getting humans to review and take it seriously. Otherwise it goes stale as soon as one dev on the project doesn't care.
I found having smaller structured markdowns in each folder explaining the space and classes within keeps Claude and Codex grounded even in a 10M+ LOC codebase of c/c++
I'm working on making lat hierarchical, e.g.
managing agents.md is important, especially at scale. however I wonder how much of a measurable difference something like this makes? in theory, it's cool, but can you show me that it's actually performing better as compared to a large agents.md, nested agents.md, skills?
more general point being that we need to be methodical about the way we manage agent context. if lat.md shows a 10% broad improvement in agent perf in my repo, then I would certainly push for adoption. until then, vibes aren't enough
I'm working on a blog post and on benchmarks. Here [1] Armin suggested I take something like quickjs, built lat base for it, and compare side by side how, say, claude code works with lat vs. without.
I'm very early into this and need to build proper harness, but I can see sometimes lat allowing for up to 2x faster coding sessions. But the main benefit to me isn't speed, it's the fact that I can now review diffs faster and stay more engaged with the agent.
[1] https://x.com/mitsuhiko/status/2037649308086902989?s=20
Very cool, interested to read more once you post! FWIW I've been building eval infras that does something adjacent/related — replaying real repo work against different agent configs, and measuring the agent's quality dimensions (pass/fail, but also human intent alignment, code review, etc.). If you want to compare notes on the harness design, or if having an independent eval of lat vs. no-lat on quickjs would be useful, happy to chat :)
So... does it work? Good description of what it does, but, does it actually make agents better, or use less tokens? What's the benchmark?
I'm working on a blog post about lat, stay tuned. Yes, it does work and I continue improving it.
Cool. I've been thinking about tools to help coding agents lately, and I've always wondered if I could do a better job than actual Claude Code / Codex. They can do the `rg`s and kick off multiple agents and the skills, etc, and I couldn't find a way to actually prove there's a ROI of using something like Agent Lattice. Curious to see the results!
One anecdote: I added lat to quickjs codebase and asked questions like "how does quickjs gc circular object graphs" and was able to get an answer in 12 seconds vs 2 minutes without lat. But take this with a grain of salt, I need better benchmark harness. Benchmarks are hard to do in general, for LLMs it's its own hell. :)
So the graph is human-maintained, and agents consume it and `lat check` is supposed to catch broken links and code-spec drift. How do you manage this in a multi-agent setup? Is it still a manual merge+fix conflicts situation? That's where I keep seeing the biggest issues with multi-agent setups
The graph can be human-maintained, but the preferred flow is to let agents update it.
Curious if you've seen a difference between agents finding things through the graph structure vs just vector search over a docs directory. The section constraints and check validation seem like the real quality wins here, wondering how much the wiki link topology adds on top of that.
I have a vitepress package in most of my repos. It is a knowledge graph that also just happens to produce heat looking docs for humans when served over http. Agents are very happy to read the raw .md.
At that point why not have an obsidian vault in your repo and get the Agent to write to it?
I was thinking the same. Especially now that Obsidian has a CLI to work with the vault.
The one thing I saw in the README is that lat has a format for source files to link back to the lat.md markdown, but I don't see why you couldn't just define an "// obs:wikilink" sort of format in your AGENTS.md
Because lat gives agents more tools and enforces the workflow.
Unlike obsidian, lat allows markdown files link into functions/structs/classes/etc too.
This saves agents time on grepping but also allows you to build better workflows with tests.
Test cases can be described as sections in `lat.md/` and marked with `require-code-mention: true`. Each spec then must be referenced by a `// @lat:` comment in test code. `lat check` flags any spec without a backlink, so you can review and maintain test coverage from the knowledge graph.
i've had a related question recently but it didn't get much traction
https://news.ycombinator.com/item?id=47543324
what's the point of markdown? there's nothing useful you can do with it other than handing it over to llm and getting some probabilistic response
Read this section, I've just updated it to be more clear, hopefully will answer your question:
https://github.com/1st1/lat.md?tab=readme-ov-file#the-idea
> Test specs with enforcement — test cases can be described as sections in lat.md/ and marked with require-code-mention: true. Each spec then must be referenced by a // @lat: comment in test code. lat check flags any spec without a backlink, so you can review and maintain test coverage from the knowledge graph.
if you mean this paragraph - imo that's still too hand-wavy compared to enforcement through generative tests for spec conformance.
tl;dr: One file, bad (gets too big for context)
So give you agent a whole obsidian
I am skeptical how that helps. Agents cant just grep in one big file if reading entire file is the problem.
The problem is that for any non-trivial question agents have to grep A LOT to understand the high-level logic expressed in code. In big projects grepping can take minutes some times. Lat short-circuits grepping significantly with `lat search` that agents happily use.
So we are reinventing the docs /*/*.md directory? /s I think this is a good idea just don’t really get why would you need a tool around it
One of the things that I've been chewing on lately is the sync problem. Having a CI job that identifies places where the docs have drifted from the implementation seems pretty valuable.
Python community figured this out in 2001: https://docs.python.org/3/library/doctest.html
I don't think this is related in any way.
> Having a CI job that identifies places where the docs have drifted from the implementation seems pretty valuable.
https://docs.python.org/3/library/doctest.html
> To check that a module’s docstrings are up-to-date by verifying that all interactive examples still work as documented. To perform regression testing by verifying that interactive examples from a test file or a test object work as expected. To write tutorial documentation for a package, liberally illustrated with input-output examples. Depending on whether the examples or the expository text are emphasized, this has the flavor of “literate testing” or “executable documentation”.
Seems pretty related to me.