Chips development guide

Chips development guide

Chips — chips, the catalog, and the Studio

A chip is a small Python module shipped as a chip: a .png whose entire codebase rides inside the image. A loadable chip declares command, use, aliases and params, and defines run(arguments). Chips reach Navi through navi_internal.navi_instance — print_message(text) to speak, llm_chat(message) to ask her model, process_message(text) for her full pipeline. Every method is written up in full on this wiki's Navi Chip Functions page — the documentation is their home.

Navi User Repo (NUR) searches GitHub for repos tagged navi-chips — that topic is the whole store. The Saints Sec Chips and Community Chips tabs are where you find and install chips: a card there shows whether you already have the chip, and that is all it does with it. A chip that is already on this machine — installed from its repo, or forged in Chip Studio under the same name — reads INSTALLED on its catalog card and its Install button sits grayed out: there is no second install over the copy you have. Install tracks the latest release; a newer release offers an update, which you take from the chip's card on the Local Chips tab. Chip Studio is where chips are written: a full code editor with highlighting, find, templates, and a live structure check. To publish: public repo, the navi-chips topic, a release tag as the version.

Editing a chip you already have. Local Chips is where you manage the chips you have — its card carries every management action: Run, Download .png, Edit in Studio, Edit README, Export for GitHub, Publish to GitHub (the whole chain now: repo, topic, upload, release — an existing version is refused up front), Check for updates / Update, and Delete. Uninstall is also on the chip's NUR card and in ChipDeck, and installs from Navi User Repo (NUR) now show in Local Chips in the same session, ready to run, edit and uninstall. Any chip in the folder can go back to the Studio — press Edit in Studio on its card in Navi User Repo (NUR) → Local Chips, or pick it in the Studio's Open a chip list. Forged chips, GitHub installs, and chips you once exported and installed again all open with their whole file set — root.py and modules together. Saving re-forges the chip with your changes inside. If the chip came from GitHub, saving marks it edited locally: the app says plainly that your copy no longer matches the published one, and an Update will refuse rather than quietly overwrite your edits. To share your version, use Export for GitHub in Navi User Repo (NUR) and cut a new release. Knowledge packs work the same way: Edit in RAG Studio on the RAG tab reopens any pack — documents in or out, name and description adjusted — and saving rebuilds its index on your machine.

Running chips from chat, and Workflows

Any loaded chip runs from the conversation: ./<name> — the way you run a program — with its arguments after it (./navi-cryptex hex -e -t "Hello world!"); a short name resolves (./cryptex finds navi-cryptex), a bare ./ answers with the shelf itself, and typing ./ in the composer offers the chips' names as you type. /chip <name> remains as the long-form alias, alongside "run the chip" and its name alone — its output lands in the thread. Under the CLI latch ($), ./ is the shell's own again: the latch decides, never a guess. There is no pill row above the composer anymore — the shelf lives in ChipDeck now, and running lives at the keyboard. The bridge genuinely runs it: code defining run() executes with a working navi_internal; a chip that only declares an output shows that instead. Workflows chain chips in order — each chip's output becomes the next chip's input, and the last output is the result.

ChipDeck — the binder

ChipDeck (in the menu, under Chips) is the binder for everything that rides a picture. It lists every installed chip, every Apex Mesh pairing card on file (config/mesh/cards/), and every knowledge pack, with each thing shown as its actual picture — face, card, or cartridge — state and all, and its actions gathered on its own sleeve. A chip's sleeve runs (./<name>), downloads its picture, opens in Chip Studio, and uninstalls; a Mesh card downloads and unpairs; a pack activates, deactivates, downloads its cartridge, and removes. Drop a picture onto ChipDeck and the data inside the picture says what it is — chip, knowledge cartridge, or Mesh card — and each installs through its own door. The picture carries the chip's manifest version inside it: the install receipt states that version, and a chip's sleeve states it too. When the picture carries no version, both show nothing for it; neither guesses one. A picture whose data was stripped on the way (most chat apps and social feeds do that) is refused, in plain words: send originals inside a .zip. What never rides a picture stays out of the binder: Soul, Memory, settings and config, the Vault's notes, and every key. Those travel in backups only.

Writing a chip, step by step

A chip is a small Python program Navi can run. A chip is a set of files: root.py — the main file, the one Navi runs; every chip has exactly one — and helper files like helpers.py, extra Python files root.py brings in with import helpers. The rules root.py follows (the Studio checks them and underlines what is missing):

1. It brings in Navi with import navi_internal and takes hold of her with navi_instance = navi_internal.navi_instance().
2. It says its name with command — the word people type to run it.
3. It says what it does with use — one short line.
4. It can list other names in aliases and describe its inputs in params (what -help shows).
5. It defines run(arguments) — the part Navi calls; arguments.text is the words typed after the chip's name.

Through navi_instance a chip can print_message(text) (show a line), llm_chat(text) (ask her model), process_message(text) (hand text to Navi as if typed), get_user()/set_user(name), clear_terminal(), and chat_with_navi(). Every one of those functions is explained in full — what it takes, what it gives back, and when to reach for it — on this wiki's Navi Chip Functions page, in the sidebar.

Making one:

1. Chips tab → Chip Studio.
2. Name it.
3. Write root.py.
4. Add helper files in the file list.
5. Forge chip.

The whole file set packs into the chip picture. The editor colors code, guides indents, folds blocks, finds words in every file, saves on its own, underlines missing pieces, and goes full screen — its toolbar holds the rest (command palette, outline, zoom, wrap). The writing desk itself has its own page in the sidebar: The Chip Studio editor.

A chip's face is drawn, not rolled, and it is card grade, drawn with the same renderer as the Mesh pairing cards: a family header in the chip color — coral red (255, 111, 97), the color chips have always worn, now official — the glyph large in its window, a name band, what the chip does, and a split footer: the family and output kind at the bottom left, the version at the bottom right, omitted when a picture's data does not know one. The glyph is named in the chip's manifest (glyph in navi-chip.json); with no glyph named, a keyword read of the chip's name and description picks one, and a chip nothing claims keeps the name-seeded pattern in the window, at the same grade. Faces are drawn at forge time. Published pictures keep theirs until re-forged. The window itself now has texture: a dim field of QR-style tiles, seeded from the cartridge's name with finder squares in three corners, in the face's accent dimmed down. The glyph sits over it as a solid silhouette with a shade offset, and the built-in glyphs were all redrawn at 20×20 — filled objects with negative-space cuts, drawn to be read at sleeve size. A manifest can also declare its own art: an icon in navi-chip.json — twenty rows of twenty characters, # for the accent, o for the shade, . for empty. Declared art outranks the glyph; below it, the order is the built-in glyph, then the name-seeded pattern. The art rides inside the picture, with the glyph and the version. Malformed art is refused in plain words when the chip is forged or exported; a picture whose art arrives damaged falls back to its glyph rather than failing. Chip Studio edits the icon as text rows. Faces are still drawn at forge time.