Building nawc and nit

Alright let’s jump right in. Here’s what I’ve been working on: nawc - a notion/obsidian alternative. It’s a notebook built with extensibility, collaboration, and a local-first approach as its guiding principles. nit - a version control system designed to be fast, secure, and modular, where collaboration is instant. You can even commit your .env files.

But before I explain in more detail, I’d like to share a bit of details on how these two projects came to be, and why they’re related.

How these projects came to be

Uninterestingly enough, these ideas started out like most tech ideas nowadays - I got frustrated with AI.

The biggest weakness of LLMs is also their biggest strength - they model language. And language is imprecise. It’s full of nuance. But code and ideas aren’t. They have requirements and preferences, both of which can be interpreted in many ways.

If you’ve done any amount of AI assisted programming you know the dance. You tell the LLM to write a function. And well… it works, it’s just that I’d rather have it be structured like this, and… okay well now you misunderstood me, you broke this feature I did like… I meant that you shoul- no don’t delete that! Ugh. Whatever. I’ll write it myself.

And the weird part? LLMs are getting really good at making good decisions. They suddenly have way more “taste” than before. So people are relying on it. There’s not even a reason to read the code. And I mean, I get it. LLMs are getting somewhat reliable, and you can trust bigger models to no longer pwn your entire organization by logging your .env file in a function it writes. Most of the time. Hopefully.

And they’re getting better too. So ship something that works good enough, and then surely they’ll get better later and fix all the small bugs. Retroactively rewriting your entire codebase in rust has never been easier.

But we must make one separation clear - ideas have requirements, and preferences.

LLMs can only improve in one of those. They can be aligned to understand requirements from language that is less verbose. But they can’t really be aligned on preferences, simply because different people have different preferences.

Some solutions were introduced for this problem, I think a bit too early. And to me, they exposed a new set of issues. AGENTS.md and skills can be used to specify preferences in natural language, but they’re often misused, bloat the context window with information that’s irrelevant to the task, or confuse the agent. TDD is fantastic in theory since it provides a deterministic, sometimes black-box approach for agents to check their work. But agents often cheat - writing weaker tests than necessary, or changing the tests so they pass with their implementation. Not to mention that no one wants to put the effort to write those test, so who ends up writing them? that’s right, AI.

nawc as the solution

nawc tries to take what I like to think of as a “diffusion” approach. It’s inspired by Matt Pocock’s grill-me skill, where:

1. The user provides the agent with a rough idea of the feature to be implemented.
2. The agent then asks the user questions to sort out their preferences, and records the decisions, slowly refining the plan.
3. Once all decisions have been recorded, the agent can convert the plan into detailed issues that depend on one another, for another agent to implement.

Note - a lot of the problems I mention below have been fixed with the release of Matt’s new “wayfinder” skill.

And while this approach is closest to what I find ideal, I still have a few problems with it:

1. The issues generated are still in plain text. And while the original agent might be aligned with the user, subsequent agents lose that context, and can still misinterpret the intent described in the issues. Especially since LLMs are still TERRIBLE writers.
2. The user might not have a full idea of what they want. While using the skill I found myself telling the LLM one thing, then after it grilled me for a while I realized the idea I originally had needs to be reworked entirely. This workflow is great for capturing intent, but it’s a bit difficult to rework and prototype on the fly.
3. Agents seem to struggle with “the splash zone”. Docs grow stale, and features evolve over time. This workflow avoids long-term documentation where possible. It takes a “docs can’t grow stale if they don’t exist” approach. But as a result, when working with Matt’s skills, I found myself answering the same questions about projects over and over again.

The solution I came up with is nawc, which was meant to be used as a tool to empower spec and test driven development. It provides the agent with a standard space to write specs, docs, examples, and explanations - the nawc notebook:

• The notes in the notebook are powered by HTML, and allow the agent to create rich fully interactive elements.
• They’re also given custom elements that allow them to reference, and even run code from other places in the codebase (similarly to jupyter notebooks).
• The user interface is powered by tiptap, and allows the user to edit the notes using familiar and quick markdown syntax, while still being able to view and interact with the HTML written by the agent.
• Notes can be linked to other notes, similarly to obsidian, which can be used to establish relationships and hierarchy between them.
• nawc provides the LLM with tools to search through the notes. It also attempts to help alert the user and the agent if a change in the codebase could potentially make some notes stale.

The workflow then becomes more focused on prototyping, and recording design decisions with both readable natural language and deterministic code:

