# noodlbox manual

Product version: 2.1.0
Bundle verified: 2026-08-27
Canonical docs: https://docs.noodlbox.io

## Contents

- [Start here](/start-here.mdx) — stable; verified 2026-09-02; product 2.1.0
- [Start here / Install](/start-here/install.mdx) — stable; verified 2026-08-28; product 2.1.0
- [Guides / Debug a Failure](/guides/debug-a-failure.mdx) — stable; verified 2026-08-27; product 2.1.0
- [Guides / Explore an Unfamiliar Codebase](/guides/explore-an-unfamiliar-codebase.mdx) — stable; verified 2026-08-27; product 2.1.0
- [Guides / Plan and Refactor a Change](/guides/plan-and-refactor-a-change.mdx) — stable; verified 2026-08-27; product 2.1.0
- [Guides / Review a Change](/guides/review-a-change.mdx) — stable; verified 2026-08-27; product 2.1.0
- [Concepts / How Noodlbox Works](/concepts/how-noodlbox-works.mdx) — stable; verified 2026-08-27; product 2.1.0
- [Concepts / Graph Schema and Cypher](/concepts/symbols-and-relationships.mdx) — stable; verified 2026-08-28; product 2.1.0
- [Concepts / Trust and Freshness](/concepts/trust-and-freshness.mdx) — stable; verified 2026-08-27; product 2.1.0
- [Integrations](/integrations.mdx) — stable; verified 2026-09-08; product 2.1.0
- [Reference / CLI Reference](/reference/cli.mdx) — stable; verified 2026-08-27; product 2.1.0
- [Reference / Configuration](/reference/configuration.mdx) — stable; verified 2026-08-27; product 2.1.0
- [Help / Compatibility and Limits](/help/compatibility.mdx) — stable; verified 2026-09-01; product 2.1.0
- [Help / Troubleshooting](/help/troubleshooting.mdx) — stable; verified 2026-08-27; product 2.1.0
- [Help / Upgrade and Migrate](/help/upgrade-and-migrate.mdx) — stable; verified 2026-08-27; product 2.1.0
- [Home](/.mdx) — stable; verified 2026-09-02; product 2.1.0

---

---
title: "Quick start"
description: "Connect your coding agent and ask your first grounded question."
url: "https://docs.noodlbox.io/start-here"
hierarchy: ["Start here"]
lastVerified: "2026-09-02"
productVersion: "2.1.0"
audience: "new-user"
contentType: "home"
status: "stable"
keywords: ["quickstart","onboarding","install","first search"]
source: "start-here.mdx"
---

# Quick start

If Noodlbox is not installed yet, follow [Install](/start-here/install). The installer starts onboarding automatically on a first install.

## Connect your agent

If you skipped onboarding or want to run it again:

```bash
nbx onboard
```

Choose your coding client and restart it after setup. You can skip CLI sign-in for public boxes; private boxes require an entitled account.

## Analyze a repository

Open a repository and run:

```bash
nbx analyze .
```

This creates the box and its local graph. There is no separate init step.

## Ask a real question

Open a repository in your coding agent and ask:

```text
Use Noodlbox to explain how authentication refresh works before changing it.
```

The agent can now read its execution paths, definitions, callers, and dependencies.

## Use the CLI directly

To retrieve context yourself:

```bash
nbx search "auth refresh flow"
```

## Where next

- [Client-specific setup notes](/integrations)
- [Explore an unfamiliar codebase](/guides/explore-an-unfamiliar-codebase)
- [How Noodlbox works](/concepts/how-noodlbox-works)
- [Troubleshooting](/help/troubleshooting)

---

---
title: "Install"
description: "Install the nbx CLI."
url: "https://docs.noodlbox.io/start-here/install"
hierarchy: ["Start here","Install"]
lastVerified: "2026-08-28"
productVersion: "2.1.0"
audience: "new-user"
contentType: "quickstart"
status: "stable"
keywords: ["install nbx","CLI","version","doctor"]
source: "start-here/install.mdx"
---

# Install

Install `nbx`:

```bash
curl -fsSL https://install.noodlbox.io/install.sh | bash
```

The installer verifies the download, installs `nbx` in `~/.local/bin`, updates your shell path, and starts first-time onboarding. It supports Apple Silicon macOS and Linux on x86_64 or ARM64. On Windows, use WSL.

Restart your shell, then check the installation:

```bash
nbx version
```

If the command is unavailable, see [Troubleshooting](/help/troubleshooting).

## Next

[Run the quick start →](/start-here)

---

---
title: "Debug a Failure"
description: "Trace a symptom through the execution paths and definitions around it."
url: "https://docs.noodlbox.io/guides/debug-a-failure"
hierarchy: ["Guides","Debug a Failure"]
lastVerified: "2026-08-27"
productVersion: "2.1.0"
audience: "developer"
contentType: "guide"
status: "stable"
keywords: ["debug","failure path","callers","dependencies"]
source: "guides/debug-a-failure.mdx"
---

