Local-first, offline by design

A local-first tool does its work on your own machine, with no round trip to a distant server. For source code this is not a nice extra; it is a requirement, because code is among the most sensitive things a business owns. That the same choice also makes the tool faster and lets it work on a plane is a welcome bonus, not the reason for it.

What local-first means

Local-first describes software that treats your own machine as the place where the real work happens and the real data lives, rather than treating your machine as a thin window onto a service running somewhere else. The distinction is easiest to feel by contrast. A great deal of modern software is the opposite: you type into a page in your browser, but the actual work and the actual data sit on a company’s servers, and your computer is mostly there to show you the result. That arrangement is often called cloud based, because the substance of it lives on machines you do not own, reachable over the network.

In a local-first tool, that relationship is turned around. The program runs on your computer. The data it works with stays on your computer. When you ask it to do something, it computes the answer right there, using your machine’s own processor and memory, and it stores what it learns in a file on your own disk. It may still connect to the network for some things, but it does not depend on a network to do its core job. The center of gravity is local.

Koragraph is built this way on purpose. It runs entirely on the developer’s machine, and no source code leaves the machine. The facts it works out about your code are kept in a local database file on that same machine, at ~/.koragraph/practice.db, and those facts persist across working sessions and follow your files even when they are renamed. Everything about where the work happens and where the results are stored points at one place: right here, on your own computer.

Why source code should not leave the machine

The strongest reason to build a code tool local-first has nothing to do with speed. It is that source code is often the most sensitive asset a company has, and sending it somewhere else is a real cost, sometimes a prohibited one. It is worth separating the reasons, because they stack.

The first is privacy and intellectual property. A company’s code can be the core of its business, the thing that took years to build and that competitors would love to see. Every copy of it that exists somewhere is a copy that could leak, be subpoenaed, be breached, or simply be retained longer than anyone intended. A tool that never sends the code off the machine creates no such copies. There is nothing in transit to intercept and nothing sitting on a distant disk to worry about.

The second is compliance. Many organizations operate under rules about where certain data is allowed to travel: legal restrictions, contractual promises to customers, or internal policies drawn to satisfy both. Under those rules, the question is often not whether you trust a given service but whether you are even permitted to send the data to it at all. A tool that keeps everything local sidesteps the entire review, because there is nothing to approve. The data never moves, so no policy about moving it is triggered.

The third is simple control. When your code stays on your machine, you decide what happens to it. You are not trusting a third party to secure it, to not train on it, to delete it when asked, or to still exist next year. Those may all be reasonable things to trust, but each one is a dependency you take on the moment the code leaves. Keeping it local removes the dependency instead of managing it.

For source code, local-first is not a feature you can weigh against others. It is the answer to a question, where is my code allowed to be, whose only safe reply is often, here.

The bonus: latency and working offline

Because the reasons above are about privacy and control, it is easy to miss that local-first also just performs well, and it is worth spelling out why. The first payoff is latency, the delay between asking for something and getting it. When a tool has to send a request across the network to a distant server and wait for the reply, that trip takes time, and it happens on every single request. A local tool has no trip to make. The question and the answer are on the same machine, so the waiting that the network imposes simply is not there.

The second payoff is that it works with no network at all. A tool that depends on a distant server stops working the moment the connection does: on a plane without usable wifi, on a train through a tunnel, behind a corporate firewall that blocks the service, or during an outage on the far end. A local-first tool does not notice any of that, because it was never relying on the network to do its job. It works in a locked room with the cable unplugged. For a developer who wants to understand their code, being able to do it anywhere, anytime, without asking whether the network is up, is quietly valuable.

There is a steadiness to this that is worth naming on its own. A tool that leans on a distant service inherits every bad day that service has: it slows down when the service is busy, it breaks when the service changes, and it can vanish if the service is retired. A local tool behaves the same on Monday as it did last year, because the thing it depends on is your own machine and nothing else. That predictability is not glamorous, but over months of daily use it is the difference between a tool you can build a habit around and one you learn not to count on.

The tradeoffs, stated honestly

Local-first is a choice, and an honest account includes what it gives up. The point is not that it is better in every way, but that for code its tradeoffs fall on the right side.

