Connect Your Agent

Run the configurator after installing Noodlbox:

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:

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.

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:

nbx configure status

If an integration is missing or outdated:

nbx configure --force

To remove the configured integrations:

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:

nbx --skill

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