# Debug a Failure

Start with the symptom, not a guessed file:

```bash
nbx search "expired session retries after refresh" --intent debug
```

## Inspect the suspect

```bash
nbx def refreshToken --include-content
```

Check the definition, direct callers, and dependencies before deciding where the fault lives.

## Ask a precise graph question

When the returned context leaves one relationship unclear, query it directly:

```bash
nbx query "MATCH (caller:CODE_SYMBOL)-[r:CALLS]->(target:CODE_SYMBOL) WHERE target.name = 'refreshToken' RETURN caller.name, type(r) LIMIT 20"
```

## Confirm with runtime evidence

Noodlbox explains code structure. Use logs, tests, traces, and a reproducer for failures that depend on runtime state.

Ask your agent:

```text
Use Noodlbox to trace this symptom to its entry points and shared dependencies. Then tell me what runtime evidence would confirm the cause.
```

## Next

- [Plan or refactor the fix](/guides/plan-and-refactor-a-change)
- [Review the change](/guides/review-a-change)

---

---
title: "Explore an Unfamiliar Codebase"
description: "Find the important paths, boundaries, and definitions without reading every file."
url: "https://docs.noodlbox.io/guides/explore-an-unfamiliar-codebase"
hierarchy: ["Guides","Explore an Unfamiliar Codebase"]
lastVerified: "2026-08-27"
productVersion: "2.1.0"
audience: "developer"
contentType: "guide"
status: "stable"
keywords: ["explore codebase","map","search","definitions"]
source: "guides/explore-an-unfamiliar-codebase.mdx"
---

# Explore an Unfamiliar Codebase

Initialize the repository once:

```bash
nbx init
```

## See the structure

```bash
nbx map
```

The map groups code by functional communities and execution workflows, which is often more useful than starting from folders.

## Search by behavior

```bash
nbx search "how authentication refresh works"
```

Use a concrete behavior or task. Search returns the code paths and definitions that belong together.

## Inspect the important symbol

```bash
nbx def refreshToken
```

`nbx def` shows the selected definition with its callers and dependencies. If several symbols share the name, add `--file <path>` or use the returned UID.

## Use it with your agent

Ask:

```text
Use Noodlbox to map this codebase, identify the entry points for authentication, and explain the refresh flow before editing.
```

## Next

- [Plan or refactor a change](/guides/plan-and-refactor-a-change)
- [How Noodlbox works](/concepts/how-noodlbox-works)

---

---
title: "Plan and Refactor a Change"
description: "Find the implementation boundary, callers, and verification targets before editing."
url: "https://docs.noodlbox.io/guides/plan-and-refactor-a-change"
hierarchy: ["Guides","Plan and Refactor a Change"]
lastVerified: "2026-08-27"
productVersion: "2.1.0"
audience: "developer"
contentType: "guide"
status: "stable"
keywords: ["plan change","refactor","callers","dependencies"]
source: "guides/plan-and-refactor-a-change.mdx"
---

# Plan and Refactor a Change

Describe the change you intend to make:

```bash
nbx search "move token rotation behind a new boundary" --intent implement
```

## Inspect the target

```bash
nbx def refreshToken --include-content
```

Record the direct callers and dependencies that define the current boundary.

## Resolve remaining questions

Use a focused graph query only when search and definition context do not answer a precise relationship question:

```bash
nbx query "MATCH (caller:CODE_SYMBOL)-[:CALLS]->(target:CODE_SYMBOL) WHERE target.name = 'refreshToken' RETURN caller.name LIMIT 20"
```

## Make and verify the change

Edit with your normal tools, run the project tests, then inspect the structural delta:

```bash
nbx diff
nbx verify --digest
```

Ask your agent:

```text
Use Noodlbox to plan this refactor. List the boundary to change, callers to preserve, dependencies involved, and verification targets.
```

## Next

- [Debug a failure](/guides/debug-a-failure)
- [Review a change](/guides/review-a-change)

---

---
title: "Review a Change"
description: "See which structural relationships changed and what deserves verification."
url: "https://docs.noodlbox.io/guides/review-a-change"
hierarchy: ["Guides","Review a Change"]
lastVerified: "2026-08-27"
productVersion: "2.1.0"
audience: "developer"
contentType: "guide"
status: "stable"
keywords: ["review","diff","verify","blast radius"]
source: "guides/review-a-change.mdx"
---

# Review a Change

Run your normal tests and inspect the source diff first. Then ask Noodlbox what changed structurally:

```bash
nbx diff
```

Use `nbx diff --json` when another tool needs the full machine-readable result.

## Inspect important definitions

```bash
nbx def refreshToken --include-content
```

Focus on changed entry points, shared definitions, callers, and dependencies.

## Run the verification pass

```bash
nbx verify --digest
```

Treat the digest as structural review evidence, not a replacement for tests or source review.

Ask your agent:

