How to use Nodez

A walk through the app from first launch to having an AI assistant connected. Nothing here is required in order - you can stop after the first section and have a perfectly good Markdown editor.

First launch#

Nodez is between releases: downloads are paused while a beta version is prepared. Watch the home page for it. Once installed, open it. A setup wizard walks you through five steps; you can skip straight past the optional ones and reopen the wizard later from Settings.

The steps are:

1. Open or create a vault - the only required one
2. Attach a code repo - optional
3. Index for AI
4. Agent contract for this vault - optional
5. Export for external agents

Opening a vault#

A vault is just a folder. Point Nodez at an existing folder of Markdown files and it reads them as they are - including a folder you already use with Obsidian. Or make an empty folder and start fresh.

Nodez adds one thing of its own: a .nodez folder holding the index and graph. Everything else in the folder stays exactly as you left it.

Once you have opened more than one vault, the picker keeps a short list of recent ones, so switching between projects does not mean browsing the filesystem again.

Writing notes#

The editor is Markdown, with a formatting toolbar and a live Preview. The sidebar holds your note tree; the right-hand panel shows the Document outline and Note properties.

Two things are worth knowing early:

Link notes with double brackets. Typing Some Note links to that note. If it does not exist yet, the link is marked as unresolved so you can find it later. This is the single most useful habit in Nodez - links are what build the graph.

Backlinks appear on their own. Any note that links to the one you are reading shows up in its backlinks, without you doing anything. See Links and backlinks.

Getting around#

Press ⌘K (Ctrl+K on Windows) for the command palette. It is the fastest way to jump to a note or run any command in the app, and it is worth learning before anything else.

Open graph shows the map of your vault. Once you are there:

• Local graph shows the neighbourhood around your current note; Global graph shows everything
• Notes only, Repo only, or Notes and repo control what is included
• Canvas 2D is the default renderer; the 3D force engine puts the same graph in space, which helps with dense clusters
• Fit to canvas re-frames everything
• Graph filters narrow by type of note or connection
• Clicking a node opens its details - its connections, and where it sits

To find how two notes relate, use the Path panel: pick a start and an end and Nodez traces a route between them. Reset returns to the full graph, and so does clicking empty space.

Adding your code#

In Settings → Indexing, or from the setup wizard, attach a code repository. Nodez reads the project - imports, calls, dependencies - and merges it into the same graph as your notes.

Nodez only ever reads your code. It does not modify it.

Indexing runs in the background and the status bar shows a spinner while it works. It re-indexes when your commit changes rather than on every keystroke. See Indexing a repository.

Syncing#

If your vault folder is a git repository, the GitHub sync control in the notes footer opens the sync panel, where you can pull, commit and push.

Two things Nodez will not do: it will not silently resolve a conflict, and it will not commit or push anything you did not ask for. When your local copy falls behind the remote, the status bar says so and clicking it opens the sync panel.

If your vault is not a git repository yet, set it up as one the normal way and Nodez will pick it up. See Syncing with GitHub.

Install and sign in to AI chat#

In the beta, Nodez connects to Codex, Claude Code, Grok, and OpenCode through their command-line apps. Install only the providers you want. Install Node.js 20 or newer for Nodez’s agent tools, then reopen your terminal.

1. Install a provider below and complete its sign-in.
2. Restart Nodez, open your vault, and select AI Chat.
3. Choose the provider, model, and access mode, then click Connect.

Codex

Run in Terminal or PowerShell:

npm install -g @openai/codex
codex login

Finish the sign-in prompts, then select Codex in Nodez. Nodez uses the CLI’s existing sign-in.

Claude Code

Install Claude Code 2.1.0 or newer. On macOS, run:

curl -fsSL https://claude.ai/install.sh | bash

On Windows, run in PowerShell:

irm https://claude.ai/install.ps1 | iex

Run claude and follow the login prompts; use /login inside Claude Code to sign in again. Then select Claude Code in Nodez. See Claude Code setup for supported accounts and installation options.

Grok

Install the official Grok CLI. On macOS, run:

curl -fsSL https://x.ai/cli/install.sh | bash
grok --version

For platform requirements and other installation options, see the Grok CLI instructions.

1. Create an API key in the xAI console.
2. In Nodez, open Settings → Keys → Grok API key, paste the key, and click Save.
3. Select Grok in AI Chat and connect.

Nodez stores the key in your system keychain. Its isolated Grok sessions require this key even if you have already signed in to Grok in a terminal.

OpenCode and free models

Install the CLI that provides the opencode command, then authenticate:

npm install -g opencode-ai
opencode auth login

Select your model provider and follow its sign-in or API-key prompts. Choose OpenCode in Nodez and connect to load the available models.

For free models, choose an available model marked free in the model picker. Availability and account requirements depend on the provider; other models may be billed. See OpenCode installation and provider setup.

If connection fails

• CLI not found: check codex --version, claude --version, grok --version, or opencode --version in a new terminal, then restart Nodez. Install the CLI on the same system as Nodez; a WSL-only install may not be visible to the Windows app.
• Sign-in expired: repeat the provider’s login steps and reconnect. For Grok, replace the key in Settings → Keys.
• No models or access denied: check the provider account’s model access and available credits. For OpenCode, run opencode auth list to check configured accounts.

Connect an external AI assistant#

This is the part that makes Nodez different from a notes app, and it takes about a minute.

You need Node.js installed. Nodez does not ship a copy. Settings → Agents shows whether it can find yours, and tells you how to install it if not.

Then, from Settings → Agents or the setup wizard:

• Copy MCP config puts a small block of JSON on your clipboard. Paste it into your assistant's settings - Claude Desktop, Cursor, and anything else that supports MCP - and restart it. It can now reach your vault.
• Copy agent handoff copies your current note, your selection and the connection details together, for when you want to start a conversation with context already in place.
• Agent contract optionally writes a short AGENTS.md into your vault, so an assistant knows the ground rules for your vault specifically.

Once connected, the assistant can search and read your notes, ask the graph what connects to what, and - when you ask it to - write notes back.

There is also an Ask about this note panel inside Nodez for quick questions without leaving the app. It works with OpenAI-compatible services or a local Ollama install.

Settings worth knowing#

• Agents - the assistant connection, Node.js status, and handoff tools
• Appearance - seven themes
• Indexing - the attached repository and how it is indexed
• About - your version, and checking for updates

If something looks wrong#

Nodez is in alpha. If the graph looks empty, check whether Local graph is on and your current note has no links yet. If indexing seems stuck, the status bar spinner tells you whether it is still running.

Anything else can wait for the beta, when feedback opens.