The clearest cost is that there is no shared central server, which means the conveniences a central server brings do not come for free. A cloud service can let a whole team query one copy of something, can pool everyone’s usage onto powerful hardware, and can be updated in one place for everyone at once. A local-first tool gives up that centralization by design. Each machine runs its own copy and works from its own data. If you wanted every developer on a team to share one live view, local-first is not the shape that gives it to you directly.

Updates are the same story. A cloud service can be improved in one place and everyone gets the new version at once, whereas each person running a local tool updates their own copy on their own schedule. That means a team can drift onto different versions for a while, which a central service never allows. It is a genuine cost of the local shape, and it is the flip side of the same independence that lets the tool keep working when the network is gone. You cannot have the one without accepting the other, so the honest question is only which set of tradeoffs fits the job, and for private source code the local set fits well.

The other cost is that the work runs on your own computer’s processor and memory rather than on someone else’s large machines. Heavy work uses your resources while it runs. For analyzing code this is usually a fine trade, since a developer’s machine is already sized to build and run the very code in question, but it is a real difference from offloading the work to a distant server. The bargain, then, is straightforward: you trade shared infrastructure and borrowed compute for privacy, control, speed, and independence from the network. For source code, that trade almost always favors staying local.

No cloud, and no model, inside the graph itself

There is a subtler point that is easy to run past, and it matters for both trust and reliability. Some tools that call themselves local still quietly depend on a distant service for the actual thinking: they run a shell on your machine but send the hard part to a large model in the cloud. That is a different thing from what is described here.

Koragraph has no LLM or cloud dependency. The knowledge graph it builds, the map of how your code connects, is produced by reading and analyzing the code directly, not by asking a language model to guess at it and not by calling out to any hosted service. This has two consequences worth naming. First, it is part of why nothing leaves the machine: there is no remote model to send the code to in the first place. Second, it means the results do not depend on a model being available, a network being up, or an external service behaving consistently from one day to the next. The analysis is deterministic work done on your machine, so the same code yields the same map, and it keeps yielding it whether or not anything on the internet is reachable.

It is worth being clear about how this sits alongside the AI agent that uses the graph. The agent itself may well be a large model, and that is fine; the point is about the graph, not the agent. When an agent asks Koragraph what calls a function, the answer it gets back was not produced by a model guessing. It was computed by directly analyzing the code. So the agent’s own uncertainty does not leak into the map it is reading. The map is a firm, checkable set of facts about the code, and the agent gets to reason on top of that firmness rather than on top of another layer of guesswork. Keeping the graph free of any model is what makes it a reliable foundation rather than one more thing that might be wrong.

How this shapes the whole design

Deciding to be local-first is not one feature among many. It is a decision near the root of the design, and once made it pushes every other choice in a particular direction. You can see the logic run downhill. If nothing may leave the machine, then the analysis has to run on the machine, which means it cannot lean on a hosted model and must instead read the code directly. If the results are to be useful across working sessions rather than recomputed from nothing every time, they have to be written down somewhere local and durable, which means a database file on your own disk. If that stored knowledge is to stay correct as the code changes, it has to survive ordinary edits, including files being renamed, rather than breaking the moment a path changes.

Each of those follows from the first commitment. This is why local-first is best understood as an architecture, a shape for the whole system, rather than a checkbox. Koragraph’s pieces line up with it: the graph is built by analyzing code on the machine with no model or cloud in the loop, the facts are stored in a local SQLite database at ~/.koragraph/practice.db, and that store persists across sessions and follows renames so the knowledge accumulates instead of evaporating. None of those are separate ideas bolted on. They are what local-first requires once you take it seriously.

Where this leads

Two threads run directly out of this one. The choice to keep durable knowledge in a plain file on your own disk raises the question of what that file is and why that particular kind of store was chosen, which is the subject of SQLite as the store. And the question of how the raw code gets turned into the facts that go into that store, all of it done locally, is the subject of The ingest pipeline. Stepping back the other way, the reason a local tool fits so naturally into an AI agent’s workflow at all traces back to MCP servers and clients, where the local server first found its place.