```text
Review this change with Noodlbox. Identify affected workflows, shared callers, and the tests I should run before merging.
```

## Next

- [CLI reference](/reference/cli)
- [Troubleshooting](/help/troubleshooting)

---

---
title: "How Noodlbox Works"
description: "How repository source becomes task-scoped context for coding agents."
url: "https://docs.noodlbox.io/concepts/how-noodlbox-works"
hierarchy: ["Concepts","How Noodlbox Works"]
lastVerified: "2026-08-27"
productVersion: "2.1.0"
audience: "all"
contentType: "concept"
status: "stable"
keywords: ["code context compiler","analysis","search","workflows"]
source: "concepts/how-noodlbox-works.mdx"
---

# How Noodlbox Works

Noodlbox initializes a repository once, then retrieves a small, relevant slice for each task.

## Initialize once

```bash
nbx init
```

Initialization analyzes source, resolves symbol identity across files, and records typed relationships such as calls and imports. From that model, Noodlbox derives functional communities and ordered execution workflows.

This is why Noodlbox can distinguish a large file from an important entry point, or a matching name from the definition actually used by a workflow.

## Retrieve per task

```bash
nbx search "auth refresh flow"
```

Search starts from relevant symbols, follows their resolved connections, and returns the workflows and definitions that belong together for the task.

## Inspect precisely

```bash
nbx def refreshToken
```

Definition context gives one symbol's location, body, callers, dependencies, and community. Use `nbx query` when you need to ask an exact graph question.

## Review current work

```bash
nbx diff
nbx verify --digest
```

These commands compare the working tree with the analyzed baseline and surface structural changes that deserve review.

## The practical model

- Repository → initialize once → local structural model
- Task → search → relevant code paths and definitions
- Change → diff and verify → structural review evidence

Noodlbox supplies code-structure evidence. Source inspection, project tests, logs, and runtime traces remain the authority for behavior.

## Next

- [Graph schema and Cypher](/concepts/symbols-and-relationships)
- [Trust and freshness](/concepts/trust-and-freshness)
- [CLI reference](/reference/cli)

---

---
title: "Graph Schema and Cypher"
description: "Node labels, typed relationships, properties, and supported Cypher for nbx query."
url: "https://docs.noodlbox.io/concepts/symbols-and-relationships"
hierarchy: ["Concepts","Graph Schema and Cypher"]
lastVerified: "2026-08-28"
productVersion: "2.1.0"
audience: "developer"
contentType: "reference"
status: "stable"
keywords: ["graph schema","Cypher","relationships","nbx query"]
source: "concepts/symbols-and-relationships.mdx"
---

# Graph Schema and Cypher

`nbx query` gives you read-only access to the local code graph. Run `nbx schema` first: the installed binary is the authority for its exact labels, properties, and Cypher support.

```bash
nbx schema
```

## Node labels

| Label | Identity | Represents |
|---|---|---|
| `CODE_SYMBOL` | `symbol_uid` | A resolved function, method, class, type, variable, or other code definition. |
| `FILE` | `file_uid` | A source file in the analyzed repository. |
| `COMMUNITY` | `community_uid` | A functional cluster of tightly coupled symbols. |
| `WORKFLOW` | `workflow_uid` | An ordered execution path from an entry point through resolved calls. |
| `DOCUMENT` | `document_uid` | A documentation chunk linked to repository symbols when present. |

All node types include `repository_id` and `producer_slot` so results remain attributable inside multi-repository boxes.

## Typed relationships

### Code structure

| Relationship | From → to | Meaning |
|---|---|---|
| `CALLS` | symbol → symbol | One symbol calls another. |
| `IMPORTS` | symbol → symbol | A resolved import relationship. |
| `EXTENDS` | symbol → symbol | Type or class inheritance. |
| `IMPLEMENTS` | symbol → symbol | Interface or trait implementation. |
| `USES` | symbol → symbol | A resolved symbol use outside the more specific edge types. |
| `CONTAINS` | symbol → symbol | A symbol lexically contains another symbol. |
| `MODULE_INIT` | symbol → symbol | A module initialization relationship. |
| `INVOKES_MACRO` | symbol → symbol | A resolved macro invocation. |

### External boundaries

| Relationship | From → to |
|---|---|
| `EXTERNAL_CALLS` | symbol → external symbol |
| `EXTERNAL_EXTENDS` | symbol → external symbol |
| `EXTERNAL_IMPLEMENTS` | symbol → external symbol |
| `EXTERNAL_IMPORTS` | file → external symbol |

### Derived structure

| Relationship | From → to | Meaning |
|---|---|---|
| `MEMBER_OF` | symbol → community | Functional community membership. |
| `WORKFLOW_CALL` | workflow → symbol | An ordered call included in a workflow. |
| `WORKFLOW_OUTCOME` | workflow → symbol | An outcome reached by a workflow. |
| `WORKFLOW_TRAVERSES` | workflow → community | A community crossed by a workflow. |
| `CHILD_OF` | community → community | Community hierarchy. |
| `COMMUNITY_CROSSING` | community → community | A resolved connection between functional boundaries. |

