.svg){kind=logo}
Putting a NestWeaver graph on a server sounded like a small architectural step. The local daemon already knew how to index code and answer structural questions. Give it a network listener, point a few clients at it, and now a whole team could use the same graph. That was the idea, anyway.
Moving a query across the network was the easy part. Deciding which graph held the truth was harder.
A shared graph could see what an individual developer could not. It included services owned by another team, libraries that rarely changed, and relationships across repositories that never appeared together in one checkout. It could also amortize the expensive work of discovering that structure. Index once, query many times.
But the graph on my laptop knew something the server did not. It knew the branch I had just rebased, the file I had modified but not committed, and the function an agent had rewritten thirty seconds ago. Treating the server as authoritative would make broad answers possible by making immediate answers less trustworthy. Treating the laptop as authoritative would preserve the moment while erasing the organization around it.
That tension changed how I thought about server mode. This was not mainly a deployment problem. It was a question of scope, freshness, and what “current” means when software exists in several places at once. The important work was learning how to trust both.
A codebase stops being one codebase when a team touches it
One developer working in one checkout can pretend a codebase has a single shape. The graph on disk corresponds to the files in front of them, and a query about a function can end at the edge of that directory. It is a useful simplification. It also disappears as soon as a team starts working.
Now there are branches carrying different changes. There may be several services and shared libraries, whether they live in separate repositories or one large repository. Developers keep different subsets checked out. Coding agents start in clean worktrees, then discard them. CI jobs appear for a few minutes, receive only the material required for one task, and vanish.
Each environment can build its own graph, but that turns organization-level discovery into a repeated tax. A new developer indexes what the previous developer already indexed. An agent spends the beginning of a task reconstructing relationships another agent found an hour ago. CI pays the same setup cost on every run, then throws the result away. Worse, every one of those graphs is bounded by what happened to be present in that environment.
Most pull-request jobs receive only the repository being changed. That is a reasonable boundary for checkout time, credentials, and test execution. It is not evidence that the repository is isolated. An API response may be consumed by a dashboard. A library type may cross several services. A command-line flag may be embedded in deployment automation owned somewhere else.
The unit of change may be a repository. The unit of impact rarely is.
That distinction matters even for organizations that keep everything in a monorepo. A checkout can still be sparse, a job can still operate on a narrow path, and two developers can still be looking at different revisions. The problem is not “monorepo versus multirepo.” The problem is that the software a team understands is usually larger than the software any one process can see right now.
The team needs a shared map
The server’s job is to preserve that larger view. It maintains reusable organization-level structure across configured code and knowledge repositories, so a developer, agent, or CI job can ask about relationships without first acquiring and indexing every checkout. The graph becomes shared infrastructure: expensive discovery is performed centrally, while clients remain small enough to work inside the environment they actually have.
That changes the economics of orientation. When a new agent asks where a concept appears, it can begin with an existing map rather than paying the cold-start cost of reconstructing the organization. When a developer touches a shared contract, the surrounding systems are already represented. When CI receives one repository, it can still learn that the repository participates in a larger dependency chain.
NestWeaver server mode is available today. A server can index configured repositories and expose the graph to connected clients and AI agents. Push webhooks can prompt re-indexing, with polling as a fallback. None of that requires every client to keep every repository on disk.
The client asks for context; it does not inherit the server’s entire filesystem. The important word is “map.” The shared graph is not a remote copy of each developer’s working tree, and it should not pretend to be. It is the durable baseline that lets the team see across boundaries. That baseline gains value because it is reused, not because it replaces the smaller, changing maps next to the code.
Shared truth is not current truth
I tried to make one graph authoritative. I renamed a function in the working tree of a feature branch, then sent the read through server-first routing. The server returned the old name because it correctly represented the commit it had indexed, not the change sitting in my editor. Nothing was broken. I had asked the broader graph a question about the present.
So I flipped the priority and asked where that concept was used across the organization. The local graph understood the rename, but its answer stopped at the checkout boundary. Repositories only on the server disappeared. Server-first had lost the branch; local-first had lost the neighborhood. Watching both queries fail in opposite directions made the design decision concrete. Exact local source should lead, broad structure should come from the server, and answers that need both should preserve both.
Both views are right. Neither is complete.
Git revisions make the difference legible. Each indexed repository corresponds to a particular commit. A client can compare the commit behind its local graph with the revision known upstream and report when those views have diverged. That does not produce perfect freshness: a push still has to reach the remote, and the server still has to observe and index it. It does provide a concrete answer to a better question than “is the graph current?”: current relative to which revision, in which scope?
The routing policy can then respect the answer. Exact source reads should favor local code. Broad search can combine local and server results. Impact analysis can keep local effects and organization-wide effects in separate tiers instead of flattening them into a misleading single list. Results identify whether local data, server data, or both contributed, so the person or agent consuming them can judge the evidence.
Network failure belongs in this model too. If the server is unreachable, the local graph remains useful for the repository and working tree it can actually inspect. The answer becomes narrower, and cross-repository portions may be marked unavailable, but ordinary local work does not need to stop. A shared map should extend a local-first workflow, not turn the network into a prerequisite for understanding the file open in front of you.
Route the question to the right view
Once I stopped looking for one authoritative graph, routing became easier to reason about. The right starting point follows the question. Questions about the exact code under the cursor value freshness. Questions about structure across the organization value coverage. Questions about risk often need both, with their boundaries left visible.
| Question | Best starting point | Why |
|---|---|---|
| What does this function look like right now? | Local graph | The checked-out branch and working tree are the freshest source available. |
| Where is this concept used across the organization? | Local + server | Local matches preserve branch context; the server adds repositories not checked out. |
| What might this change affect? | Two-tier analysis | Local effects and organization-wide effects are both useful and should stay distinct. |
| Which components bridge multiple repositories? | Server graph | Structural roles become visible only when the broader graph is present. |
Local-first is a routing policy, not a refusal to share context.
That policy also guards against a subtle failure mode: a broad answer can look more authoritative simply because it contains more results. Conversely, a perfectly fresh local answer can look definitive while omitting a consumer in a repository that is not on disk. The client has to preserve provenance so “local” and “server” remain part of the answer rather than implementation details hidden beneath it.
Staleness is similarly contextual. A server graph can be current for the default branch and stale for the feature branch that exists only on a laptop. A local graph can be current for one repository and have no knowledge at all of twenty others.
The server mode documentation describes the concrete routing behaviors. The design principle is simpler: do not ask one scope to impersonate another. Start close to the change, reach outward when the question requires it, and keep enough origin information to know which view supplied what.
A pull request is where the boundary becomes visible
Imagine a change to processPayment in api-service. The implementation has been cleaned up, its return behavior has shifted, and every test in api-service passes locally. The pull request looks healthy because, within the repository being changed, it is healthy.
CI receives only api-service. It installs that repository’s dependencies, runs its test suite, and evaluates the diff against the code it has. This is normal. Checking out every repository in an organization for every pull request would create its own cost and access problems.
But three downstream systems still rely on the old behavior. billing-worker interprets the previous result when it schedules reconciliation. admin-dashboard renders fields from that response. notifications decides which message to send from the status it receives. None of those repositories exists in the CI workspace, so neither their source nor their tests can be inspected there.
The server graph supplies the missing relationships. The pull-request analysis can connect the changed processPayment symbol to callers, contracts, and dependent components represented in the organization baseline. Instead of concluding “all tests passed, therefore the change is contained,” the review can say, “local validation passed, and these three systems remain in the impact path.”
That is useful evidence, but it has a deliberate limit.
Server mode does not magically run those repositories’ tests. It tells the people and automation reviewing the change where the risk continues beyond the checkout.
That boundary is important enough to state plainly. A graph can identify a dependency edge, show the symbols at either end, and point reviewers toward the systems that deserve attention. It cannot prove that every downstream behavior is broken, and it cannot substitute for executing billing-worker, admin-dashboard, or notifications in their own environments.
What it changes is the quality of the next decision. The pull request can request review from the right owners. CI can post a focused list of downstream relationships. A developer can inspect a contract before merging. Another pipeline can choose to run additional tests if the organization has built that automation. NestWeaver provides the map for those choices; it does not claim to have traveled every road on it.
The local view still matters throughout. It supplies the precise diff and the freshest meaning of processPayment. The server supplies the organizational continuation. Keeping those contributions separate makes the warning more credible than either an isolated green check or a vague declaration that “something elsewhere might break.”
Local-first does not mean local-only
I started with what sounded like a server project and ended up with a lesson about authority. Immediate developer truth belongs next to the developer: the current branch, the working tree, and the code an agent changed moments ago. Moving that truth behind a network request would make the local workflow more fragile while making its answers less current.
The expensive organization-level discovery belongs in a shared graph. Relationships across services and libraries should not need to be rediscovered by every laptop and short-lived CI job. They gain value when the team can build them once, update them as repositories move, and query them from environments that hold only part of the code.
The useful answer is assembled at query time. Local source leads when the question is about the present checkout. The server leads when the question requires organization-wide structure. Impact questions keep both scopes and their provenance visible. If the network fails, the local graph continues answering within its honest boundary instead of turning a partial outage into a blocked editor.
What changed for me was the meaning of “truth” in a code intelligence system. There is no contradiction in saying the laptop knows the function best while the server knows its neighborhood best. The failure is asking either one to stand in for the other. Once freshness and scope become explicit, multiple truths stop competing for authority. They become legible, routable, and composable.
Explore NestWeaver on GitHub or read the server mode documentation.