Nectar FAQ

Common questions about nectar: what it does, how it differs from grep, whether it changes your workflow, whether teams re-index, and whether your code is safe.

Nectar gives every file a stable identity and a plain-language description so your assistant can find code by meaning. It complements, not replaces, grep and symbol search. It requires no workflow changes, teams do not re-index, and only file contents needed for a description are sent through a gateway you configure.

What does nectar actually do?

It reads each file in your project once, gives it a stable identity, and writes a short plain-language description of what it does. Your assistant searches those descriptions to find code by meaning instead of file name.

How is nectar different from grep or my editor's search?

Grep and editor search match exact words and names. Nectar matches meaning, so it finds a file like session-refresh.ts for a question about logins even though the word login never appears in it.

Does nectar change my workflow?

No. You write, name, and organize code exactly as you do today. There are no comments, markers, or conventions to add.

Does every teammate have to re-index the project?

No. The understanding is stored in one committed file. A teammate who clones the repo inherits every description instantly, with no re-scan and no extra cost.

Is my code safe?

Nectar only reads your source to write descriptions. File contents are sent only through a gateway you configure yourself, and nectar never writes to or changes your source files.

Straight answers to the questions people actually ask about nectar.

#What does nectar actually do?

It reads each file in your project once and writes a short plain-language description of what it does, something like "refreshes login tokens on each authenticated request." It gives every file a stable identity so that description stays attached even through renames and moves. Your assistant then searches those descriptions instead of guessing from file names.

#How is nectar different from grep or my editor's search?

Grep and your editor's search are exact-match tools. They compare the letters you typed against the letters in your files, so they only work if you already know a name, a variable, or a string that literally appears in the file you're looking for.

Nectar works the other way. It already knows what each file is for, so you can ask a plain question, like "where is the login logic," and get back files whose names and contents never even contain the word "login." The two aren't competing. Use grep when you know the exact name. Use nectar, through your assistant, when you know the idea but not the name.

No. Those are structural tools: they read the grammar of your code to know that this name refers to that function. They're exact and essential for things like safely renaming a symbol or tracing a call chain. Nectar is semantic: it knows what a file means and is for. The two answer different questions and work well together.

#Does nectar change my workflow?

No. You write, name, and organize your code exactly as you do today. There are no special comments, naming conventions, or markers to add. Descriptions are produced for you automatically, in the background.

#Does every teammate have to re-index the project?

No. Nectar's understanding is stored in one file, .honeycomb/nectars.json, that gets committed to your repository like any other file. When a teammate clones the project, their copy already contains the map, so their nectar recognizes every file and inherits its description with no new scan and no new cost. One person, or one automated run, pays the one-time cost. Everyone else inherits it for free, instantly, even offline.

#What does the first scan cost?

It's a one-time cost per project, not a recurring fee. Roughly: about 200 files costs thirty cents, 2,000 files costs about three dollars, and 10,000 files costs about fifteen dollars. Run nectar brood --dry-run first to see the exact number before spending anything. Day-to-day cost after that first scan is minimal, because nectar only re-describes files that meaningfully changed.

#Is my code safe? Does it leave my machine?

Nectar only reads your source to write descriptions. It never modifies your source files. The only file it writes is its own map. When a file needs a description, its contents are sent, one file at a time, through a gateway you configure yourself, to a language model, and only the generated description comes back. Your file's identity is created and stored locally and never needs to leave. If your organization requires that no source ever leave the network, that's a matter of how you configure the gateway.

#What happens if I rename or move a file?

Nothing breaks. A file's identity doesn't depend on its name or its location, so renames, moves, and full folder reorganizations keep the file's description intact, with no cost to re-describe it.

#Does nectar re-scan on every save?

No. Nectar waits for a pause in your editing, and only re-describes a file when its content changed in a way that matters. Cosmetic changes, like reformatting, are ignored.

#What if a description looks wrong?

It usually corrects itself the next time the file meaningfully changes. You can also force a fresh description right away with nectar brood --force.

#What happens if I stop using nectar?

Nothing is lost. The map is a committed, readable file that doesn't depend on a running service or a subscription. Because your source was never modified in the first place, there's nothing to clean up if you walk away.

#Common questions

See the list above. Each answer links back to more detail in how nectar works, getting started, and the command reference.