### Change and file relationships

| Relationship | From → to | Meaning |
|---|---|---|
| `CO_CHANGED` | symbol → symbol | Symbols changed together in repository history. |
| `FILE_CO_CHANGED` | file → file | Files changed together in repository history. |
| `FILE_DEPENDS_ON` | file → file | A resolved file dependency. |

## Common properties

- `CODE_SYMBOL`: `name`, `kind`, `language`, `file_path`, source ranges, `signature`, `docstring`, `scope`, `content`, and content or structural hashes.
- `COMMUNITY`: `label`, `summary`, `size`, `hierarchy_level`, and canonical parent identifiers.
- `WORKFLOW`: `label`, `description`, entry-point fields, `max_depth`, callsite counts, and resolution counts.
- `FILE`: `path`, `language`, `content_hash`, and `line_count`.
- `DOCUMENT`: `path`, `chunk_index`, `title`, `heading_trail`, `referenced_symbol_uids`, and `source_type`.
- Relationship records: `source_uid`, `target_uid`, `relationship`, source location, `centrality_score`, and `step_index`.

Use `nbx schema` when you need the complete property list for your installed version.

## Query examples

### Find every caller of a symbol

```bash
nbx query '
MATCH (caller:CODE_SYMBOL)-[r:CALLS]->(target:CODE_SYMBOL)
WHERE target.name = "refreshToken"
RETURN caller.name AS caller, type(r) AS relationship
LIMIT 50
'
```

### Find a symbol's functional community

```bash
nbx query '
MATCH (symbol:CODE_SYMBOL)-[:MEMBER_OF]->(community:COMMUNITY)
WHERE symbol.name = "refreshToken"
RETURN symbol.name, community.label, community.size
LIMIT 20
'
```

### Read an ordered workflow

```bash
nbx query '
MATCH (workflow:WORKFLOW)-[step:WORKFLOW_CALL]->(symbol:CODE_SYMBOL)
WHERE workflow.label CONTAINS "Token"
RETURN workflow.label, step.step_index, symbol.name, symbol.file_path
ORDER BY step.step_index
LIMIT 50
'
```

## Supported Cypher

`nbx query` supports the subset needed for bounded graph reads:

- Clauses: `MATCH`, `WHERE`, `WITH`, `UNWIND`, `RETURN`, `ORDER BY`, `SKIP`, `LIMIT`, and `DISTINCT`.
- Comparison and logic: `=`, `<>`, `<`, `>`, `<=`, `>=`, `AND`, `OR`, `NOT`, `IN`, `CONTAINS`, `STARTS WITH`, `ENDS WITH`, `LIKE`, `ILIKE`, `IS NULL`, and `IS NOT NULL`.
- Scalar functions: `toLower`, `toUpper`, and `type`.
- Aggregates: `count`, `sum`, `avg`, `min`, `max`, and `collect`.

Not currently supported: `OPTIONAL MATCH`, `CASE`, regex matching with `=~`, `XOR`, `all()` / `any()` / `none()` predicates, path variables, and path functions.

## Keep queries bounded

Add `LIMIT` while exploring, bind relationship variables when returning `type(r)` or edge properties, and qualify labels and property names exactly as `nbx schema` reports them.

## Next

- [CLI reference](/reference/cli)
- [How Noodlbox works](/concepts/how-noodlbox-works)
- [Debug a failure](/guides/debug-a-failure)

---

---
title: "Trust and Freshness"
description: "Understand local data, analysis freshness, and coverage boundaries."
url: "https://docs.noodlbox.io/concepts/trust-and-freshness"
hierarchy: ["Concepts","Trust and Freshness"]
lastVerified: "2026-08-27"
productVersion: "2.1.0"
audience: "all"
contentType: "concept"
status: "stable"
keywords: ["local data","freshness","coverage","security"]
source: "concepts/trust-and-freshness.mdx"
---

# Trust and Freshness

## Local by default

Local commands read the selected repository and its local Noodlbox box. Source stays on the machine unless you explicitly target or synchronize an external box.

Use exact targets such as `--box`, `--repo`, or `--hub` when the current directory is not the intended source.

## Check freshness

The structural model reflects the last analysis, while source files may continue changing:

```bash
nbx status --check
```

Run analysis again when status reports stale input or when new source must be included:

```bash
nbx analyze .
```

Use `nbx diff` to inspect working-tree changes against the analyzed baseline.

## Qualify coverage

An absent result does not prove that code does not exist. Generated code, dynamic dispatch, unsupported syntax, and language support boundaries can limit what analysis resolves.

For important negative claims:

1. Check status.
2. Inspect the relevant source.
3. State the files or language scope you verified.

## Destructive commands