1. The user creates a note for a new feature. They write markdown describing what they want.
2. They ask the agent to help them refine the plan. The agent asks questions that help understand the user’s preferences.
3. The agent records design decisions in the note, and adds HTML-based visualizations, runnable code examples, and tests that help describe the understood intent.
4. The user can continue answering questions and refining the prototypes in the note with the agent until they are satisfied.
5. Future agents can use these notes to have more deterministic guidelines for the user’s preferences.
6. Referenced files/linked notes can be used to identify when a change might create a “splash zone” which leads to stale documentation.

nawc is not all it could be

You see, at first I just wanted to just make a tool to make AI coding more manageable for myself. Then I realized that a lot of what makes that tool so powerful are things I could use outside of just coding.

I started thinking about two tools I use every day - Notion and Obsidian. I like to think of both as notebooks, where you can use your notes as powerful data. Both have their advantages and disadvantages. Notion is collaborative, and can be used to manage teams of all sizes. Its notes are like a database, with extensive tooling that makes extracting useful information from them take just a few clicks. Obsidian is extensible and local. Notes are just markdown files that you own. It’s simple at its core, but has a rich plugin system that allows you to do whatever you want with your notebook.

What if we could have the best of both worlds? Suddenly my idea became bigger.

If I could just slap nawc as a plugin to either Notion or Obsidian I would. But they’re both missing features I want. They either suck to work with collaboratively, suck to extend, aren’t available offline, but most importantly - their simplicity is their biggest weakness. Markdown is not as powerful as HTML.

So the idea became - make a notion/obsidian alternative, powered by HTML, with the syntax simplicity of markdown, with an offline first approach, and extensibility and collaboration as guiding principles. That’s what the future of nawc looks like to me. But that’s not what I’m releasing today.

Quick Aside To Talk About NIT

nit, or nawc-it, came to be as a by-product of my work on nawc. Thus the name. But it’s slowly starting to seem like the more important one out of the two.

I needed a way for nawc to share files between my devices efficiently. The natural first choice for me as a developer was my familiar git. But using git meant partially abandoning one of my guiding principles of collaboration.

Collaboration in nawc means the ability to share files with the notebook’s co-authors. But git takes an all or nothing approach. You either share everything, or nothing at all.

That approach prevents me from having just my one notebook for everything. It means having to jump between my personal diary to my work notes I share with my boss, which would have to be in separate notebooks.

How do I make notes from different notebooks link without dealing with more security vulnerabilities? How do I make that process smooth and seamless? What if I suddenly want to share a note from my diary with my boss? Do I have to create a whole separate notebook or put it in my work notebook?

I was going to just build a simple sync engine with permissions instead. But then this talk came up…

It’s Time To Rethink Everything by @t3dotgg

Theo sniped me. It almost felt like it was directed right at me. He literally talks about the same weaknesses of git I encountered. The problems that I already started solving with nawc.

I’ve made a potentially really silly decision. If I expand the scope of this project just a little bit, and generalize it to more than just nawc, I can confidently say I could make a legitimate git alternative that solves all of those issues, and more.

And thus, nit was born. I won’t go into much more detail in this post. There should be another post on my website already with details about nit’s design by the time you’re reading this: Designing a git alternative - nit.

Where We Are Now

I’ll be completely honest. The version of nawc I’m releasing today is a slop fork of the original.

It’s made to live in your codebase as a node package, and while still extensible, it’s not exactly the separate collaborative app I had in mind. And I’m okay with it.

I created this buggy and unpolished version because I was still excited about the original concept of the AI coding workflow it enables. So I created this version just so I could use that workflow somehow, and build the real nawc and nit using it.

So I’m letting anyone know in advance. I do not care about this version of nawc. You might encounter some bugs I would just rather not fix, because they don’t impact my workflow. I tried to cram as many features in it as possible, like language syntax support, and agent providers, but all of them are not as well-tested as the ones I use in my workflow. So there probably will be broken features and bugs. And I’m gonna rely on other people to fix those, because again - I don’t really care about this version of nawc.

Although I will say, it’s mostly polished because it had a solid base already made.

Now that I have a decent, usable version of nawc, I’m going to use it to assist me in developing the real nawc and nit.

I hope that by sharing this project, as unfinished as it is, that I inspire others to take risks, think bigger, and create in public.

I also created this project so that people stop vibe coding so hard. This tool is meant to give you better control over your agents. PLEASE care about the code you put out there.