Commands such as `nbx delete`, `nbx reset`, `nbx migrate`, and some configuration operations change Noodlbox-managed state. Preview migrations and read command help before automating them.

## Next

- [Compatibility and limits](/help/compatibility)
- [Troubleshooting](/help/troubleshooting)

---

---
title: "Connect Your Agent"
description: "Configure Noodlbox for Claude Code, Cursor, Codex, or OpenCode."
url: "https://docs.noodlbox.io/integrations"
hierarchy: ["Integrations"]
lastVerified: "2026-09-08"
productVersion: "2.1.0"
audience: "agent-user"
contentType: "integration"
status: "stable"
keywords: ["agents","configure","Claude Code","Cursor","Codex","OpenCode"]
source: "integrations.mdx"
---

# Connect Your Agent

Run the configurator after installing Noodlbox:

```bash
nbx configure
nbx configure status
```

The configurator detects supported coding clients and installs their current Noodlbox instructions and automation under your home directory. It does not add integration files to the repository. Restart the client after setup.

## Claude Code

`nbx configure` uses Claude Code's native skill and lifecycle-hook systems. It makes two managed changes:

- Writes the versioned Noodlbox skill to `~/.claude/skills/nbx/SKILL.md`. The skill teaches Claude when and how to use `nbx map`, `search`, `def`, and `diff`.
- Merges Noodlbox hook groups into `~/.claude/settings.json`. Existing settings and hooks are preserved.

The installed hooks are:

| Claude Code hook | Matcher | What Noodlbox does |
| --- | --- | --- |
| `SessionStart` | New startup sessions | Adds Noodlbox usage guidance and the current graph schema. For an analyzed repository, it also reports graph freshness. |
| `PreToolUse` | `Grep` or `Bash` | In an analyzed repository, augments eligible searches with structural context. A bare symbol name routes to `nbx def`; a plain-language query routes to `nbx search`. Before a recognized `git commit`, it also supplies a structural commit audit. |
| `PreToolUse` | `Edit` or `Write` | Supplies a working-tree structural audit while Claude edits, limited to one audit per 60-second editing window. |
| `PostToolUse` | All tools | Normally does nothing. After a completed `git commit`, it starts a debounced background analysis so the graph follows the new `HEAD`. |

Automatic search augmentation runs only when Claude is working inside an analyzed box. Regexes, paths, globs, and patterns that do not map cleanly to a symbol or plain-language query are left alone. The hooks are bounded and fail open: if Noodlbox has no useful result, the graph is unavailable, or a hook times out, Claude's original tool call continues.

Restart Claude Code after configuration. Then verify the installed files and exercise the real hook channel from inside an analyzed repository:

```bash
nbx configure status
nbx hook doctor
```

Re-run `nbx configure --force` after an upgrade if the integration is reported as outdated. Removal for all configured clients is covered under [What gets installed](#what-gets-installed).

## Cursor

`nbx configure` connects Cursor through the shared Agent Skill, one shell hook, and one setup command:

- Writes the versioned skill to `~/.agents/skills/nbx/SKILL.md`.
- Merges a `beforeShellExecution` entry into `$CURSOR_CONFIG_DIR/hooks.json`, or `~/.cursor/hooks.json` when `CURSOR_CONFIG_DIR` is not set. Existing hooks are preserved.
- Writes `/setup-noodlbox` to the same config directory under `commands/setup-noodlbox.md`.

Cursor has no global rules file. Run `/setup-noodlbox` once in each repository where you want the Noodlbox instructions to apply. The command creates `.cursor/rules/noodlbox.mdc` in that repository with `alwaysApply: true`; the shell hook reminds you when an analyzed repository is missing it.

The `beforeShellExecution` hook inspects search-shaped shell commands such as `grep`, `rg`, `ag`, and `ack`. In an analyzed repository, a bare symbol name routes to `nbx def` and a plain-language phrase routes to `nbx search`, giving Cursor structural context before the shell command runs. Regexes, paths, globs, and unrelated commands run normally without augmentation. The hook always allows the original command and fails open when Noodlbox is unavailable or has nothing useful to add.

Restart Cursor and reopen the repository after configuration, then run `/setup-noodlbox` once for that project.

## Codex

`nbx configure` connects Codex through the shared Agent Skill, global rules, and trusted lifecycle hooks:

- Writes the versioned skill to `~/.agents/skills/nbx/SKILL.md`.
- Adds a marked Noodlbox section to `$CODEX_HOME/AGENTS.md`, or `~/.codex/AGENTS.md` when `CODEX_HOME` is not set. Existing rules outside that section are preserved.
- Merges Noodlbox hook groups into `$CODEX_HOME/hooks.json`, or `~/.codex/hooks.json` by default. Existing hook groups are preserved.

The installed hooks are:

| Codex hook | Matcher | What Noodlbox does |
| --- | --- | --- |
| `SessionStart` | New startup sessions | Adds Noodlbox usage guidance and the current graph schema. For an analyzed repository, it also reports graph freshness. |
| `PreToolUse` | `Bash` | Augments eligible `grep`-style shell searches with `nbx def` or `nbx search` context. Before a recognized `git commit`, it supplies a structural commit audit. |

Codex does not currently receive the Claude-specific `Edit`/`Write` mid-edit audit or `PostToolUse` background refresh. Use `nbx diff` to inspect working-tree impact and `nbx analyze` when you want an explicit committed-graph refresh.

Codex will not run a newly written hook until you trust it. After configuration, start a new Codex session and approve the hook review prompt, or open `/hooks` inside Codex and approve the Noodlbox hooks there. Trust is tied to the hook content, so an updated hook may require approval again. The hooks are bounded and fail open once enabled.

## OpenCode

`nbx configure` connects OpenCode through the shared Agent Skill, global rules, and an auto-loaded local plugin:

- Writes the versioned skill to `~/.agents/skills/nbx/SKILL.md`.
- Adds a marked Noodlbox section to `~/.config/opencode/AGENTS.md`. Existing rules outside that section are preserved.
- Writes the plugin to `~/.config/opencode/plugins/noodlbox.ts`; no `opencode.json` plugin entry is required.
- Merges `@opencode-ai/plugin` into `~/.config/opencode/package.json`, preserving other keys and dependencies. OpenCode resolves that dependency when it starts.

The plugin makes semantic search, exact graph queries, repository listing, analysis, and local index removal available inside OpenCode. Each action delegates to the local `nbx` CLI in the current repository; the public command surface remains `nbx search`, `query`, `list`, `analyze`, and `delete`.

It also installs two automatic hook paths:

| OpenCode hook | When it runs | What Noodlbox does |
| --- | --- | --- |
| `chat.message` | First message in each session | Adds the analyzed-repository list, graph schema, and short usage guidance. OpenCode loads the global `AGENTS.md` rules separately, so they are not duplicated here. |
| `tool.execute.after` | After `grep` or a search-shaped `bash` command | Appends `nbx search` results to the original tool output when the pattern is a plain term or phrase. Regexes and path-shaped searches are left unchanged. |

Automatic plugin work is time-bounded and fail open: an unavailable CLI, empty result, or timeout leaves the original OpenCode interaction unchanged. Restart OpenCode after configuration so it loads the plugin and resolves its SDK dependency.

## What gets installed

`nbx configure` owns its generated skill, command, and plugin files. For shared JSON and Markdown files, it merges only Noodlbox entries or marked sections and preserves unrelated user configuration. Avoid copying paths or configuration snippets between clients; their formats and lifecycle events differ.

The shared `~/.agents/skills/nbx/SKILL.md` is reused by Cursor, Codex, and OpenCode. Claude Code receives its own copy because it reads `~/.claude/skills/` instead.

Check the current state at any time:

```bash
nbx configure status
```

If an integration is missing or outdated:

```bash
nbx configure --force
```

To remove the configured integrations:

```bash
nbx configure uninstall
```

Uninstall removes Noodlbox-managed skills, commands, rule sections, hook entries, and plugin files for all configured clients. It edits shared configuration surgically; the generic `@opencode-ai/plugin` dependency added to OpenCode's `package.json` is left in place.

## Manual skill fallback

When the configurator cannot update client settings, print the current agent instructions and install them using the client's supported skill mechanism:

```bash
nbx --skill
```

This installs instructions only. Prefer `nbx configure` for the complete supported setup.

## Next

- [Run the quick start](/start-here)
- [Explore a codebase](/guides/explore-an-unfamiliar-codebase)
- [Troubleshooting](/help/troubleshooting#agent-integration-is-missing-or-outdated)

---

---
title: "CLI Reference"
description: "The essential nbx commands and target controls."
url: "https://docs.noodlbox.io/reference/cli"
hierarchy: ["Reference","CLI Reference"]
lastVerified: "2026-08-27"
productVersion: "2.1.0"
audience: "developer"
contentType: "reference"
status: "stable"
keywords: ["nbx CLI","command reference","analyze","search"]
source: "reference/cli.mdx"
---

# CLI Reference

Use `nbx <command> --help` for the exact options supported by your installed version.

## Core workflow

| Command | Purpose |
|---|---|
| `nbx analyze [path]` | Build or refresh the local structural model. |
| `nbx search "<query>"` | Retrieve task-relevant workflows and definitions. |
| `nbx def <name-or-uid>` | Inspect one symbol with callers and dependencies. |
| `nbx query "<cypher>"` | Run a read-only graph query. |
| `nbx map` | Show communities and execution workflows. |
| `nbx diff` | Compare working-tree structure with the analyzed baseline. |
| `nbx verify --digest` | Summarize structural verification findings. |

```bash
nbx analyze .
nbx search "auth refresh flow"
nbx def refreshToken
```

## Setup and targeting

| Command | Purpose |
|---|---|
| `nbx init [path]` | Create box configuration. |
| `nbx repo <subcommand>` | Manage repositories inside a box. |
| `nbx list` | List local boxes. |
| `nbx status` | Inspect freshness and integrity. |
| `nbx configure` | Configure supported coding agents. |
| `nbx auth` | Manage authentication. |

Read commands use the current box by default. Common target controls are:

- `--box <ID|PATH|NAME>` — use another local box.
- `--repo <ALIAS>` — select one repository in the box.
- `--hub <REF>` — explicitly read an external Hub target.

## Maintenance

| Command | Purpose |
|---|---|
| `nbx update` | Update the CLI. |
| `nbx migrate --dry-run` | Preview metadata migration. |
| `nbx doctor` | Diagnose installation and local state. |
| `nbx cache` | Inspect or manage caches. |
| `nbx delete` | Delete a selected box. |
| `nbx reset` | Reset Noodlbox-managed state. |
| `nbx feedback` | Prepare a support report. |
| `nbx version` | Print the installed version. |

`delete`, `reset`, migration, and configuration commands can change managed state. Read their command help before automation.

## Output

- `--json` requests machine-readable output where supported.
- `-h`, `--help` prints command help.
- `-V`, `--version` prints the CLI version.

## Next

- [Configuration](/reference/configuration)
- [Troubleshooting](/help/troubleshooting)

---

---
title: "Configuration"
description: "Configure boxes, repositories, coding agents, and CI behavior."
url: "https://docs.noodlbox.io/reference/configuration"
hierarchy: ["Reference","Configuration"]
lastVerified: "2026-08-27"
productVersion: "2.1.0"
audience: "operator"
contentType: "reference"
status: "stable"
keywords: ["configuration",".nbx","agents","CI"]
source: "reference/configuration.mdx"
---

# Configuration

Most projects need no manual configuration:

```bash
nbx analyze .
nbx configure
```

## Box configuration

`nbx init` creates explicit box configuration when defaults are not enough:

```bash
nbx init --name my-box --alias app
```

Use `nbx repo` to manage multiple repositories inside one box:

```bash
nbx repo add ./apps/api --as api
nbx repo add ./apps/web --as web
nbx repo list
```

Repository aliases must be unique. Changing an alias changes repository identity and requires re-analysis.

## Agent configuration

`nbx configure` detects and configures supported coding clients:

```bash
nbx configure
nbx configure status
```

Use `nbx configure --force` to replace outdated managed assets. Avoid editing generated files by hand.

## CI

- `nbx init --ci` requires existing box configuration and lock state.
- `nbx status --check` exits non-zero when analysis is stale or integrity checks fail.
- `nbx configure -y` accepts integration defaults without prompts.
- `nbx verify --digest --audience agent` produces a concise verification report.

## External targets

Local reads use the current box. Use `--box`, `--repo`, or `--hub` explicitly when another target is intended.

Hub synchronization is opt-in:

```bash
nbx sync enable
nbx sync disable
```

Review and commit changes to `.nbx/nbx.toml` when synchronization intent changes.

## Migrations

Preview metadata migrations before applying them:

```bash
nbx migrate --dry-run
```

## Next

- [CLI reference](/reference/cli)
- [Connect your agent](/integrations)
- [Trust and freshness](/concepts/trust-and-freshness)

---

---
title: "Compatibility and Limits"
description: "Supported languages, coding agents, and important analysis boundaries."
url: "https://docs.noodlbox.io/help/compatibility"
hierarchy: ["Help","Compatibility and Limits"]
lastVerified: "2026-09-01"
productVersion: "2.1.0"
audience: "all"
contentType: "help"
status: "stable"
keywords: ["compatibility","supported languages","coding agents","limitations"]
source: "help/compatibility.mdx"
---

# Compatibility and Limits

The command examples target Noodlbox `2.1.0`; the language list reflects current support.

## Languages

Noodlbox analyzes the following source languages and file types:

| Language | Support | File extensions |
| --- | --- | --- |
| TypeScript | Stable | `.ts`, `.tsx`, `.mts`, `.cts` |
| JavaScript | Stable | `.js`, `.jsx`, `.mjs`, `.cjs` |
| Python | Stable | `.py`, `.pyi` |
| Java | Stable | `.java` |
| Go | Beta | `.go` |
| Rust | Preview | `.rs` |

Stable support does not mean every generated construct, macro expansion, runtime import, or dynamic dispatch pattern resolves perfectly. Beta and preview results should be verified against source before making exhaustive claims.

## Coding agents

`nbx configure` supports Claude Code, Cursor, Codex, and OpenCode. The configurator reports each detected client as current, outdated, or missing:

```bash
nbx configure status
```

Client versions evolve independently. A current status report is more reliable than a copied filesystem path.

## Important limits

- Noodlbox models source structure; it does not execute code or observe runtime state.
- Results reflect the last analysis plus the command's supported working-tree behavior.
- An empty result is not proof that code does not exist.
- Generated code, dynamic behavior, unsupported syntax, and language boundaries can create gaps.
- Search retrieves code context. Standalone project-document search is not part of the current CLI.
- Noodlbox does not replace source review, tests, logs, traces, or a debugger.

## Check your installation

```bash
nbx version
nbx status --check
nbx configure status
```

For a newer CLI, use `nbx --help` and `nbx <command> --help` as the syntax authority.

## Next

- [Trust and freshness](/concepts/trust-and-freshness)
- [Troubleshooting](/help/troubleshooting)

---

---
title: "Troubleshooting"
description: "Fix common installation, analysis, search, and agent setup problems."
url: "https://docs.noodlbox.io/help/troubleshooting"
hierarchy: ["Help","Troubleshooting"]
lastVerified: "2026-08-27"
productVersion: "2.1.0"
audience: "operator"
contentType: "help"
status: "stable"
keywords: ["troubleshooting","doctor","stale analysis","agent setup"]
source: "help/troubleshooting.mdx"
---

# Troubleshooting

Start with the health check:

```bash
nbx doctor --verbose
```

## Command not found

Restart your shell, then check:

```bash
command -v nbx
nbx version
```

If `nbx` is still unavailable, run the installer again.

## Box not found

Run `nbx list` and confirm you are inside the intended project. Analyze the project if it has no box:

```bash
nbx analyze .
```

## Analysis is stale

```bash
nbx status --check
nbx analyze .
```

Use `nbx analyze --force` only when normal analysis does not repair the mismatch.

## Search is empty or irrelevant

Confirm the selected box, make the query more concrete, and choose an intent when useful:

```bash
nbx search "expired session retry" --intent debug
```

Inspect source before treating an empty result as proof of absence.

## Definition is ambiguous

Several symbols may share a name. Add a file path or use the UID returned by `nbx def`:

```bash
nbx def validate --file src/auth/validator.ts
```

## Agent integration is missing or outdated

```bash
nbx configure --force
nbx configure status
```

Restart the coding client after configuration.

## A graph query fails

Inspect the current schema, bind every relationship variable you return, and add a limit:

```bash
nbx schema
```

## Before resetting

`nbx reset --force` removes Noodlbox-managed state. It is not a general first repair step. Use automatic fixes offered by `nbx doctor --fix` first.

## Report a problem

Run `nbx feedback` and include the installed version, failing command, redacted output, target box, and reproduction steps.

---

---
title: "Upgrade and Migrate"
description: "Update the CLI, migrate box metadata, and refresh coding-agent configuration."
url: "https://docs.noodlbox.io/help/upgrade-and-migrate"
hierarchy: ["Help","Upgrade and Migrate"]
lastVerified: "2026-08-27"
productVersion: "2.1.0"
audience: "operator"
contentType: "help"
status: "stable"
keywords: ["upgrade","migrate","update","agent assets"]
source: "help/upgrade-and-migrate.mdx"
---

# Upgrade and Migrate

## Update the CLI

```bash
nbx version
nbx update
nbx version
```

## Preview metadata changes

```bash
nbx migrate --dry-run
```

Review unexpected changes before applying migration.

## Refresh the model

```bash
nbx analyze .
nbx status --check
```

## Refresh coding-agent setup

```bash
nbx configure --force
nbx configure status
```

Restart the active coding client after managed assets change.

## Verify the result

```bash
nbx search "auth refresh flow"
nbx doctor
```

If a migration preview is unclear, do not apply it. Preserve the output and run `nbx feedback`.

## Release notes

See [Noodlbox releases](https://github.com/noodlbox/noodlbox-app/releases) for version-specific changes.

---

---
title: "Noodlbox"
description: "The nbx CLI compiles your codebase into a local knowledge graph your agents can query. LLM-free."
url: "https://docs.noodlbox.io/"
hierarchy: ["Home"]
lastVerified: "2026-09-02"
productVersion: "2.1.0"
audience: "all"
contentType: "home"
status: "stable"
keywords: ["context infrastructure","context compiler","code graph","coding agents","nbx"]
source: "index.mdx"
---

# Noodlbox

Noodlbox is context infrastructure for coding agents.

The nbx CLI compiles your codebase into a local knowledge graph your agents can query. LLM-free.

## Start here

- [Install Noodlbox](/start-here/install)
- [Run the quick start](/start-here)
- [Connect your coding agent](/integrations)

## The shortest path

Install Noodlbox and complete the guided setup:

```bash
curl -fsSL https://install.noodlbox.io/install.sh | bash
```

The installer starts onboarding. Then open a repository and ask your agent to use Noodlbox. The repository is initialized and analyzed on first use.

## Learn more

- [Explore a codebase](/guides/explore-an-unfamiliar-codebase)
- [Understand how Noodlbox works](/concepts/how-noodlbox-works)
- [CLI reference](/reference/cli)
- [Troubleshooting](/help/troubleshooting)