# Documentation (/)
noodlbox gives your AI agent a semantic understanding of your codebase—not just files, but how code actually works together.
**Works with:** Claude Code, Cursor, Codex, OpenCode, and any MCP-compatible agent.
Install in 2 minutes and start exploring your codebase
## How It Works
Your agent connects to noodlbox via MCP. When you ask about your code, noodlbox provides the precise context needed—no more guessing, no more token waste.
```
"How does the authentication flow work?"
"What would break if I changed this function?"
"Find all code related to payment processing"
```
## Explore the Docs
Installation, setup, and your first analysis
Guided workflows for common development tasks
Code exploration, debugging, and change analysis
Understanding communities, processes, and the knowledge graph
Tools and resources available to your agent
## Key Concepts
| Concept | What it means |
| -------------------- | ----------------------------------------------- |
| **Knowledge Graph** | Your code as a queryable graph of relationships |
| **Communities** | Clusters of related code (auto-detected) |
| **Processes** | Execution flows through your application |
| **Impact Detection** | What breaks when you change something |
[Deep dive into the platform →](/platform)
# Getting Started (/getting-started)
This guide will help you get noodlbox set up and start exploring your codebase.
## Prerequisites
* **Supported platforms:**
* macOS (Apple Silicon)
* Linux (x64)
* Linux (ARM64)
* An MCP-compatible client (e.g., Claude Code, Cursor, Codex, OpenCode)
## Quick Start
### How It Works
Your agent has MCP tools to analyze, delete, search, and query repositories. You just need to install once.
### Install the CLI
Sign in to [noodlbox.io](https://noodlbox.io) and copy the install command from the dashboard.
The installer runs `noodl init` automatically, which:
* Authenticates with noodlbox (opens browser)
* Configures MCP for your agents (Claude Code, Cursor, Codex)
After installation, ask your agent:
```
"Analyze this codebase"
"What communities exist here?"
"How does the authentication flow work?"
```
The agent calls `noodlbox_analyze` automatically when needed.
**Already installed?** Run `noodl init` to set up authentication and agent configuration.
### When to Use Manual
* CI/CD pipelines and automation scripts
* Batch operations across multiple repositories
* Explicit control over when analysis happens
* Environments without interactive authentication
### Install the CLI
Sign in to [noodlbox.io](https://noodlbox.io) and copy the install command from the dashboard.
The installer authenticates and configures MCP automatically.
### Analyze your codebase
```bash
noodl analyze .
```
This extracts code entities and relationships, building a knowledge graph.
### Integrate your Agents
```bash
noodl configure
```
This sets up MCP, skills, and hooks for Claude Code, Cursor, and Codex.
Install the noodlbox plugin:
```bash
claude plugin marketplace add noodlbox/noodlbox-claude-plugins
claude plugin install noodlbox@noodlbox
```
The plugin provides MCP, skills, and slash commands like `/noodlbox:setup-noodlbox`.
**One-Click:** [Add to Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=noodlbox\&config=eyJjb21tYW5kIjoibm9vZGwiLCJhcmdzIjpbIm1jcCJdfQ==)
**Manual:** Add to `.cursor/mcp.json`:
```json
{
"mcpServers": {
"noodlbox": {
"command": "noodl",
"args": ["mcp"]
}
}
}
```
Add to `~/.codex/config.toml`:
```toml
[mcp_servers.noodlbox]
command = "noodl"
args = ["mcp"]
```
Add to `~/.config/opencode/opencode.json`:
```json
{
"mcp": {
"noodlbox": {
"type": "local",
"command": ["noodl", "mcp"]
}
}
}
```
After setup, ask your agent:
```
"What communities exist in this codebase?"
"How does the authentication flow work?"
"What would be impacted if I changed this function?"
```
## What You Can Do
Research and gather context before implementing
Track down bugs by tracing execution paths
Review PRs for quality, safety, and impact
## Troubleshooting
| Problem | Solution |
| ------------------ | ---------------------------------------------------------------------------- |
| Connection failed | Run `noodl status` to check authentication |
| No repositories | Agent-first: Ask agent to analyze. Manual: Run `noodl analyze /path/to/repo` |
| Config not applied | Restart your agent, or run `noodl reset` to start fresh |
| Auth expired | Run `noodl auth` to re-authenticate |
## Next Steps
* [CLI Reference](/reference/cli-reference) - Complete command reference
* [Claude Code Plugin](/integrations/claude-code-plugin) - Commands, skills, and agents
* [Explore the platform](/platform) - Understand communities, processes, and the knowledge graph
* [MCP Tools & Resources](/mcp) - What your agent can access
# MCP Server (/mcp)
The MCP (Model Context Protocol) server connects noodlbox to agents like Claude Code, Cursor, Codex, and OpenCode, enabling intelligent code exploration and analysis.
## What is MCP?
MCP is a protocol that allows agents to access external tools and data. The noodlbox MCP server exposes your code knowledge graph through:
* **Tools** - Execute operations like queries and searches
* **Resources** - Access structured data like maps and schemas
## Quick Setup
The installer runs `noodl init` automatically, which configures MCP for all your agents. The MCP server uses **STDIO transport** - your agent launches it automatically when needed.
**Agent-first workflow:** After setup, your agent can analyze repositories directly via MCP tools - no CLI commands needed.
For manual configuration:
Install the [noodlbox plugin](https://github.com/noodlbox/noodlbox-claude-plugins):
```bash
claude plugin marketplace add noodlbox/noodlbox-claude-plugins
claude plugin install noodlbox@noodlbox
```
The plugin auto-updates when you run `noodl update --install`.
**Path:** `.cursor/mcp.json`
```json
{
"mcpServers": {
"noodlbox": {
"command": "noodl",
"args": ["mcp"]
}
}
}
```
**Path:** `~/.codex/config.toml`
```toml
[mcp_servers.noodlbox]
command = "noodl"
args = ["mcp"]
```
**Path:** `~/.config/opencode/opencode.json`
```json
{
"mcp": {
"noodlbox": {
"type": "local",
"command": ["noodl", "mcp"]
}
}
}
```
[Full setup guide →](/getting-started#manual-configuration)
## Tools
The MCP server provides tools for interacting with noodlbox.
### Query Tools
Find relevant code with natural language queries
Get 360-degree context for a symbol: references, community, docs
Search documentation with semantic, linked, or hybrid modes
Execute graph queries to explore code relationships
Analyze git changes to understand impact
### Refactoring Tools
Multi-file coordinated rename with confidence-tagged edits
### Management Tools
Index a repository and build its knowledge graph
Remove an analyzed repository from noodlbox
## Resources
Access structured data through MCP resources using `@noodlbox:uri` syntax:
List analyzed repositories
Knowledge graph structure
Communities, processes, and navigation
## Tools vs Resources
| Use | When |
| ------------- | --------------------------------------------------------- |
| **Tools** | Custom queries, searching patterns, analyzing impact |
| **Resources** | Structured data, exploring communities, viewing processes |
## Example Session
```
You: "Show me my repositories"
→ Uses @noodlbox:repository://list
You: "What communities are in owner/my-app?"
→ Uses @noodlbox:map://owner/my-app
You: "Find code related to authentication"
→ Uses noodlbox_query_with_context tool
You: "Show me everything about the authenticateUser function"
→ Uses noodlbox_symbol_context tool
You: "Rename getUserById to findUserById"
→ Uses noodlbox_rename_symbol tool
You: "What would be affected if I change the login function?"
→ Uses noodlbox_detect_impact tool
```
## Security
MCP operations are:
* **Authenticated** - Requires valid authentication via `noodl auth`
* **Local** - Data stays on your machine
* **Code-safe** - Cannot modify your source code
Management tools (`analyze`, `delete`) modify the knowledge graph but never touch your source files.
## Learn More
* [Setup Guide](/getting-started) - Installation and configuration
* [Context Search](/mcp/tools/context-search) - Natural language code search
* [Cypher Query](/mcp/tools/cypher-query) - Graph query examples
# Claude Code Plugin (/integrations/claude-code-plugin)
The noodlbox plugin for Claude Code provides skills, commands, and hooks that enable intelligent codebase exploration and analysis.
## Installation
### Automatic Setup (Recommended)
The easiest way to install the plugin is through the noodlbox CLI:
```bash
noodl configure
```
This automatically:
* Installs the noodlbox Claude Code plugin
* Configures MCP server connection
If the plugin is already installed, `noodl configure --force` will update it to the latest version.
### Manual Setup
If you prefer manual installation:
```bash
claude plugin marketplace add noodlbox/noodlbox-claude-plugins
claude plugin install noodlbox@noodlbox
```
The plugin auto-updates when you run `noodl update`.
## Plugin Architecture
The plugin provides two types of content:
| Type | Purpose | Execution |
| ------------ | ----------------------------------------- | ---------------------------------- |
| **Skills** | Knowledge Claude uses for decision-making | Internalized by Claude |
| **Commands** | Slash commands you invoke | Triggered with `/noodlbox:command` |
## Commands
Plugin commands use the `/noodlbox:command` format:
| Plugin Command | Description |
| -------------------------- | --------------------------------------------------- |
| `/noodlbox:setup-noodlbox` | Set up noodlbox MCP context for the current project |
### `/noodlbox:setup-noodlbox`
Set up noodlbox MCP context for the current project.
```
/noodlbox:setup-noodlbox
```
This command:
1. Reads the `setup://` MCP resource to get noodlbox context
2. Creates or updates `CLAUDE.md` at the project root with noodlbox configuration
Use this in new projects to give Claude full context about noodlbox tools and resources.
## Skills
The plugin includes the `noodlbox-setup` skill for initializing noodlbox context in a project. It's automatically loaded with the plugin.
## CLI Depth Control
The CLI supports depth control for query and search commands:
```bash
# Get symbol definitions only (default)
noodl query "authentication flow" --depth definitions
# Get symbols with all relationships
noodl query "error handling" --depth full
noodl search "payments" -d full
```
| Depth | Description |
| ----------------------- | ------------------------------------------------------ |
| `definitions` (default) | Symbol signatures and full body content |
| `full` | Symbols plus all relationships (calls, imports, edges) |
## Workflow: First-Time Setup
For a new repository:
```
1. noodl analyze /path/to/repo # Analyze codebase
2. /noodlbox:setup-noodlbox # Set up noodlbox context
```
## Workflow: Pre-Commit Review
Before committing changes, use the `noodlbox_detect_impact` MCP tool:
```
Use noodlbox_detect_impact to analyze my staged changes
```
Review impacted processes and plan testing based on impact.
## Labels File (Optional)
You can manually create a `.noodlbox/labels.json` file to provide human-readable names:
```json
{
"version": "1.0",
"repository": "owner/my-app",
"communities": {
"abc123": {
"label": "Authentication System",
"description": "Handles login, token validation, sessions"
}
},
"processes": {
"proc_001": {
"label": "User Login Flow",
"description": "Validates credentials, creates session"
}
}
}
```
**Used by:**
* `noodl` CLI commands
* MCP resources (`@noodlbox:map://`)
* Architecture generation
## Updating the Plugin
### Automatic Update (Recommended)
The plugin is automatically updated when you update the CLI:
```bash
noodl update
```
Or force update via configure:
```bash
noodl configure --force
```
### Manual Update
```bash
claude plugin marketplace update noodlbox
claude plugin update noodlbox@noodlbox
```
## Related
* [Getting Started](/getting-started) - Installation and MCP setup
* [Change Analysis](/workflows/change-analysis) - Dependencies and impact workflow
* [Code Exploration](/workflows/code-exploration) - Exploration patterns
# Integrations (/integrations)
Noodlbox integrates into your AI coding workflow through multiple channels, from fully automatic context injection to explicit tool calls.
## Integration Matrix
| Integration | Type | When it fires | What it does |
| ------------------------------------------------- | --------- | ----------------------- | ------------------------------------------------ |
| [Session Hooks](/integrations/session-hooks) | Automatic | Conversation start | Injects architecture context |
| [Search Hooks](/integrations/search-hooks) | Automatic | Glob/Grep/Bash searches | Adds semantic context to searches |
| [MCP Tools](/mcp) | On demand | When invoked | Explicit queries for context, impact, and graphs |
| [Skills](/integrations/claude-code-plugin#skills) | Automatic | Based on your question | Guides Claude on which tools to use |
## Automatic vs On-Demand
**Automatic integrations** work without any action from you:
* **Session hooks** inject context when a conversation begins
* **Search hooks** enhance search tools with architectural context
* **Skills** help Claude decide when to use Noodlbox tools
**On-demand integrations** are invoked explicitly:
* **MCP tools** for direct queries when you need specific information
* **Commands** like `/noodlbox:setup-noodlbox` for specific workflows
## Getting Started
With the Noodlbox CLI, configuration is automatic:
```bash
noodl configure
```
This sets up your selected agents with:
* MCP server connection
* Skills (intelligent tool selection)
* Hooks (automatic context injection where supported)
For agents not directly supported, see [Other Agents](/integrations/other-agents) for manual MCP configuration.
## Platform Support
Noodlbox supports multiple AI coding assistants with platform-specific integrations:
| Platform | Session Hook | Search Hook | Context Injection | MCP Tools |
| ------------------------------------------ | ----------------- | ---------------------- | ------------------- | --------- |
| Claude Code | ✅ SessionStart | ✅ PreToolUse | ✅ additionalContext | ✅ |
| Cursor | ❌ | ✅ beforeShellExecution | ✅ agent\_message | ✅ |
| OpenCode | ✅ session.created | ✅ tool.execute.before | ✅ chat.message | ✅ |
| Codex | ❌ | ❌ | ❌ | ✅ |
| [Other Agents](/integrations/other-agents) | ❌ | ❌ | Manual (AGENTS.md) | ✅ |
## Skills Distribution
Skills are centralized in the noodlbox plugins repository and distributed to each platform:
| Platform | Skills Location |
| ------------ | ---------------------------------------- |
| Claude Code | Bundled with the plugin |
| Cursor | Installed to `~/.cursor/skills/` |
| OpenCode | Installed to `~/.config/opencode/skill/` |
| Codex | Installed to `~/.codex/skills/` |
| Other Agents | Manual setup via `setup://` resource |
All platforms receive the `noodlbox-setup` skill for initializing noodlbox context in a project.
# OpenCode Plugin (/integrations/opencode-plugin)
The noodlbox plugin for OpenCode provides automatic semantic search augmentation and MCP tools for intelligent codebase exploration.
## Installation
### Automatic Setup (Recommended)
The easiest way to install the plugin is through the noodlbox CLI:
```bash
noodl configure opencode
```
This automatically:
* Copies the plugin to `~/.config/opencode/plugin/noodlbox/`
* Copies skills to `~/.config/opencode/skill/`
* Configures MCP server connection in `~/.config/opencode/opencode.json`
### Manual Setup
If you prefer manual installation:
1. Copy the plugin files:
```bash
mkdir -p ~/.config/opencode/plugin/noodlbox
cp -r platforms/opencode/plugin/* ~/.config/opencode/plugin/noodlbox/
cp -r shared/hooks ~/.config/opencode/plugin/noodlbox/shared/
```
2. Copy skills:
```bash
cp -r shared/skills/* ~/.config/opencode/skill/
```
3. Add MCP config to `~/.config/opencode/opencode.json`:
```json
{
"mcp": {
"noodlbox": {
"type": "local",
"command": ["noodl", "mcp"]
}
}
}
```
## Plugin Architecture
The OpenCode plugin uses a multi-hook architecture for seamless integration:
| Hook | Event | Purpose |
| --------------------- | --------------------- | ------------------------------------ |
| `session.created` | Session start | Lists indexed repositories |
| `tool.execute.before` | Before Glob/Grep/Bash | Runs semantic search, stores results |
| `chat.message` | Before LLM message | Injects search context into message |
| `tool.execute.after` | After MCP tools | Formats query results for display |
## How It Works
### Automatic Context Injection
When you use search tools (Glob, Grep, Bash), the plugin automatically:
1. **Intercepts** the tool call in `tool.execute.before`
2. **Extracts** a semantic query from the pattern
3. **Runs** `noodl search` against your indexed codebase
4. **Stores** results in session-scoped storage (with 30s TTL for memory safety)
5. **Injects** context via `chat.message` hook into the next LLM message
6. **Consumes** (clears) the context after injection to prevent stale data
This happens transparently - you get semantic search results without changing your workflow.
### Context Format
Search results are injected as XML context:
```xml
```
The LLM sees this context alongside your original search results, providing architectural understanding.
## MCP Tools
The plugin connects to the noodlbox MCP server, providing these tools:
| Tool | Purpose |
| ----------------------------- | ----------------------------------------------------------------- |
| `noodlbox_query_with_context` | Semantic code search returning execution flows |
| `noodlbox_symbol_context` | Get 360-degree context for a symbol (references, community, docs) |
| `noodlbox_detect_impact` | Analyze git changes and their ripple effects |
| `noodlbox_rename_symbol` | Multi-file coordinated rename with confidence-tagged edits |
| `noodlbox_raw_cypher_query` | Direct graph queries for advanced analysis |
| `noodlbox_analyze` | Index a new repository |
## Skills
Noodlbox provides the `noodlbox-setup` skill for initializing noodlbox context in a project:
| Skill | Purpose | When to Use |
| ---------------- | ---------------------------------------- | ----------------- |
| `noodlbox-setup` | Initialize noodlbox context in a project | "Set up noodlbox" |
Skills are installed to `~/.config/opencode/skill/` and discovered automatically by OpenCode.
## Session Startup
On session start, the plugin logs all indexed repositories:
```
[noodlbox] Indexed repositories:
owner/my-app (last analyzed: 2 hours ago)
owner/other-repo (last analyzed: 1 day ago)
```
This helps you know which repositories have context available.
## Example Usage
### Automatic Enhancement
When you search with Grep:
```
Grep for "handleAuth"
```
The plugin automatically augments with semantic search, showing:
* Functions that implement authentication
* Related processes and call chains
* Entry points into the auth system
### Explicit Tool Calls
For direct queries:
```
Use noodlbox_query_with_context to find the payment processing flow
```
### Impact Analysis
Before committing:
```
Use noodlbox_detect_impact to check what my staged changes affect
```
## Configuration
### Environment Variables
| Variable | Default | Purpose |
| --------------------- | ------- | -------------------- |
| `NOODLBOX_CLI_PATH` | `noodl` | Path to noodl CLI |
| `NOODLBOX_HOOK_DEBUG` | `false` | Enable debug logging |
### Debug Mode
Enable debug logging to troubleshoot hook execution:
```bash
export NOODLBOX_HOOK_DEBUG=true
```
## Workflow: First-Time Setup
For a new repository:
```bash
# 1. Analyze the codebase
noodl analyze /path/to/repo
# 2. Configure OpenCode
noodl configure opencode
# 3. Start coding - hooks work automatically
```
## Workflow: Pre-Commit Review
Before committing changes, ask OpenCode:
```
Use noodlbox_detect_impact to analyze my staged changes
```
Review the impacted processes and plan testing accordingly.
## Troubleshooting
### Hooks Not Firing
1. Check plugin is installed: `ls ~/.config/opencode/plugin/noodlbox/`
2. Verify shared lib exists: `ls ~/.config/opencode/plugin/noodlbox/shared/hooks/lib.js`
3. Enable debug mode to see hook execution:
```bash
export NOODLBOX_HOOK_DEBUG=true
```
### MCP Tools Not Available
1. Check MCP config: `cat ~/.config/opencode/opencode.json`
2. Verify noodl is in PATH: `which noodl`
3. Test MCP server: `noodl mcp`
### No Search Results
1. Verify repository is indexed: `noodl list`
2. Re-analyze if needed: `noodl analyze .`
## Related
* [Getting Started](/getting-started) - Installation and MCP setup
* [Workflows](/workflows) - Step-by-step guides for common tasks
# Other Agents (/integrations/other-agents)
If your AI coding agent isn't directly supported by `noodl configure`, you can manually configure the MCP server to access Noodlbox tools and resources.
## MCP Configuration
Add the following to your agent's MCP configuration file:
```json
{
"mcpServers": {
"noodlbox": {
"command": "noodl",
"args": ["mcp"]
}
}
}
```
The configuration key varies by agent:
* Most agents use `mcpServers` (Claude Code, Cursor, VS Code)
* Some agents use `servers` or `mcp_servers`
Check your agent's documentation for the correct configuration format and file location.
## Project Setup
After configuring MCP, set up noodlbox context in each project. Ask your AI agent:
```
Read the setup:// MCP resource and write it to AGENTS.md in the project root
```
This creates an `AGENTS.md` file with noodlbox context that your agent will use for codebase understanding.
Alternatively, you can manually create the file by running:
```bash
noodl mcp resource read setup:// > AGENTS.md
```
## Available Tools
Once configured, your agent has access to these MCP tools:
| Tool | Purpose |
| ----------------------------- | ----------------------------------------------------------------- |
| `noodlbox_query_with_context` | Semantic code search returning execution flows |
| `noodlbox_symbol_context` | Get 360-degree context for a symbol (references, community, docs) |
| `noodlbox_detect_impact` | Analyze git changes and their ripple effects |
| `noodlbox_rename_symbol` | Multi-file coordinated rename with confidence-tagged edits |
| `noodlbox_raw_cypher_query` | Direct graph queries for advanced analysis |
| `noodlbox_analyze` | Index a new repository |
| `noodlbox_delete` | Remove a repository from the index |
## Available Resources
| Resource | Description |
| ----------------------------------- | -------------------------------------------- |
| `repository://list` | List of indexed repositories |
| `setup://` | AGENTS.md content for project initialization |
| `db://schema/{repository}` | Database schema for a repository |
| `map://{repository}` | Codebase overview map |
| `map://{repository}/community/{id}` | Community detail view |
| `map://{repository}/process/{id}` | Process execution trace |
## Workflow: First-Time Setup
For a new repository:
```bash
# 1. Install noodlbox CLI
brew install noodlbox/tap/noodl
# 2. Analyze the codebase
noodl analyze /path/to/repo
# 3. Configure your agent's MCP (see above)
# 4. Set up project context
# Ask your agent: "Read the setup:// MCP resource and write it to AGENTS.md"
```
## Troubleshooting
### MCP Tools Not Available
1. Verify noodl is in PATH: `which noodl`
2. Test MCP server manually: `noodl mcp`
3. Check your agent's MCP configuration file location and format
### No Search Results
1. Verify repository is indexed: `noodl list`
2. Re-analyze if needed: `noodl analyze .`
### Connection Issues
The MCP server uses stdio transport. Ensure your agent supports stdio-based MCP servers.
## Related
* [Getting Started](/getting-started) - Installation and CLI setup
* [MCP Tools](/mcp) - Detailed tool documentation
* [MCP Resources](/mcp/resources) - Resource documentation
# Search Hooks (/integrations/search-hooks)
Search hooks automatically enhance file search tools with Noodlbox semantic context. When your AI agent searches for code, it gets architectural context alongside file matches.
## How It Works
When your AI agent searches using `Glob`, `Grep`, or `Bash` (with grep/rg/find commands):
1. The hook extracts the search pattern
2. Queries Noodlbox for related processes and symbols
3. Returns semantic context alongside the original search
The original tool still runs - the hook adds context, not replaces results.
## Before vs After
**Without hooks** (file paths only):
```
> grep "validator"
→ src/auth/validator.ts
→ src/user/validator.ts
→ tests/validator.test.ts
```
**With hooks** (semantic context added):
```
> grep "validator"
→ TokenValidator (src/auth/validator.ts:45)
CALLS: verifyJWT(), checkExpiry()
CALLED_BY: AuthMiddleware, APIGateway
→ InputValidator (src/user/validator.ts:12)
CALLS: sanitizeInput(), validateSchema()
CALLED_BY: UserController, FormHandler
```
## Setup
Search hooks are **automatically configured** when you install the Noodlbox plugin:
```bash
claude plugin install noodlbox@noodlbox
```
Uses the `PreToolUse` hook to intercept Glob, Grep, and Bash tool calls.
Search hooks are **automatically configured** when you run `noodl configure`:
```bash
noodl configure
```
Uses the `beforeShellExecution` hook to enhance shell searches with semantic context.
Search hooks are **automatically configured** when you run `noodl configure`:
```bash
noodl configure
```
Uses skills to enhance searches with semantic context.
Search hooks are **automatically configured** when you run `noodl configure`:
```bash
noodl configure
```
Uses skills to enhance searches with semantic context.
## Supported Tools
| Tool | What's Enhanced |
| ------ | -------------------------------- |
| `Glob` | File pattern searches |
| `Grep` | Content pattern searches |
| `Bash` | grep, rg, ag, ack, find commands |
## Fallback Behavior
The hook gracefully falls back when:
* Repository is not indexed
* Search pattern is too short
* Any error occurs
This makes it safe to use across all projects - unindexed repos work normally.
## See Also
* [Session Hooks](/integrations/session-hooks) - Context at conversation start
* [MCP Tools](/mcp) - Direct tool access
# Session Hooks (/integrations/session-hooks)
Session hooks inject Noodlbox context at the **start of a conversation**, before any reasoning begins. Your AI agent knows about the codebase structure from the first message.
## How It Works
When you start a new conversation in an indexed repository:
1. The hook detects the repository is indexed
2. Injects context about available tools and resources
3. Your agent immediately knows how to explore the codebase
The hook only fires on fresh sessions, not when resuming or clearing.
## What Gets Injected
When the hook detects an indexed repository, your agent receives:
* **Available tools** - semantic search, impact detection, graph queries
* **Available resources** - architecture map, database schema
* **Knowledge graph schema** - node types, relationships, and properties
* **Usage tips** - read the map first to understand structure
### Knowledge Graph Schema
The hook calls `noodl schema` and injects the full database schema, wrapped in `` tags. This gives your agent immediate understanding of:
* **Node types** - `CODE_SYMBOL`, `FILE`, `COMMUNITY`, `PROCESS`
* **Relationships** - `CALLS`, `CONTAINED_BY`, `MEMBER_OF`, `STEP_IN_PROCESS`
* **Properties** - Available fields on each node type
With this schema, your agent can write accurate Cypher queries without needing to discover the structure first.
## Setup
Session hooks are **automatically configured** when you install the Noodlbox plugin:
```bash
claude plugin install noodlbox@noodlbox
```
Uses the `SessionStart` hook to inject context when a conversation begins.
Cursor achieves session context through `.cursorrules` and MCP resources:
```bash
noodl configure
```
The `.cursorrules` file provides base Noodlbox awareness, and agents can read MCP resources like `map://{repository}` and `db://schema/{repository}` on demand.
Codex achieves session context through skills and MCP resources:
```bash
noodl configure
```
Skills provide base Noodlbox awareness, and agents can read MCP resources like `map://{repository}` and `db://schema/{repository}` on demand.
OpenCode achieves session context through `AGENTS.md` and MCP resources:
```bash
noodl configure
```
The `AGENTS.md` file provides base Noodlbox awareness, and agents can read MCP resources like `map://{repository}` and `db://schema/{repository}` on demand.
## When It Fires
| Event | Hook Fires? | Why |
| ---------------- | ----------- | ------------------------------- |
| New conversation | Yes | Fresh session needs context |
| Resume | No | Context already in conversation |
| Clear | No | User intentionally clearing |
## See Also
* [Search Hooks](/integrations/search-hooks) - Automatic context on every search
* [MCP Tools](/mcp) - Direct tool access
# Communities (/platform/communities)
Communities are functional groupings of code that work together. Unlike directories or modules, communities are detected algorithmically based on actual code relationships.
## What is a Community?
A community is a cluster of code symbols (functions, classes, methods) that:
* Frequently call each other
* Share common purposes
* Have higher internal cohesion than external connections
Think of communities as the natural boundaries in your codebase - the groups of code that "belong together" based on how they're actually used.
## How Communities Are Detected
noodlbox uses modularity optimization algorithms to identify communities:
### Build the call graph
Map all function calls in your codebase
### Calculate modularity
Find groupings that maximize internal connections
### Detect boundaries
Identify where one community ends and another begins
### Label communities
Generate meaningful names based on symbols
## Community Properties
### Cohesion Score
A measure from 0 to 1 of how tightly connected the community is:
* **High cohesion (0.8+)**: Well-defined, focused responsibility
* **Medium cohesion (0.5 to 0.8)**: Reasonable grouping, some external dependencies
* **Low cohesion (below 0.5)**: May indicate code that should be split
### Entry Points
Functions that are called from outside the community. These are the community's "API" - how other code interacts with it.
### Key Symbols
The most central symbols in the community, based on how many other symbols depend on them.
## Example Community
```json
{
"label": "Authentication",
"cohesion": 0.92,
"symbol_count": 85,
"entry_points": [
{ "name": "login", "calls": 156 },
{ "name": "logout", "calls": 89 },
{ "name": "validateToken", "calls": 234 }
],
"key_symbols": [
{ "name": "authenticateUser", "centrality": 0.95 },
{ "name": "createSession", "centrality": 0.87 }
]
}
```
## Communities vs. Files
| Aspect | File-based | Community-based |
| ----------- | ------------------- | ---------------------- |
| Grouping | Directory structure | Actual relationships |
| Boundaries | Developer choice | Algorithm detected |
| Refactoring | Move files | Understand connections |
| Discovery | Browse folders | Follow functionality |
## Working with Communities
### Exploring Communities
Use the Codebase Map to see all communities:
```
GET map://{repository}
```
### Deep Diving
Get details about a specific community:
```
GET map://{repository}/community/{id}
```
### Querying with Cypher
Find symbols in a community:
```cypher
MATCH (s:CodeSymbol)-[:MEMBER_OF]->(c:Community)
WHERE c.label = "Authentication"
RETURN s.name, s.symbol_type
```
Find cross-community calls:
```cypher
MATCH (s1:CodeSymbol)-[:MEMBER_OF]->(c1:Community),
(s2:CodeSymbol)-[:MEMBER_OF]->(c2:Community),
(s1)-[:CALLS]->(s2)
WHERE c1 <> c2
RETURN c1.label, c2.label, s1.name, s2.name
```
## Use Cases
### Understanding Codebase Structure
Communities reveal the actual architecture of your code, beyond what's documented or intended.
### Impact Analysis
Changes to a community's key symbols affect the entire community. Changes to entry points may affect external code.
### Refactoring Planning
Low cohesion communities may need to be split. Frequently cross-communicating communities may need to be merged.
### Onboarding
New developers can understand the codebase by exploring communities instead of navigating file trees.
## Learn More
* [Codebase Map](/mcp/resources/codebase-map) - See all communities
* [Community Detail](/mcp/resources/community-resource) - Explore a specific community
* [Processes](/platform/processes) - Execution flows within and across communities
# Platform (/platform)
noodlbox transforms your codebase into an intelligent knowledge graph that understands code relationships, not just files.
## Core Philosophy
Traditional code navigation is file-based: directories, imports, grep. But developers think in features, flows, and functionality.
noodlbox reimagines code understanding:
| Traditional | noodlbox |
| ----------- | --------------- |
| Directories | Communities |
| Call stacks | Processes |
| Imports | Relationships |
| Grep | Semantic search |
## Core Concepts
The foundation: nodes, relationships, and graph queries
Functional groupings of related code
Execution flows through your codebase
Human-readable names for communities and processes
## How It Works
### Analysis
```bash
noodl analyze /path/to/repo
```
noodlbox extracts:
* **Symbols** - Functions, classes, methods, variables
* **Relationships** - Calls, imports, contains
* **Structure** - Files, modules, packages
### Community Detection
Using the Leiden algorithm, noodlbox identifies communities - clusters of code that work together. This reveals natural structure beyond file organization.
### Process Extraction
noodlbox traces execution paths to identify processes - the flows that make your application work.
### Knowledge Graph
Everything is stored in LanceDB - a unified storage layer for both graph queries and full-text search:
* **Graph Storage** - Relationships and traversals via lance-graph
* **Full-Text Search** - BM25-ranked code search with Tantivy
```cypher
// Find all functions that call authentication code
MATCH (caller)-[:CALLS]->(auth:CODE_SYMBOL)
WHERE auth.name CONTAINS 'auth'
RETURN caller.name, auth.name
```
## CLI Commands
| Command | Description |
| ---------------------- | ----------------------------- |
| `noodl analyze ` | Analyze a repository |
| `noodl list` | List analyzed repositories |
| `noodl delete ` | Delete an analyzed repository |
| `noodl configure` | Configure AI agents (global) |
| `noodl status` | Check authentication |
See the [CLI Reference](/reference/cli-reference) for the complete command list.
## Accessing the Graph
**Via MCP (recommended):**
```
@noodlbox:map://owner/my-repo
@noodlbox:map://owner/my-repo/community/123
```
**Via Cypher:**
```cypher
MATCH (s:CODE_SYMBOL)-[:CALLS]->(t:CODE_SYMBOL)
RETURN s.name, t.name LIMIT 10
```
## Learn More
* [Knowledge Graph](/platform/knowledge-graph) - Graph structure and queries
* [Communities](/platform/communities) - How code is grouped
* [Processes](/platform/processes) - Execution flow tracing
* [Labels](/platform/labels) - Human-readable naming system
# Knowledge Graph (/platform/knowledge-graph)
At the heart of noodlbox is a knowledge graph - a structured representation of your code that captures symbols, relationships, and organizational patterns.
## Why a Graph?
Code is inherently relational:
* Functions call other functions
* Classes inherit from other classes
* Modules import other modules
* Features span multiple files
Relational databases struggle with these interconnections. A graph database makes traversing relationships natural and fast.
## Node Types
### CodeSymbol
The fundamental unit: functions, classes, methods, variables, interfaces, enums, and more.
```typescript
{
name: "authenticateUser",
symbol_type: "Function",
file_path: "src/auth/authenticate.ts",
line_number: 42,
content: "export function authenticateUser(...) { ... }",
signature: "authenticateUser(credentials: Credentials): Promise"
}
```
**Symbol types by language:**
| TypeScript | Python |
| ----------------------- | ----------------------- |
| Class, Method, Function | Class, Method, Function |
| Attribute, Interface | Attribute |
| TypeAlias, Enum | TypeAlias, Enum |
| Constant, Export | Constant |
### File
Source files in your repository.
```typescript
{
path: "src/auth/authenticate.ts",
extension: "ts"
}
```
### Community
Functional groupings detected by modularity analysis.
```typescript
{
label: "Authentication",
cohesion: 0.92,
symbol_count: 85
}
```
### Process
Execution flows through the codebase.
```typescript
{
label: "UserLogin",
process_type: "cross_community",
step_count: 5
}
```
## Relationship Types
### CALLS
Function/method call relationships.
```cypher
(authenticate:CodeSymbol)-[:CALLS]->(validateToken:CodeSymbol)
```
### CONTAINED\_BY
Symbols contained in files.
```cypher
(authenticate:CodeSymbol)-[:CONTAINED_BY]->(authFile:File)
```
### MEMBER\_OF
Symbols belonging to communities.
```cypher
(authenticate:CodeSymbol)-[:MEMBER_OF]->(authCommunity:Community)
```
### STEP\_IN\_PROCESS
Steps in execution processes.
```cypher
(authenticate:CodeSymbol)-[:STEP_IN_PROCESS {step: 2}]->(loginProcess:Process)
```
## Querying the Graph
noodlbox uses Cypher, a declarative graph query language:
### Find all callers of a function
```cypher
MATCH (caller:CodeSymbol)-[:CALLS]->(target:CodeSymbol)
WHERE target.name = "authenticateUser"
RETURN caller.name, caller.file_path
```
### Trace execution paths
```cypher
MATCH path = (entry:CodeSymbol)-[:CALLS*1..5]->(target:CodeSymbol)
WHERE entry.name = "handleRequest"
RETURN path
```
### Find community relationships
```cypher
MATCH (s1:CodeSymbol)-[:MEMBER_OF]->(c1:Community),
(s2:CodeSymbol)-[:MEMBER_OF]->(c2:Community),
(s1)-[:CALLS]->(s2)
WHERE c1 <> c2
RETURN c1.label, c2.label, count(*) as cross_calls
```
## Storage Architecture
noodlbox uses [LanceDB](https://lancedb.com/) as a unified storage layer for both graph queries and full-text search.
### Graph Storage
Graph relationships are stored and queried using lance-graph, enabling:
* Fast traversals across millions of relationships
* Complex pattern matching with Cypher queries
* Efficient aggregations
### Full-Text Search
Code search uses LanceDB's built-in FTS with BM25 ranking (powered by Tantivy). This provides:
* Relevance-ranked search results
* Code-aware stopword filtering
* Fast incremental indexing
## Accessing the Schema
Use the Database Schema resource to inspect the graph structure:
```
GET db://schema/{repository}
```
This returns all node types, relationship types, and their properties.
## Learn More
* [MCP Cypher Query Tool](/mcp/tools/cypher-query) - Execute graph queries
* [Database Schema Resource](/mcp/resources/database-schema) - Explore the schema
* [Communities](/platform/communities) - How communities are structured
# Labels (/platform/labels)
Labels transform auto-generated identifiers into meaningful, human-readable names for communities and processes.
## What are Labels?
When noodlbox analyzes your code, it automatically generates identifiers for communities and processes. Labels provide human-readable alternatives:
| Without Labels | With Labels |
| ----------------------------------- | --------------------- |
| `community_42` | Authentication System |
| `proc_handleLogin_to_validateToken` | User Login Flow |
| `cluster_abc123` | Payment Processing |
## The Labels File
Labels are stored in `.noodlbox/labels.json` in your repository root:
```json
{
"version": "1.0",
"repository": "owner/my-app",
"generated_at": "2024-12-15T10:30:00Z",
"communities": {
"abc123": {
"label": "Authentication System",
"description": "Handles user login, token validation, and session management"
},
"def456": {
"label": "Payment Processing",
"description": "Processes payments, handles refunds, manages payment methods"
}
},
"processes": {
"proc_001": {
"label": "User Login Flow",
"description": "Validates credentials, creates session, returns auth token"
},
"proc_002": {
"label": "Checkout Process",
"description": "Validates cart, processes payment, creates order"
}
}
}
```
## Creating Labels
Labels are created manually by adding a `.noodlbox/labels.json` file to your repository. Here's how to create effective labels:
## Label Guidelines
### Community Labels
Labels describe the module's purpose based on:
* Common theme in symbol names
* Domain/business function
* File path patterns (e.g., `src/auth/` suggests "Authentication")
**Examples:**
* `login`, `logout`, `validateToken` → "Authentication System"
* `processPayment`, `refund`, `chargeCard` → "Payment Processing"
* `User`, `Profile`, `updateAccount` → "User Management"
### Process Labels
Labels describe the execution flow based on:
* Entry point symbol name
* Terminal action (what the process achieves)
* Domain context
**Examples:**
* `handleLogin` → `validateToken` → `createSession` → "User Login Flow"
* `addToCart` → `checkout` → `processPayment` → "Order Checkout Process"
* `sendEmail` → `formatTemplate` → `deliverMessage` → "Email Notification Dispatch"
## Where Labels are Used
### CLI Commands
```bash
noodl list # Shows community labels
noodl status # Includes label statistics
```
### MCP Resources
```
@noodlbox:map://owner/my-repo
```
Returns community labels instead of IDs in the overview.
### Impact Analysis
The `noodlbox_detect_impact` MCP tool uses labels for:
* Process names in impact reports
* Community names in cross-module analysis
## Editing Labels
Edit `.noodlbox/labels.json` to:
* Add labels for new communities/processes
* Update labels with domain-specific terminology
* Expand descriptions
```json
{
"communities": {
"abc123": {
"label": "OAuth 2.0 Authentication",
"description": "Implements OAuth 2.0 flow with PKCE for mobile clients"
}
}
}
```
## Best Practices
### Label Naming
* **Be specific**: "User Authentication" > "Auth"
* **Describe function**: "Payment Processing" > "Payments Module"
* **Use domain terms**: Match terminology your team uses
### Descriptions
* Summarize in one sentence
* Focus on what the code does, not how
* Include key responsibilities
### Version Control
Commit `.noodlbox/labels.json` to your repository:
* Shared across team members
* Evolves with your codebase
* Documents architectural understanding
## Related
* [Communities](/platform/communities) - Understanding code communities
* [Processes](/platform/processes) - Execution flow tracing
* [Claude Code Plugin](/integrations/claude-code-plugin) - Commands for working with labels
# Processes (/platform/processes)
Processes are execution flows through your codebase - the paths that trace how operations move from start to finish.
## What is a Process?
A process represents a sequence of function calls that accomplish something:
* A user logging in
* An API request being handled
* Data being transformed and saved
Processes show you the "how" of your code - not just what functions exist, but how they work together.
## Process Types
### Intra-community Processes
Processes that stay within a single community:
* More localized
* Easier to understand
* Lower change impact
```
Authentication Community:
validateToken → checkExpiry → refreshIfNeeded
```
### Cross-community Processes
Processes that span multiple communities:
* Show system-wide flows
* Reveal architectural boundaries
* Higher change impact
```
API → Authentication → DataAccess → Logging
```
## Process Properties
### Trace
The ordered sequence of function calls:
```json
{
"trace": [
{ "step": 1, "name": "handleRequest", "location": "src/api/handler.ts:23" },
{ "step": 2, "name": "authenticate", "location": "src/auth/auth.ts:45" },
{ "step": 3, "name": "fetchUser", "location": "src/data/users.ts:67" },
{ "step": 4, "name": "respond", "location": "src/api/response.ts:12" }
]
}
```
### Communities Traversed
Which communities the process touches:
```json
{
"communities": ["API", "Authentication", "DataAccess"]
}
```
### Related Processes
Other processes that share entry points or patterns:
```json
{
"related": [
{ "id": "proc_signup", "common_entry_point": "handleRequest" }
]
}
```
## How Processes Are Detected
noodlbox identifies processes through:
1. **Entry point detection** - Find functions called from outside communities
2. **Path tracing** - Follow call chains from entry points
3. **Pattern recognition** - Group similar execution paths
4. **Labeling** - Generate descriptive names
## Working with Processes
### Viewing Process Traces
Get the full trace of a process:
```
GET map://{repository}/process/{id}
```
### Finding Processes in Communities
Explore a community to see its processes:
```
GET map://{repository}/community/{id}
```
### Querying Process Steps
Use Cypher to analyze process steps:
```cypher
MATCH (s:CodeSymbol)-[r:STEP_IN_PROCESS]->(p:Process)
WHERE p.label = "UserLogin"
RETURN s.name, r.step, s.file_path
ORDER BY r.step
```
## Use Cases
### Understanding Features
See exactly how a feature works by tracing its process.
### Debugging
Follow the process trace to understand where errors occur in the flow.
### Impact Analysis
Cross-community processes show which parts of the system are affected by changes.
### Documentation
Processes serve as living documentation of how your code actually works.
### Code Review
Verify that changes don't break process flows.
## Example: User Login Process
```json
{
"id": "proc_login",
"label": "UserLogin",
"process_type": "cross_community",
"communities": ["API", "Authentication", "DataAccess", "Session"],
"trace": [
{
"step": 1,
"name": "handleLoginRequest",
"location": "src/api/auth.ts:45"
},
{
"step": 2,
"name": "validateCredentials",
"location": "src/auth/validate.ts:23"
},
{
"step": 3,
"name": "getUserByEmail",
"location": "src/data/users.ts:67"
},
{
"step": 4,
"name": "comparePassword",
"location": "src/auth/password.ts:34"
},
{
"step": 5,
"name": "createSession",
"location": "src/session/create.ts:12"
},
{
"step": 6,
"name": "respondWithToken",
"location": "src/api/response.ts:89"
}
]
}
```
This process shows:
* Entry through API layer
* Credential validation in Authentication
* Database lookup in DataAccess
* Session creation in Session
* Response back through API
## Learn More
* [Process Trace Resource](/mcp/resources/process-resource) - Access process data
* [Communities](/platform/communities) - How code is grouped
* [Change Analysis](/workflows/change-analysis) - Analyze change impact on processes
# Skills (/skills)
Skills are structured prompts that guide your AI agent through tasks using noodlbox's knowledge graph.
## Available Skills
Initialize noodlbox context for a project
## How to Use Skills
Skills are invoked via slash commands in your AI agent:
```
/noodlbox:setup
```
Each skill provides:
* **Quick Start** - Essential steps to get going
* **Workflow Checklist** - Track your progress
* **Tool Reference** - Which MCP tools to use
* **Examples** - Real-world scenarios
## Choosing the Right Skill
| Task | Skill |
| ---------------------------------- | ---------------------- |
| "Set up noodlbox for this project" | [Setup](/skills/setup) |
## Related
* [Workflows](/workflows) - Step-by-step guides for common tasks
* [MCP Server](/mcp) - Tools and resources available to your agent
# Setup (/skills/setup)
Set up noodlbox for a project by creating an `AGENTS.md` file with MCP context.
**Invoke with:** `/noodlbox:setup`
## What It Does
Creates an `AGENTS.md` file at the project root to provide noodlbox context to the AI agent. This file contains instructions that help the agent understand how to use noodlbox tools effectively.
## Instructions
### Check if AGENTS.md exists
Look for `AGENTS.md` at the project root
### Create or update the file
**If AGENTS.md does not exist:**
* Create it with the noodlbox content
**If AGENTS.md already exists:**
* Add a blank line
* Add ``
* Add the noodlbox content
* Add ``
### Confirm success
The agent will confirm the file was created or updated
## Example Output
**For a new file:**
```
Created AGENTS.md with noodlbox context. The AI agent will now have access to noodlbox MCP tools and resources.
```
**For an existing file:**
```
Added noodlbox section to existing AGENTS.md. The AI agent will now have access to noodlbox MCP tools and resources.
```
## File Structure
The noodlbox section in `AGENTS.md` is wrapped with HTML comments for easy identification:
```markdown
# Noodlbox
Instructions for using noodlbox tools and resources...
```
This allows:
* Safe updates without overwriting user content
* Easy removal if needed
* Clear separation from other AGENTS.md content
## When to Use
Use this skill when:
* Setting up noodlbox for the first time in a project
* Re-initializing noodlbox context after major changes
* Adding noodlbox to a project that already has an `AGENTS.md` file
## Related
* [Getting Started](/getting-started) - Full installation and setup guide
* [MCP Server](/mcp) - Tools and resources available to your agent
# CLI Reference (/reference/cli-reference)
The `noodl` CLI provides commands for analyzing repositories, managing configurations, and interacting with the noodlbox platform.
## Repository Names
Repository names use the `owner/repo` format. Most commands also accept a path and will resolve to the repository automatically.
```bash
# By path (recommended)
noodl search "authentication flow" # Uses current directory
noodl search "query" /path/to/repo # Explicit path
# By name
noodl search "query" owner/my-repo # Reference by name
noodl delete owner/my-repo # Delete by name
```
## Core Commands
Commands for analyzing and querying your codebase.
### noodl analyze
Analyze a repository and build its knowledge graph.
```bash
noodl analyze [OPTIONS]
```
**Arguments:**
| Argument | Description |
| -------- | --------------------------------- |
| `` | Path to the repository to analyze |
**Options:**
| Flag | Description |
| --------------- | ------------------------------------------------------- |
| `--force` | Re-analyze ignoring cached results |
| `--docs ` | Enable markdown documentation analysis (default: false) |
**Examples:**
```bash
noodl analyze . # Current directory
noodl analyze /path/to/repo # Absolute path
noodl analyze --force . # Re-analyze from scratch
noodl analyze --docs true . # Include markdown docs
```
### noodl list
List all analyzed repositories.
```bash
noodl list
```
### noodl delete
Delete analyzed repositories from noodlbox.
```bash
noodl delete [OPTIONS] [REPOSITORIES]...
```
**Arguments:**
| Argument | Description |
| ------------------- | ----------------------------------- |
| `[REPOSITORIES]...` | Repository names or paths to delete |
**Options:**
| Flag | Description |
| ----------- | ------------------------- |
| `-y, --yes` | Skip confirmation prompts |
**Examples:**
```bash
noodl delete owner/my-repo # Delete one repository
noodl delete owner/repo1 owner/repo2 # Delete multiple
noodl delete -y owner/my-repo # Skip confirmation
```
### noodl schema
Display the knowledge graph schema (node types, relationships, properties).
```bash
noodl schema
```
Used by AI agents to understand the graph structure for queries.
### noodl search
Search for code using natural language.
```bash
noodl search [OPTIONS] [REPOSITORY]
```
**Arguments:**
| Argument | Description |
| -------------- | ------------------------------------------------------- |
| `` | Search query (required) |
| `[REPOSITORY]` | Repository name or path (defaults to current directory) |
**Options:**
| Flag | Description |
| ----------------------- | ----------------------------------------- |
| `--limit ` | Maximum number of processes to return |
| `--max-symbols ` | Maximum symbols per process |
| `--include-content` | Include full symbol content in output |
| `-f, --format ` | Output format: `toon` (default) or `json` |
**Examples:**
```bash
noodl search "authentication flow" # Search current dir
noodl search "database queries" /path/to/repo # Search specific repo
noodl search "API handlers" --limit 5 # Limit results
noodl search "auth" --format json # JSON output
noodl search "login" --include-content # Include full code
```
### noodl search-docs
Search documentation (markdown files, READMEs) using vector, keyword, or hybrid search.
```bash
noodl search-docs [OPTIONS] [REPOSITORY]
```
**Arguments:**
| Argument | Description |
| -------------- | ------------------------------------------------------- |
| `` | Search query (required) |
| `[REPOSITORY]` | Repository name or path (defaults to current directory) |
**Options:**
| Flag | Description |
| ----------------------- | ------------------------------------------------------------------------ |
| `--mode ` | Search mode: `vector` (semantic), `fts` (keyword), or `hybrid` (default) |
| `--limit ` | Maximum number of documents to return |
| `-f, --format ` | Output format: `toon` (default) or `json` |
**Examples:**
```bash
# Hybrid search (default - combines semantic + keyword)
noodl search-docs "authentication guide"
# Semantic search only
noodl search-docs "API usage" --mode vector
# Keyword search only
noodl search-docs "README" --mode fts
# With options
noodl search-docs "setup" --limit 10 --format json
```
### noodl query
Execute a Cypher query against the knowledge graph.
```bash
noodl query [OPTIONS] [REPOSITORY]
```
**Arguments:**
| Argument | Description |
| -------------- | ------------------------------------------------------- |
| `` | Cypher query (required) |
| `[REPOSITORY]` | Repository name or path (defaults to current directory) |
**Options:**
| Flag | Description |
| ----------------------- | ----------------------------------------- |
| `--limit ` | Maximum number of results |
| `-f, --format ` | Output format: `toon` (default) or `json` |
**Examples:**
```bash
noodl query "MATCH (s:CODE_SYMBOL) RETURN s.name LIMIT 10"
noodl query "MATCH (s:CODE_SYMBOL)-[:CALLS]->(t) RETURN s.name, t.name" --limit 20
noodl query "MATCH (c:COMMUNITY) RETURN c" --format json
```
## Account Commands
Commands for authentication and account status.
### noodl auth
Authenticate with noodlbox (opens browser).
```bash
noodl auth
```
### noodl status
Check authentication and connection status.
```bash
noodl status
```
## Setup Commands
Commands for first-time setup and reset.
### noodl init
First-time setup for noodlbox. This is the recommended starting point.
```bash
noodl init [OPTIONS]
```
This command:
* Creates required directories (`~/.noodlbox/state`, `~/.noodlbox/repositories`)
* Authenticates with noodlbox (opens browser)
* Configures MCP for your agents (Claude Code, Cursor, Codex, OpenCode)
**Options:**
| Flag | Description |
| ----------- | -------------------------- |
| `-y, --yes` | Skip prompts, use defaults |
**Examples:**
```bash
noodl init # Interactive first-time setup
noodl init -y # Non-interactive mode (used by installer)
```
**Note:** The installer runs `noodl init -y` automatically. To start fresh, use `noodl reset`.
### noodl reset
Wipe all noodlbox data and re-run first-time setup.
```bash
noodl reset [OPTIONS]
```
This command:
* Removes `~/.noodlbox` directory (all data, config, repositories)
* Re-runs `noodl init` for fresh setup
**Options:**
| Flag | Description |
| ------------- | ------------------------ |
| `-f, --force` | Skip confirmation prompt |
**Examples:**
```bash
noodl reset # Interactive (asks for confirmation)
noodl reset -f # Skip confirmation
```
## Agent Integration Commands
Commands for configuring AI agent integrations.
### noodl configure
Configure AI agents (Claude Code, Cursor, Codex, OpenCode) globally.
```bash
noodl configure [OPTIONS]
```
Configuration is stored in `~/.noodlbox/config.toml` and applies to all repositories.
**Options:**
| Flag | Description |
| ----------- | -------------------------------------- |
| `-y, --yes` | Skip prompts, use defaults |
| `--force` | Reconfigure even if already configured |
**Examples:**
```bash
noodl configure # Configure agents
noodl configure -y # Non-interactive mode
noodl configure --force # Force reconfigure
```
### noodl mcp
Start the MCP server (typically launched automatically by agents).
```bash
noodl mcp
```
## Utility Commands
Commands for maintenance and troubleshooting.
### noodl update
Update the noodl CLI and plugins to the latest version.
```bash
noodl update
```
### noodl doctor
Diagnose installation issues and check system health.
```bash
noodl doctor [OPTIONS]
```
**Options:**
| Flag | Description |
| --------------- | ---------------------------------------- |
| `-v, --verbose` | Show detailed information for each check |
| `--fix` | Apply automatic fixes when possible |
**Checks performed:**
* Installation integrity
* Authentication validity
* Security configuration
* Network connectivity
* MCP server configuration
* Repository health
### noodl docs
Open the noodlbox documentation in your browser.
```bash
noodl docs
```
### noodl feedback
Submit feedback or report issues.
```bash
noodl feedback
```
### noodl version
Display the installed noodl version.
```bash
noodl version
```
## Global Options
These options work with all commands:
| Flag | Description |
| --------------- | ------------------------- |
| `-h, --help` | Show help for any command |
| `-V, --version` | Show version information |
## Related
* [Getting Started](/getting-started) - Installation and MCP setup
* [Platform Overview](/platform) - Understanding the knowledge graph
# Reference (/reference)
Complete technical reference for noodlbox CLI and tools.
Complete command reference for the noodlbox CLI
# Change Planning (/workflows/change-planning)
Pre-work research - gather context and understand the codebase BEFORE implementing changes.
B[Search Context]
B --> C[Explore Community]
C --> D[Trace Processes]
D --> E[Map Dependencies]`}
/>
## Quick Start
> "I need to implement user notifications, where do I start?"
> "Show me the codebase map"
> "Search for code related to email sending"
> "What processes involve the UserService?"
## When to Use
Use this workflow before any non-trivial implementation task:
* Adding a new feature
* Modifying existing behavior
* Integrating with existing code
* Understanding unfamiliar code areas
## Workflow
### Get the Codebase Overview
Start by reading the codebase map to understand the high-level structure:
> "Show me the codebase map"
**Uses:** `map://current` resource
Look for:
* Community names and purposes
* Cohesion scores (how tightly coupled)
* Cross-community flows
### Search for Relevant Code
Use semantic search to find code related to your task:
> "Search for code related to user notifications"
**Uses:** `noodlbox_query_with_context` tool
This returns processes ranked by relevance with full context.
### Explore the Target Community
Drill into specific modules to understand their boundaries:
> "Show me details about the Notifications community"
**Uses:** `map://current/community/{id}` resource
Focus on:
* Entry points (where to hook in)
* Key symbols (important functions/classes)
* Internal processes
### Trace Execution Flows
Understand how existing code executes:
> "Trace the sendEmail process"
**Uses:** `map://current/process/{id}` resource
See the exact function call sequence to understand integration points.
### Map Dependencies
Before planning your implementation, understand what code you'll depend on:
> "What functions call EmailService.send?"
> "What does NotificationManager depend on?"
**Uses:** `noodlbox_raw_cypher_query` tool
```cypher
// Find callers of a function
MATCH (caller)-[:CALLS]->(target:Symbol {name: "send"})
RETURN caller.name, caller.file_path
// Find dependencies of a class
MATCH (source:Symbol {name: "NotificationManager"})-[:CALLS]->(dep)
RETURN DISTINCT dep.name, dep.kind
```
## Example: Planning a New Feature
**Task:** Add push notification support alongside existing email notifications
### Understand Current State
> "Show me the codebase map"
Find the Notifications community and note its cohesion score.
### Find Existing Patterns
> "Search for notification sending patterns"
Review how email notifications are currently implemented.
### Identify Integration Points
> "What calls NotificationService.notify?"
These callers will need to support push notifications too.
### Map the Extension Points
> "Show me the NotificationService community details"
Identify where to add push notification logic without breaking existing behavior.
## Tools & Resources Reference
| Purpose | Tool/Resource |
| ------------------- | ------------------------------ |
| High-level overview | `map://current` |
| Semantic search | `noodlbox_query_with_context` |
| Module details | `map://current/community/{id}` |
| Execution flow | `map://current/process/{id}` |
| Dependency queries | `noodlbox_raw_cypher_query` |
# Code Review (/workflows/code-review)
Review PRs for quality, safety, and impact using impact detection and graph analysis.
B[Check Cross-Community]
B --> C[Verify Tests]
C --> D[Review Docs]
D --> E[Document Needs]`}
/>
## Quick Start
> "Review this PR comparing my branch to main"
> "What's the blast radius of changes on this branch?"
> "Which communities are affected by this PR?"
## When to Use
Use this workflow when:
* Reviewing pull requests
* Assessing merge risk
* Checking for unintended side effects
* Verifying test coverage
## Code Review Workflow
### Run Impact Detection
Compare the PR branch against the base:
> "Check the impact comparing this branch to main"
**Uses:** `noodlbox_detect_impact` tool with:
* `change_scope: "compare"`
* `base_ref: "main"` (or target branch)
This returns:
* `changed_symbols`: What was directly modified
* `potentially_affected`: Code that depends on changes
* `affected_documents`: Docs that may need updating
### Check Cross-Community Impact
Look for changes that affect multiple modules:
> "Which communities are affected by these changes?"
Review the `communities_impacted` in the impact detection results.
**Red flags:**
* Changes affecting 3+ communities
* High-cohesion communities being modified
* Changes to shared utilities or core modules
### Identify High-Centrality Changes
Check if important symbols are being modified:
> "Are any central functions being changed?"
Look for:
* Functions with many callers
* Core utilities
* Public APIs
```cypher
MATCH (caller)-[:CALLS]->(target:Symbol)
WHERE target.name IN ["changedFunction1", "changedFunction2"]
RETURN target.name, count(caller) as caller_count
ORDER BY caller_count DESC
```
### Verify Test Coverage
Check that impacted processes have test coverage:
> "Do the affected processes have tests?"
Review the `affected_processes` and verify each has corresponding tests.
### Review Affected Documentation
Check `affected_documents` from impact detection:
> "What docs need updating based on these changes?"
**Uses:** `noodlbox_search_documents` tool
Flag any documentation that references changed code.
### Document Coordination Needs
If multiple communities are affected:
* Note which teams need to be informed
* Identify integration points that need verification
* Document any breaking changes
## Code Review Checklist
* [ ] Run impact detection (`change_scope: "compare"`, `base_ref: target_branch`)
* [ ] Check cross-community impact
* [ ] Verify test coverage for impacted areas
* [ ] Review affected\_documents for outdated docs
* [ ] Flag high-centrality changes (many callers)
* [ ] Document coordination needs if multiple teams affected
## Risk Matrix for PR Review
| Impact | Callers | Risk | Action |
| -------------------- | ------- | -------- | ---------------------------- |
| Single community | \< 10 | Low | Standard review |
| Single community | 10-50 | Medium | Verify tests pass |
| Multiple communities | Any | High | Request additional reviewers |
| Core/shared code | > 50 | Critical | Require senior review |
## Example: Review a Feature PR
**PR:** Add email notification preferences
### Run Impact Detection
> "Check the impact comparing feature/email-prefs to main"
Results:
* 8 changed symbols
* 23 potentially affected
* 2 communities impacted (Notifications, UserSettings)
### Assess Risk
* Two communities affected (medium risk)
* Changes to NotificationService (check caller count)
```cypher
MATCH (caller)-[:CALLS]->(target:Symbol {name: "NotificationService"})
RETURN count(caller) as caller_count
```
Result: 15 callers (medium risk)
### Verify Coverage
Check that notification and settings tests exist and pass.
### Review Decision
* Risk: Medium
* Requires: Standard review + verify tests
* No additional reviewers needed
## Example: Review a Refactoring PR
**PR:** Split DataService into domain-specific services
### Run Impact Detection
Results:
* 45 changed symbols
* 120+ potentially affected
* 5 communities impacted
### Identify High-Risk Changes
```cypher
MATCH (caller)-[:CALLS]->(target:Symbol)
WHERE target.file_path CONTAINS "DataService"
RETURN target.name, count(caller) as caller_count
ORDER BY caller_count DESC
LIMIT 10
```
Flag the top callers for extra scrutiny.
### Check for Breaking Changes
Look for:
* Changed method signatures
* Removed exports
* New required parameters
### Review Decision
* Risk: High (5 communities, 120+ affected)
* Requires: Senior review
* Action: Break into smaller PRs if possible
## Useful Queries for Code Review
### Find All Callers of Changed Functions
```cypher
MATCH (caller)-[:CALLS]->(target:Symbol)
WHERE target.name IN $changedFunctions
RETURN target.name, collect(caller.name) as callers
```
### Check for Orphaned Code
```cypher
MATCH (sym:Symbol)
WHERE sym.file_path CONTAINS $removedFile
AND NOT (sym)<-[:CALLS]-()
AND sym.kind = "function"
RETURN sym.name as potentially_dead_code
```
### Verify Test File Exists
```cypher
MATCH (test:Symbol)
WHERE test.file_path CONTAINS "test" OR test.file_path CONTAINS "spec"
AND test.name CONTAINS $changedFunctionName
RETURN test.file_path
```
## Tools Reference
| Purpose | Tool |
| ------------------- | ------------------------------------------------------- |
| Compare branches | `noodlbox_detect_impact` with `change_scope: "compare"` |
| Find affected docs | `noodlbox_search_documents` |
| Understand context | `noodlbox_query_with_context` |
| Query relationships | `noodlbox_raw_cypher_query` |
# Debugging (/workflows/debugging)
Investigate bugs by tracing execution paths and understanding code relationships.
B[Identify Suspect]
B --> C[Trace Callers]
C --> D[Trace Callees]
D --> E[Check Recent Changes]`}
/>
## Quick Start
> "Why is the login failing with 'Invalid token'?"
> "Find code that throws AuthenticationError"
> "What calls validateToken?"
> "What changed recently in the auth module?"
## When to Use
Use this workflow when:
* Investigating error messages
* Tracing unexpected behavior
* Finding root causes
* Identifying regression sources
## Debugging Patterns
| Symptom | Approach |
| -------------------- | ---------------------------------------- |
| Error message | Search for error text, trace throw sites |
| Wrong return value | Trace data flow through callees |
| Intermittent failure | Look for external calls, race conditions |
| Recent regression | Use detect\_impact for recent changes |
| Performance issue | Trace execution flow, find hot paths |
## Debugging Workflow
### Search for Related Code
Start with the error message or behavior:
> "Find code related to 'Invalid token' error"
**Uses:** `noodlbox_query_with_context` tool
Look for:
* Where the error is thrown
* What conditions trigger it
* Related validation logic
### Identify the Suspect Function
Narrow down to the specific function:
> "Find the validateToken function"
Review the code to understand its logic.
### Trace Callers (Entry Points)
Find how the suspect code is reached:
> "What calls validateToken?"
**Uses:** `noodlbox_raw_cypher_query` tool
```cypher
MATCH (caller)-[:CALLS]->(target:Symbol {name: "validateToken"})
RETURN caller.name, caller.file_path
ORDER BY caller.file_path
```
This shows all paths that lead to the error.
### Trace Callees (Dependencies)
Find what the suspect code depends on:
> "What does validateToken call?"
```cypher
MATCH (source:Symbol {name: "validateToken"})-[:CALLS]->(callee)
RETURN callee.name, callee.file_path, callee.kind
```
This reveals:
* External service calls
* Database queries
* Other potential failure points
### Check Recent Changes
If this is a regression, find what changed:
> "What changed recently that might affect authentication?"
**Uses:** `noodlbox_detect_impact` tool
Review `changed_symbols` and `potentially_affected` for recent modifications.
### Trace the Full Execution Flow
For complex bugs, trace the entire process:
> "Trace the authentication process"
**Uses:** `map://current/process/{id}` resource
See the exact function call sequence from start to finish.
## Debugging Checklist
* [ ] Search for error message or related code
* [ ] Identify the specific function where the error occurs
* [ ] Trace all callers to understand entry points
* [ ] Trace all callees to find dependencies
* [ ] Check for recent changes with detect\_impact
* [ ] Review the full execution flow if needed
* [ ] Form hypothesis and verify
## Example: Debug Intermittent 500 Error
**Symptom:** Users occasionally get 500 errors on the checkout page
### Find the Error Source
> "Find code that handles checkout errors"
Locate the checkout controller and error handling.
### Identify External Calls
```cypher
MATCH (method)-[:DEFINED_IN]->(class:Symbol {name: "CheckoutController"})
MATCH (method)-[:CALLS]->(external)
WHERE external.file_path CONTAINS "service" OR external.file_path CONTAINS "client"
RETURN method.name, external.name, external.file_path
```
Result: `processPayment` calls `PaymentGateway.charge`
### Trace the Payment Flow
> "Trace the processPayment process"
See all functions involved in payment processing.
### Check for Race Conditions
```cypher
MATCH (method)-[:CALLS]->(dep)
WHERE method.name = "processPayment"
AND (dep.name CONTAINS "async" OR dep.name CONTAINS "Promise" OR dep.name CONTAINS "await")
RETURN dep.name, dep.file_path
```
Look for concurrent operations that might conflict.
### Review Recent Changes
> "What changed recently in the payment module?"
**Finding:** A recent change modified the timeout handling in PaymentGateway.
## Useful Cypher Patterns for Debugging
### Find Error Throw Sites
```cypher
MATCH (sym:Symbol)
WHERE sym.body CONTAINS "throw" AND sym.body CONTAINS "Error"
RETURN sym.name, sym.file_path
LIMIT 20
```
### Find Functions with External Calls
```cypher
MATCH (func:Symbol {kind: "function"})-[:CALLS]->(dep)
WHERE dep.file_path CONTAINS "node_modules"
OR dep.name CONTAINS "fetch"
OR dep.name CONTAINS "http"
RETURN func.name, func.file_path, collect(dep.name) as external_deps
```
### Find Functions in a Call Chain
```cypher
MATCH path = (entry:Symbol {name: "handleRequest"})-[:CALLS*1..5]->(target)
WHERE target.name = "validateToken"
RETURN [n IN nodes(path) | n.name] as call_chain
```
## Tools Reference
| Purpose | Tool |
| -------------------- | ----------------------------- |
| Find related code | `noodlbox_query_with_context` |
| Trace relationships | `noodlbox_raw_cypher_query` |
| Check recent changes | `noodlbox_detect_impact` |
| Full execution flow | `map://current/process/{id}` |
# Document Sync (/workflows/document-sync)
Find stale documentation that needs updating when code changes.
B[Get Symbol UIDs]
B --> C[Search Linked Docs]
C --> D[Review & Update]`}
/>
## Quick Start
> "What docs need updating after my changes?"
> "Find documentation that references the functions I modified"
> "Are there any stale docs referencing getUserData?"
## When to Use
Use this workflow:
* Before committing code changes
* During code review
* As part of your release process
* When updating APIs or public interfaces
## How It Works
Noodlbox creates bidirectional links between code and documentation:
| Edge Type | Direction | Meaning |
| --------------- | ---------- | ---------------------------- |
| `DOCUMENTED_BY` | Code → Doc | This code is documented here |
| `REFERENCES` | Doc → Code | This doc mentions this code |
Links are created when documentation contains:
* Inline code references: `` `functionName` ``
* Code blocks with function calls
* Prose mentioning symbol names
## Document Sync Workflow
### Detect Changed Symbols
First, find what code has changed:
> "What's the impact of my unstaged changes?"
**Uses:** `noodlbox_detect_impact` tool
This returns `changed_symbols` with UIDs for each modified symbol.
### Extract Symbol UIDs
From the impact detection response, collect the `uid` field from each changed symbol.
Example response:
```json
{
"changed_symbols": [
{ "name": "getUserData", "uid": "sym_abc123", ... },
{ "name": "UserService", "uid": "sym_def456", ... }
]
}
```
### Search for Linked Documentation
Find docs that reference the changed symbols:
> "Find documentation that references sym\_abc123 and sym\_def456"
**Uses:** `noodlbox_search_documents` tool with:
* `mode: "linked"`
* `symbol_uids: ["sym_abc123", "sym_def456"]`
This returns documentation files that:
* Are documented by these symbols
* Reference these symbols in their content
### Review and Update
For each flagged document:
1. Check if the code change affects the documentation
2. Update examples, descriptions, or signatures as needed
3. Remove references to deleted code
4. Add documentation for new functionality
## Document Types to Check
| Doc Type | What to Look For |
| ----------------- | ------------------------------------- |
| API docs | Changed signatures, new parameters |
| README | Updated examples, changed behavior |
| Tutorials | Outdated code snippets |
| Architecture docs | Changed relationships, new components |
| Changelogs | Needs new entry |
## Example: Pre-Commit Doc Check
**Scenario:** You've updated the authentication flow and want to check docs before committing.
### Run Impact Detection
> "Check the impact of my unstaged changes"
Results:
```json
{
"changed_symbols": [
{ "name": "authenticateUser", "uid": "sym_auth1" },
{ "name": "validateToken", "uid": "sym_tok1" },
{ "name": "refreshSession", "uid": "sym_sess1" }
]
}
```
### Search Linked Docs
> "Find docs linked to sym\_auth1, sym\_tok1, sym\_sess1"
Results:
* `docs/authentication.md` - references authenticateUser
* `README.md` - contains auth example
### Review Each Document
**docs/authentication.md:**
* Section "How to Authenticate" uses old function signature
* Update to reflect new parameter
**README.md:**
* Quick start example still valid
* No changes needed
### Commit with Doc Updates
Stage both code and documentation changes together.
## Automating Doc Sync
### In Code Review
Add doc sync check to your PR checklist:
```markdown
## PR Checklist
- [ ] Ran impact detection
- [ ] Checked affected_documents
- [ ] Updated stale documentation
```
### In CI/CD
Run doc sync check as part of your pipeline:
```yaml
# Example: Flag PRs with potentially stale docs
- name: Check doc sync
run: |
# Run impact detection comparing PR to base
# If affected_documents is non-empty, add PR comment
```
## Querying Documentation Relationships
### Find All Docs for a Symbol
```cypher
MATCH (sym:Symbol {name: "getUserData"})-[:DOCUMENTED_BY]->(doc:Document)
RETURN doc.file_path, doc.title
```
### Find All Symbols in a Doc
```cypher
MATCH (doc:Document {file_path: "README.md"})-[:REFERENCES]->(sym:Symbol)
RETURN sym.name, sym.kind, sym.file_path
```
### Find Potentially Stale Docs
```cypher
MATCH (sym:Symbol)-[:DOCUMENTED_BY]->(doc:Document)
WHERE sym.updated_at > doc.updated_at
RETURN doc.file_path, sym.name as stale_reference
```
## Tools Reference
| Purpose | Tool |
| ------------------- | ------------------------------------------------- |
| Detect changes | `noodlbox_detect_impact` |
| Find linked docs | `noodlbox_search_documents` with `mode: "linked"` |
| Query relationships | `noodlbox_raw_cypher_query` |
# Workflows (/workflows)
Step-by-step guides for common development tasks.
B[Implement]
B --> C[Debug]
C --> D[Code Review]
D --> E[Search Docs]
E --> F[Sync Docs]
F --> A
style A fill:#e1f5fe
style B fill:#fff3e0
style C fill:#ffebee
style D fill:#e8f5e9
style E fill:#f3e5f5
style F fill:#fce4ec`}
/>
Research and gather context before implementing
Plan safe refactors by mapping dependencies
Investigate bugs by tracing execution paths
Review PRs for quality, safety, and impact
Find documentation using semantic or linked search
Find stale docs that need updating
## How to Use These Guides
Each workflow guide includes:
1. **Quick Start**: Common prompts to get started
2. **When to Use**: Situations where this workflow applies
3. **Step-by-Step**: Detailed instructions
4. **Examples**: Real-world scenarios
5. **Tools Reference**: What tools to use and when
## Related
* [Platform](/platform) - Understand communities, processes, and the knowledge graph
* [MCP Server](/mcp) - Tools and resources for querying and analysis
# Refactoring (/workflows/refactoring)
Plan safe refactors by mapping dependencies BEFORE making changes.
B[Map Callers]
B --> C[Map Callees]
C --> D[Check Cross-Community]
D --> E[Preview Impact]`}
/>
## Quick Start
> "I want to rename getUserData to fetchUserProfile"
> "What calls getUserData?"
> "What would be impacted if I changed getUserData?"
## When to Use
Use this workflow when planning:
* Renaming functions, classes, or variables
* Extracting code into new modules
* Splitting services
* Moving code between files
* Deprecating APIs
## Refactoring Patterns
| Pattern | First Step |
| ---------------- | ------------------------------------------------------------ |
| Rename symbol | Use `noodlbox_rename_symbol` for automated multi-file rename |
| Extract module | Map internal dependencies |
| Split service | Group by domain, map cross-dependencies |
| Move to new file | Check import relationships |
| Deprecate API | Find all callers, plan migration path |
## Planning Workflow
### Find the Symbol
Locate the code you want to refactor:
> "Find the getUserData function"
**Uses:** `noodlbox_query_with_context` tool
### Get Full Symbol Context
Understand the symbol's role, all references, and community:
> "Show me the full context for getUserData"
**Uses:** `noodlbox_symbol_context` tool
Returns categorized incoming/outgoing references, community membership, and centrality score.
### Map All Callers
Find everything that depends on this code:
> "What calls getUserData?"
**Uses:** `noodlbox_raw_cypher_query` tool
```cypher
MATCH (caller)-[:CALLS]->(target:Symbol {name: "getUserData"})
RETURN caller.name, caller.file_path, caller.kind
ORDER BY caller.file_path
```
This tells you what will break if you change the signature.
### Map All Callees
Find everything this code depends on:
> "What does getUserData call?"
```cypher
MATCH (source:Symbol {name: "getUserData"})-[:CALLS]->(callee)
RETURN callee.name, callee.file_path, callee.kind
```
This tells you what you're bringing along if you move the code.
### Identify Cross-Community Dependencies
Check if refactoring crosses module boundaries:
> "Which communities reference getUserData?"
```cypher
MATCH (caller)-[:CALLS]->(target:Symbol {name: "getUserData"})
MATCH (caller)-[:BELONGS_TO]->(comm:Community)
RETURN DISTINCT comm.name, comm.label, count(caller) as caller_count
```
Cross-community changes require more coordination.
### Preview Impact
Before making changes, preview the blast radius:
> "What would be impacted if I changed getUserData?"
**Uses:** `noodlbox_detect_impact` tool
Review the `potentially_affected` symbols.
## Risk Assessment
| Indicator | Risk Level | Action |
| ---------------------------- | ---------- | ------------------------------ |
| \< 5 callers, same community | Low | Proceed with care |
| 5-20 callers, same community | Medium | Document changes, update tests |
| > 20 callers | High | Consider gradual migration |
| Cross-community callers | High | Coordinate with teams |
| Part of public API | Critical | Version and deprecate properly |
## Example: Planning a Rename
**Task:** Rename `getUserData` to `fetchUserProfile`
### Get Symbol Context
> "Show me the context for getUserData"
**Uses:** `noodlbox_symbol_context`
Returns: 12 incoming callers across 4 files, all in the "UserManagement" community. Centrality score: 0.72.
### Preview the Rename
> "Preview renaming getUserData to fetchUserProfile"
**Uses:** `noodlbox_rename_symbol` with `dry_run: true`
Returns: 4 files affected, 14 total edits (12 graph edits, 2 ast\_search edits), with per-file change details and confidence tags.
### Assess and Apply
* 12 graph edits (high confidence) -- auto-accept
* 2 ast\_search edits (lower confidence) -- review in test files
* Same community (low coordination risk)
* **Decision:** Apply the rename with `dry_run: false`
## Example: Planning a Service Split
**Task:** Split `DataService` into `UserDataService` and `ProductDataService`
### Map Internal Methods
```cypher
MATCH (method)-[:DEFINED_IN]->(class:Symbol {name: "DataService"})
RETURN method.name, method.kind
```
### Group by Domain
```cypher
MATCH (method)-[:DEFINED_IN]->(class:Symbol {name: "DataService"})
MATCH (method)-[:CALLS]->(dep)
RETURN method.name,
CASE
WHEN dep.name CONTAINS "User" THEN "user"
WHEN dep.name CONTAINS "Product" THEN "product"
ELSE "shared"
END as domain
```
### Identify Shared Dependencies
Methods calling both user and product code need special handling.
### Plan Extraction Order
1. Extract shared utilities first
2. Create `UserDataService` with user methods
3. Create `ProductDataService` with product methods
4. Update callers
5. Remove original `DataService`
## Tools Reference
| Purpose | Tool |
| ---------------- | ----------------------------- |
| Find code | `noodlbox_query_with_context` |
| Symbol deep-dive | `noodlbox_symbol_context` |
| Map dependencies | `noodlbox_raw_cypher_query` |
| Rename symbol | `noodlbox_rename_symbol` |
| Preview impact | `noodlbox_detect_impact` |
# Search Docs (/workflows/search-docs)
Search your repository's documentation to find relevant guides, READMEs, and API docs.
B[Search Docs]
B --> C[Review Results]
C --> D[Read or Update]`}
/>
## Quick Start
> "Find documentation about authentication"
> "What docs reference the PaymentService class?"
> "Show me API documentation for user management"
## When to Use
Use this workflow:
* When exploring an unfamiliar codebase
* Before implementing a feature to understand existing patterns
* When updating code and need to find related docs
* To discover API guides and tutorials
## Search Modes
| Mode | Use Case |
| ---------- | --------------------------------------------------------------- |
| `semantic` | General search - "find docs about X" |
| `linked` | Find docs for specific code symbols |
| `hybrid` | Both - when you have context symbols but also want topic search |
## Search Docs Workflow
### Choose Your Search Mode
**Semantic (default):** Natural language search
> "Find docs about authentication"
**Linked:** Find docs that reference specific symbols
> "Find docs linked to these symbols: sym\_abc123, sym\_def456"
**Hybrid:** Both approaches combined
> "Find auth docs, also check docs for the authenticateUser function"
### Search for Documentation
Ask your agent:
> "Search docs for 'API endpoints'"
**Uses:** `noodlbox_search_documents` tool
Results are separated into:
* `semantic_docs` - Documents matching your query text
* `related_docs` - Documents linked to code symbols
### Review Results
Each result includes:
* **Title** - Document section heading
* **File path** - Location in repository
* **Preview** - Snippet of content
Example:
```json
{
"semantic_docs": [
{
"title": "Authentication Guide",
"file_path": "docs/auth/README.md",
"preview": "This guide explains..."
}
]
}
```
### Read or Update
Ask your agent to read the full document:
> "Read docs/auth/README.md"
Or update it if needed:
> "Update the authentication guide with the new OAuth flow"
## Example: Finding API Documentation
**Scenario:** You need to understand how the user API works before adding a new endpoint.
### Search for User API Docs
> "Find documentation about user API endpoints"
Results:
* `docs/api/users.md` - User API Reference
* `README.md` - Quick start section on users
### Narrow with Code Context
If you know specific functions:
> "Find docs that reference getUserById and createUser"
**Uses:** `mode: "linked"` with `symbol_uids`
### Read and Learn
> "Read the User API Reference"
Now you understand the patterns and can implement your new endpoint consistently.
## Example: Finding Docs for Changed Code
**Scenario:** You modified authentication code and want to check if docs need updating.
### Get Changed Symbols
> "What's the impact of my changes?"
**Uses:** `noodlbox_detect_impact`
Results include `affected_documents` automatically.
### Search Linked Docs
> "Find docs linked to the changed symbols"
**Uses:** `mode: "linked"` with symbol UIDs from impact detection
### Update Stale Docs
Review each flagged document and update as needed.
See [Document Sync](/workflows/document-sync) for the full doc update workflow.
## Combining with Code Search
Documentation search complements code search:
| Need | Tool |
| --------- | ----------------------------- |
| Find code | `noodlbox_query_with_context` |
| Find docs | `noodlbox_search_documents` |
| Find both | Ask agent to search both |
**Example workflow:**
> "Find how authentication works - show me both the code and documentation"
Your agent will:
1. Search code with `noodlbox_query_with_context`
2. Search docs with `noodlbox_search_documents`
3. Combine results for a complete picture
## Tools Reference
| Purpose | Tool |
| ------------------- | -------------------------------------------------------- |
| Semantic doc search | `noodlbox_search_documents` with `mode: "semantic"` |
| Linked doc search | `noodlbox_search_documents` with `mode: "linked"` |
| Hybrid search | `noodlbox_search_documents` with `mode: "hybrid"` |
| Code search | `noodlbox_query_with_context` |
| Impact + docs | `noodlbox_detect_impact` (includes `affected_documents`) |
## Related
* [Document Sync](/workflows/document-sync) - Update stale documentation
* [Document Search Tool](/mcp/tools/document-search) - Full MCP tool reference
* [Context Search](/mcp/tools/context-search) - Search code, not docs
# Codebase Map (/mcp/resources/codebase-map)
Get a bird's-eye view of your repository's structure.
## URI
```
map://{repository}
```
## Response
```json
{
"repository": "owner/my-app",
"stats": {
"communities": 12,
"symbols": 450,
"processes": 35
},
"communities": [
{
"id": "comm_1",
"label": "Authentication",
"symbols": 85,
"cohesion": 0.92,
"key_symbols": ["authenticateUser", "validateToken"],
"entry_points": ["login", "signup"]
}
],
"cross_flows": [
{
"from": "Authentication",
"to": "DataAccess",
"calls": 47
}
]
}
```
## Key Fields
| Field | Description |
| -------------- | ------------------------------------------------------ |
| `cohesion` | 0-1, higher means tighter code coupling (0.8+ is good) |
| `key_symbols` | Most important functions in the community |
| `entry_points` | Functions called from outside the community |
| `cross_flows` | How communities depend on each other |
## Usage
Ask your agent:
> "Show me the codebase map"
> "Which communities handle authentication?"
> "What are the main dependencies between communities?"
## Related
* [Community Detail](/mcp/resources/community-resource) - Deep dive into a community
* [Process Trace](/mcp/resources/process-resource) - Follow execution flows
# Community Detail (/mcp/resources/community-resource)
Get detailed information about a community's symbols, processes, and connections.
## URI
```
map://{repository}/community/{community_id}
```
## Response
```json
{
"id": "comm_auth",
"label": "Authentication",
"stats": {
"symbols": 85,
"processes": 12,
"cohesion": 0.92
},
"symbols": [
{
"name": "authenticateUser",
"centrality": 0.95,
"location": "src/auth/authenticate.ts:42"
}
],
"entry_points": [
{
"name": "login",
"caller_community": "API",
"calls": 156
}
],
"processes": [
{
"id": "proc_login",
"label": "UserLogin",
"steps": 5
}
],
"connections": {
"outgoing": [{ "to": "DataAccess", "calls": 47 }],
"incoming": [{ "to": "API", "calls": 156 }]
}
}
```
## Key Fields
| Field | Description |
| -------------- | ------------------------------------------------- |
| `centrality` | 0-1, higher means more important to the community |
| `entry_points` | Functions called from outside this community |
| `connections` | Dependencies to/from other communities |
## Usage
Ask your agent:
> "Show me the Authentication community details"
> "What are the most important functions in this community?"
> "What processes exist in this community?"
## Related
* [Codebase Map](/mcp/resources/codebase-map) - Find community IDs
* [Process Trace](/mcp/resources/process-resource) - Trace processes
# Database Schema (/mcp/resources/database-schema)
View the structure of the knowledge graph before writing Cypher queries.
## URI
```
db://schema/{repository}
```
## Node Types
### CodeSymbol
Functions, classes, methods, variables, interfaces, enums, and more.
| Property | Type | Description |
| ------------- | ------ | ----------------------------- |
| `name` | STRING | Symbol name |
| `symbol_type` | STRING | Symbol kind (see table below) |
| `file_path` | STRING | File location |
| `line_number` | INT64 | Starting line |
| `content` | STRING | Full symbol body |
| `signature` | STRING | Symbol signature |
#### Symbol Types
**TypeScript:**
| Kind | Description |
| ----------- | --------------------------- |
| `Class` | ES6 class definition |
| `Method` | Class method |
| `Function` | Standalone function |
| `Attribute` | Class property |
| `Interface` | TypeScript interface |
| `TypeAlias` | Type alias (`type X = ...`) |
| `Enum` | Enum declaration |
| `Constant` | Const export |
| `Export` | Re-export statement |
**Python:**
| Kind | Description |
| ----------- | --------------------------------- |
| `Class` | Class definition |
| `Method` | Class method |
| `Function` | Standalone function |
| `Attribute` | Class attribute |
| `Enum` | Enum subclass |
| `Constant` | Module-level UPPER\_CASE constant |
| `TypeAlias` | Type alias assignment |
### File
Source files in the repository.
| Property | Type |
| ----------- | ------ |
| `path` | STRING |
| `extension` | STRING |
### Community
Code communities detected by modularity analysis.
| Property | Type | Description |
| -------------- | ------ | ---------------------------- |
| `label` | STRING | Community name |
| `cohesion` | DOUBLE | 0-1, higher is more cohesive |
| `symbol_count` | INT64 | Number of symbols |
### Process
Execution flows through the codebase.
| Property | Type | Description |
| -------------- | ------ | ------------------------------------ |
| `label` | STRING | Process name |
| `process_type` | STRING | intra\_community or cross\_community |
| `step_count` | INT64 | Number of steps |
## Relationships
| Relationship | From | To | Description |
| ----------------- | ---------- | ---------- | --------------------------- |
| `CALLS` | CodeSymbol | CodeSymbol | Function calls |
| `CONTAINED_BY` | CodeSymbol | File | Symbol in file |
| `MEMBER_OF` | CodeSymbol | Community | Symbol belongs to community |
| `STEP_IN_PROCESS` | CodeSymbol | Process | Step in execution flow |
## Example Query
```cypher
// Find all functions in the Authentication community
MATCH (s:CodeSymbol)-[:MEMBER_OF]->(c:Community)
WHERE c.label = "Authentication"
AND s.symbol_type = "Function"
RETURN s.name, s.file_path
```
## Related
* [Cypher Query Tool](/mcp/tools/cypher-query) - Execute queries
* [Codebase Map](/mcp/resources/codebase-map) - Explore communities
# Process Trace (/mcp/resources/process-resource)
See the exact sequence of function calls in an execution flow.
## URI
```
map://{repository}/process/{process_id}
```
## Response
```json
{
"id": "proc_login",
"label": "UserLogin",
"process_type": "cross_community",
"communities": ["API", "Authentication", "DataAccess"],
"trace": [
{ "step": 1, "name": "handleLoginRequest", "location": "src/api/auth.ts:45" },
{ "step": 2, "name": "authenticateUser", "location": "src/auth/authenticate.ts:67" },
{ "step": 3, "name": "getUserByEmail", "location": "src/data/users.ts:23" },
{ "step": 4, "name": "createSession", "location": "src/auth/session.ts:89" }
],
"related": [
{ "id": "proc_signup", "label": "UserSignup" }
]
}
```
## Key Fields
| Field | Description |
| -------------- | ----------------------------------------------------------------- |
| `process_type` | `intra_community` (localized) or `cross_community` (wider impact) |
| `communities` | Which communities this process touches |
| `trace` | Ordered function calls with file locations |
| `related` | Similar processes sharing entry points |
## Usage
Ask your agent:
> "Trace the login process"
> "Which communities does this process touch?"
> "What processes are similar to the signup flow?"
## Related
* [Community Detail](/mcp/resources/community-resource) - Find process IDs
* [Cypher Query](/mcp/tools/cypher-query) - Query process steps
# Repositories (/mcp/resources/repositories)
Discover which repositories you have access to.
## URI
```
repository://list
```
## Response
```json
{
"repositories": [
{
"id": "repo_1",
"name": "frontend",
"full_name": "myorg/frontend"
},
{
"id": "repo_2",
"name": "api-server",
"full_name": "myorg/api-server"
}
]
}
```
## Usage
Ask your agent:
> "What repositories do I have access to?"
> "Show me an overview of each repository"
Use the `name` field in other tool parameters and resource URIs.
Only repositories you've analyzed with `noodl analyze` will appear.
## Related
* [Codebase Map](/mcp/resources/codebase-map) - View repository structure
* [Database Schema](/mcp/resources/database-schema) - Explore graph structure
# Analyze (/mcp/tools/analyze)
The `noodlbox_analyze` tool indexes a repository, extracting code entities, relationships, and building a queryable knowledge graph.
## Parameters
| Parameter | Type | Required | Default | Description |
| -------------- | ------- | -------- | ------- | --------------------------------------- |
| `path` | string | Yes | - | Absolute path to the repository |
| `force` | boolean | No | `false` | Re-analyze even if already analyzed |
| `include_docs` | boolean | No | `true` | Include markdown documentation analysis |
## Usage
```
Analyze the repository at /path/to/my-project
```
The agent will call `noodlbox_analyze` with the path.
## When to Use
* **First-time setup**: Index a new repository before querying
* **After major changes**: Re-analyze with `force: true` after significant refactoring
* **Adding documentation**: Enable `include_docs` to link markdown files to code symbols
## What Gets Analyzed
The analysis extracts:
| Entity | Description |
| ----------------- | --------------------------------------------------------------- |
| **Symbols** | Functions, classes, methods, variables |
| **Files** | Source files with metadata |
| **Relationships** | Calls, imports, contains, inherits |
| **Communities** | Auto-detected clusters of related code |
| **Processes** | Execution flows through your application |
| **Documents** | Markdown files linked to code symbols (if `include_docs: true`) |
## Example
```
Use noodlbox_analyze to index /Users/me/projects/my-app with documentation included
```
Response:
```
Analysis complete for owner/my-app:
- 1,247 symbols extracted
- 3,892 relationships discovered
- 42 communities detected
- 156 processes identified
- 23 documents linked
```
## Related
* [Delete](/mcp/tools/delete) - Remove analyzed repositories
* [Context Search](/mcp/tools/context-search) - Search the knowledge graph
* [CLI Reference](/reference/cli-reference#noodl-analyze) - CLI equivalent
# Context Search (/mcp/tools/context-search)
Search your codebase with natural language. Results are grouped by process and ranked by relevance.
## Parameters
| Parameter | Type | Required | Description |
| ------------------------- | ------- | -------- | -------------------------------------------- |
| `repository` | string | Yes | Repository name (e.g., "owner/repo") |
| `q` | string | Yes | Natural language search query |
| `task_context` | string | Yes | Context about what you're working on |
| `current_goal` | string | Yes | Your immediate objective |
| `search_intention` | string | Yes | Why you're searching and what you plan to do |
| `include_content` | boolean | No | Include full symbol content (default: true) |
| `max_processes` | number | No | Max processes to return (1-300, default: 50) |
| `max_symbols_per_process` | number | No | Max symbols per process (1-100, default: 20) |
## Context Fields
The context fields help the search algorithm understand your intent:
| Field | Purpose | Example |
| ------------------ | ---------------------- | ---------------------------------------- |
| `task_context` | What you're working on | "Implementing user authentication" |
| `current_goal` | What you want to find | "Find login validation logic" |
| `search_intention` | Why you're searching | "Understand how auth works to add OAuth" |
## Example
Ask your agent:
> "Find code related to user authentication"
Or provide context for better results:
> "I'm adding OAuth support. Find the existing authentication code so I can understand how to integrate with it."
## Response Structure
Results include three symbol groups:
```json
{
"result": {
"total_count": 15,
"processes": [
{
"id": "proc_123",
"summary": "UserAuthentication",
"priority": 0.95,
"symbol_count": 5,
"avg_centrality": 0.72
}
],
"process_symbols": [
{
"id": "sym_456",
"process_id": "proc_123",
"name": "authenticateUser",
"symbol_type": "Function",
"file_path": "src/auth/authenticate.ts",
"signature": "async function authenticateUser(credentials: Credentials): Promise",
"content": "...",
"fts_score": 5.2,
"centrality_score": 0.85,
"step_index": 0,
"is_fts_match": true,
"selection_range_start_line": 45,
"selection_range_start_character": 0
}
],
"documents": [
{
"id": "doc_789",
"title": "Authentication Guide",
"file_path": "docs/auth/README.md",
"preview": "..."
}
],
"definitions": [
{
"id": "sym_def",
"name": "UserCredentials",
"symbol_type": "Interface",
"file_path": "src/types/auth.ts"
}
]
}
}
```
| Field | Description |
| ----------------- | ----------------------------------------------------------- |
| `processes` | Process metadata (summary, priority) without nested symbols |
| `process_symbols` | All symbols from process chains, flattened and deduplicated |
| `documents` | Matching markdown documentation chunks |
| `definitions` | Standalone DTOs, interfaces, types not in any process |
## Tips
* **Be specific**: "stripe webhook handler" beats "payment code"
* **Provide context**: Better task descriptions = better results
* **Start broad, then narrow**: Search "payments", then "refund processing"
* **Use `include_content: false`** for faster responses when you only need locations
## Related
* [Cypher Query](/mcp/tools/cypher-query) - Precise graph queries
* [Document Search](/mcp/tools/document-search) - Search documentation
* [Impact Detection](/mcp/tools/impact-detection) - Find affected code
# Cypher Query (/mcp/tools/cypher-query)
Query your code knowledge graph using Cypher. Read-only operations only.
## Parameters
| Parameter | Type | Required | Description |
| ------------- | ------ | -------- | -------------------------------------------------------- |
| `repository` | string | Yes | Repository name (e.g., "owner/repo") |
| `cypher` | string | Yes | Cypher query (read-only) |
| `max_results` | number | No | Safety limit for results (default: 10000, 0 = unlimited) |
## Supported Operations
| Supported | Not Supported |
| ---------------------------------- | ----------------------------- |
| `MATCH`, `RETURN`, `WHERE`, `WITH` | `CREATE`, `DELETE`, `SET` |
| `ORDER BY`, `LIMIT`, `SKIP` | `MERGE`, `DROP`, `ALTER` |
| `=`, `<>`, `<`, `>`, `<=`, `>=` | `STARTS WITH`, `ENDS WITH` |
| `AND`, `OR`, `NOT`, `CONTAINS` | `IN`, `=~` (regex), `IS NULL` |
Write operations (CREATE, DELETE, SET, MERGE) are blocked for safety.
## Common Queries
### Find functions by name
```cypher
MATCH (s:CODE_SYMBOL)
WHERE s.kind = "Function"
AND s.name CONTAINS "user"
RETURN s.name, s.file_path
LIMIT 20
```
### Find callers of a function
```cypher
MATCH (caller:CODE_SYMBOL)-[:CALLS]->(target:CODE_SYMBOL)
WHERE target.name = "authenticateUser"
RETURN caller.name, caller.file_path
```
### Trace call chains
```cypher
MATCH path = (start:CODE_SYMBOL)-[:CALLS*1..3]->(end:CODE_SYMBOL)
WHERE start.name = "handleRequest"
RETURN path
LIMIT 10
```
### Find cross-community calls
```cypher
MATCH (s1:CODE_SYMBOL)-[:MEMBER_OF]->(c1:COMMUNITY),
(s2:CODE_SYMBOL)-[:MEMBER_OF]->(c2:COMMUNITY),
(s1)-[:CALLS]->(s2)
WHERE c1 <> c2
RETURN c1.label, c2.label, count(*) as calls
ORDER BY calls DESC
```
### List communities by size
```cypher
MATCH (c:COMMUNITY)
RETURN c.label, c.size
ORDER BY c.size DESC
LIMIT 20
```
### Find symbols in a file
```cypher
MATCH (s:CODE_SYMBOL)
WHERE s.file_path CONTAINS "/auth/"
RETURN s.name, s.kind, s.file_path
```
## Workarounds for Unsupported Operators
| Instead of... | Use... |
| --------------------------------------- | ----------------------------------------------- |
| `WHERE s.name STARTS WITH "get"` | `WHERE s.name CONTAINS "get"` |
| `WHERE s.kind IN ["Function", "Class"]` | `WHERE s.kind = "Function" OR s.kind = "Class"` |
| `WHERE s.name =~ ".*User.*"` | `WHERE s.name CONTAINS "User"` |
## Query Patterns
| To get... | Query pattern |
| ------------------ | ----------------------------------------------------------- |
| Symbols only | `MATCH (s:CODE_SYMBOL) RETURN s.name, s.content` |
| Symbols + callers | `MATCH (caller)-[:CALLS]->(s:CODE_SYMBOL) RETURN s, caller` |
| Symbols + callees | `MATCH (s:CODE_SYMBOL)-[:CALLS]->(callee) RETURN s, callee` |
| Full relationships | `MATCH (s:CODE_SYMBOL)-[r]->(target) RETURN s, r, target` |
## Tips
* Always use `LIMIT` to avoid large result sets
* Filter early with `WHERE` for better performance
* Specify node labels: `CODE_SYMBOL`, `FILE`, `COMMUNITY`, `PROCESS`
* Use `max_results` as a safety net (the query's `LIMIT` takes precedence)
## Related
* [Database Schema](/mcp/resources/database-schema) - Node types and properties
* [Context Search](/mcp/tools/context-search) - Natural language search
# Delete (/mcp/tools/delete)
The `noodlbox_delete` tool removes a repository from noodlbox, deleting its knowledge graph and all associated data.
## Parameters
| Parameter | Type | Required | Description |
| ------------ | ------ | -------- | -------------------------------------- |
| `repository` | string | Yes | Repository name in `owner/repo` format |
## Usage
```
Delete the repository owner/my-old-project from noodlbox
```
The agent will call `noodlbox_delete` with the repository name.
## When to Use
* **Cleanup**: Remove repositories you no longer need indexed
* **Re-indexing**: Delete before a fresh analysis (alternative to `force: true`)
* **Storage management**: Free up local storage space
## What Gets Deleted
| Data | Description |
| --------------------- | -------------------------------------------------- |
| **Knowledge graph** | All symbols, relationships, communities, processes |
| **Vector embeddings** | Semantic search indexes |
| **Document links** | Markdown-to-code associations |
| **Local metadata** | Repository configuration and cache |
This action is irreversible. The repository must be re-analyzed to restore the knowledge graph.
## Example
```
Use noodlbox_delete to remove owner/deprecated-service
```
Response:
```
Deleted repository: owner/deprecated-service
```
## Related
* [Analyze](/mcp/tools/analyze) - Index a repository
* [CLI Reference](/reference/cli-reference#noodl-delete) - CLI equivalent
# Document Search (/mcp/tools/document-search)
Search your repository's documentation (markdown files, READMEs, guides) to find relevant docs.
## Parameters
| Parameter | Type | Required | Description |
| ------------- | --------- | -------- | ---------------------------------------------------------------------------- |
| `repository` | string | Yes | Repository name (e.g., "owner/repo") |
| `query` | string | Yes\* | Natural language search query |
| `mode` | string | No | Search mode: `"semantic"`, `"linked"`, or `"hybrid"` (default: `"semantic"`) |
| `symbol_uids` | string\[] | Yes\*\* | Symbol UIDs for linked/hybrid mode |
| `limit` | number | No | Max documents to return (1-100, default: 20) |
\*Required for `semantic` and `hybrid` modes
\*\*Required for `linked` mode, optional for `hybrid`
## Search Modes
B[Vector similarity search]
C[linked] --> D[Find docs via DOCUMENTED_BY edges]
E[hybrid] --> F[Both combined + deduped]`}
/>
| Mode | Use Case |
| ---------- | ------------------------------------------------------- |
| `semantic` | General doc search ("find docs about X") |
| `linked` | Find documentation for specific code symbols |
| `hybrid` | Both - when you have symbols but also want topic search |
### Semantic Mode (Default)
Finds documents semantically similar to your query using vector embeddings.
```json
{
"repository": "owner/my-project",
"query": "authentication setup guide",
"mode": "semantic"
}
```
### Linked Mode
Finds documents that reference specific code symbols via `DOCUMENTED_BY` edges. Requires `symbol_uids`.
```json
{
"repository": "owner/my-project",
"mode": "linked",
"symbol_uids": ["abc123", "def456"]
}
```
Use symbol UIDs from `noodlbox_query_with_context` or `noodlbox_detect_impact` results.
### Hybrid Mode
Combines both semantic and linked search, deduplicating results.
```json
{
"repository": "owner/my-project",
"query": "API usage",
"mode": "hybrid",
"symbol_uids": ["abc123"]
}
```
## Usage
Ask your agent:
> "Find documentation about the authentication system"
> "What docs reference the PaymentService class?"
> "Show me guides related to my staged changes"
## Response
```json
{
"semantic_docs": [
{
"id": "doc_123",
"title": "Authentication Guide",
"file_path": "docs/auth/README.md",
"preview": "This guide explains how to implement..."
}
],
"related_docs": [
{
"id": "doc_456",
"title": "API Reference",
"file_path": "docs/api/auth.md",
"preview": "The authenticateUser function..."
}
],
"mode": "hybrid"
}
```
| Field | Description |
| --------------- | --------------------------------------------------------- |
| `semantic_docs` | Documents matching query semantically (vector similarity) |
| `related_docs` | Documents linked to symbols via `DOCUMENTED_BY` edges |
## Workflow Example
1. **Find changed code** with `noodlbox_detect_impact`
2. **Get symbol UIDs** from the `changed_symbols` response
3. **Search for related docs** using linked or hybrid mode
4. **Update docs** alongside code changes
## Related
* [Context Search](/mcp/tools/context-search) - Search code, not documentation
* [Impact Detection](/mcp/tools/impact-detection) - Find code affected by changes
# Impact Detection (/mcp/tools/impact-detection)
Analyze your uncommitted changes to see which processes, symbols, and documentation are affected before committing.
## Parameters
| Parameter | Type | Required | Description |
| ------------------------- | ------- | -------- | ---------------------------------------------------- |
| `repository` | string | Yes | Repository name (e.g., "owner/repo") |
| `change_scope` | string | No | What to analyze (default: "unstaged") |
| `base_ref` | string | No | Base reference for "compare" scope (default: "HEAD") |
| `include_content` | boolean | No | Include symbol code content (default: false) |
| `max_processes` | number | No | Max processes per page (1-50, default: 10) |
| `max_symbols_per_process` | number | No | Max symbols per process (1-100, default: 20) |
| `page` | number | No | Page number for pagination (0-based, default: 0) |
## Change Scopes
B[Index vs Working Tree]
C[staged] --> D[HEAD vs Index]
E[all] --> F[HEAD vs Working Tree]
G[compare] --> H[base_ref vs Working Tree]`}
/>
| Scope | What it compares | Use Case |
| ---------- | -------------------------- | -------------------------------- |
| `unstaged` | Index vs working tree | See impact before `git add` |
| `staged` | HEAD vs index | Review before committing |
| `all` | HEAD vs working tree | Full picture of uncommitted work |
| `compare` | `base_ref` vs working tree | Compare against branch/commit |
For `compare` scope, you must provide an explicit `base_ref` (e.g., "main", "develop", or a commit SHA). Using "HEAD" with compare will return an error - use `all` scope instead.
## Usage
Ask your agent:
> "What processes are affected by my current changes?"
> "Check the impact of my staged changes before I commit"
> "Compare my changes against main branch"
## Response
```json
{
"summary": {
"changed_symbols_count": 3,
"changed_files_count": 2,
"total_impacted_processes": 5,
"total_impacted_symbols": 12,
"total_lines_changed": 47,
"affected_documents_count": 2,
"message": null
},
"changed_symbols": [
{
"id": "sym_123",
"name": "authenticateUser",
"file_path": "src/auth/login.ts",
"change_type": "Modified"
}
],
"changed_files": [
{
"path": "src/auth/login.ts",
"has_symbols": true,
"symbol_count": 2,
"lines_added": 15,
"lines_deleted": 5
}
],
"impacted_processes": [
{
"id": "proc_456",
"summary": "UserAuthentication",
"entry_point_id": "sym_789",
"symbols": [
{
"id": "sym_123",
"name": "authenticateUser",
"symbol_type": "Function",
"file_path": "src/auth/login.ts",
"is_changed": true,
"step_index": 0,
"centrality_score": 0.85,
"signature": "async function authenticateUser(...)",
"selection_range_start_line": 45,
"selection_range_start_character": 0
}
]
}
],
"affected_documents": [
{
"id": "doc_001",
"title": "Authentication Guide",
"file_path": "docs/auth/README.md",
"preview": "This document explains..."
}
],
"pagination": {
"page": 0,
"page_size": 10,
"total_pages": 1,
"has_more": false
}
}
```
## Understanding Results
| Field | Description |
| -------------------- | ------------------------------------------------------------- |
| `is_changed: true` | Symbols you directly modified |
| `is_changed: false` | Symbols in affected processes (potentially impacted) |
| `affected_documents` | Documentation linked to changed symbols (may need updating) |
| `has_symbols: false` | Files with changes but no analyzed code (configs, docs, etc.) |
### Empty Results
When no code changes are detected, `summary.message` explains why:
* **No uncommitted changes**: Working tree is clean
* **No symbols in changed files**: Changes are in configs, docs, or unsupported languages
## Change Types
| Type | Description |
| ---------- | ------------------------------ |
| `Modified` | Symbol content was changed |
| `Added` | New symbol in a changed file |
| `Deleted` | Symbol removed or file deleted |
## Common Workflows
**Before staging:**
```
"What's the impact of my unstaged changes?"
```
**Before committing:**
```
"Check impact of staged changes"
```
**Before creating PR:**
```
"Compare my changes against main branch"
```
## Related
* [Document Search](/mcp/tools/document-search) - Find docs for changed symbols
* [Context Search](/mcp/tools/context-search) - Search for related code
* [Process Resource](/mcp/resources/process-resource) - Understand affected flows
# Rename Symbol (/mcp/tools/rename-symbol)
Rename a symbol across your entire codebase. Discovers all references via the knowledge graph and AST-aware search, then previews or applies the rename with confidence tags on every edit.
## Parameters
| Parameter | Type | Required | Default | Description |
| ------------- | ------- | -------- | ------- | ---------------------------------------------------------------------- |
| `repository` | string | Yes | - | Repository name (e.g., "owner/repo") |
| `symbol_name` | string | No | - | Symbol name to rename (e.g., "getUserById", "BookingService.validate") |
| `symbol_uid` | string | No | - | Direct symbol UID from prior tool calls |
| `new_name` | string | Yes | - | The new name for the symbol |
| `file_path` | string | No | - | Relative file path to disambiguate common names |
| `dry_run` | boolean | No | `true` | Preview edits without modifying files |
Either `symbol_name` or `symbol_uid` must be provided. Default is `dry_run: true` (safe preview mode). Set `dry_run: false` to apply changes to disk.
## Usage
Ask your agent:
> "Rename getUserById to findUserById"
> "Preview a rename of PaymentService.process to PaymentService.execute"
> "Apply the rename of validateBooking to checkBooking"
## Response Format
The response is a tagged enum with two possible outcomes:
### Success
When the symbol is uniquely identified, returns the rename preview or result:
```json
{
"status": "success",
"old_name": "getUserById",
"new_name": "findUserById",
"files_affected": 4,
"total_edits": 7,
"graph_edits": 5,
"ast_search_edits": 2,
"changes": [
{
"file_path": "src/users/service.ts",
"edits": [
{
"line": 23,
"old_text": "export function getUserById(id: string): User {",
"new_text": "export function findUserById(id: string): User {",
"confidence": "graph"
}
]
},
{
"file_path": "src/auth/service.ts",
"edits": [
{
"line": 45,
"old_text": "const user = await getUserById(token.userId);",
"new_text": "const user = await findUserById(token.userId);",
"confidence": "graph"
}
]
},
{
"file_path": "src/users/service.spec.ts",
"edits": [
{
"line": 12,
"old_text": "describe('getUserById', () => {",
"new_text": "describe('findUserById', () => {",
"confidence": "ast_search"
}
]
}
],
"applied": false
}
```
### Ambiguous
When multiple symbols match the query, returns candidates for disambiguation:
```json
{
"status": "ambiguous",
"message": "Found 2 symbols matching 'validate'. Use symbol_uid or file_path to disambiguate.",
"candidates": [
{
"uid": "abc123",
"name": "validate",
"kind": "Function",
"file_path": "src/booking/validator.ts",
"line": 15
},
{
"uid": "def456",
"name": "validate",
"kind": "Method",
"file_path": "src/payment/processor.ts",
"line": 42
}
]
}
```
To resolve ambiguity, re-call the tool with the `symbol_uid` from the desired candidate.
## Response Fields
### Success Fields
| Field | Type | Description |
| ------------------ | ------- | ---------------------------------------------------------------- |
| `old_name` | string | The original symbol name |
| `new_name` | string | The new symbol name |
| `files_affected` | number | Number of files with changes |
| `total_edits` | number | Total number of individual edits |
| `graph_edits` | number | Edits from the knowledge graph (semantic, high confidence) |
| `ast_search_edits` | number | Edits from AST tree-sitter search (structural, lower confidence) |
| `changes` | array | Per-file changes with individual edits |
| `applied` | boolean | Whether changes were written to disk |
### Edit Confidence
Each edit is tagged with a confidence level indicating how it was discovered:
| Confidence | Source | Meaning |
| ------------ | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `graph` | Knowledge graph | Semantic reference from the analyzed graph. High confidence -- these are known callers, importers, and references. |
| `ast_search` | Tree-sitter AST search | Structural match found by scanning AST nodes. Lower confidence -- includes test files, string literals, and references not captured by the graph. |
Review `ast_search` edits carefully. They may include matches in comments, string literals, or unrelated symbols that happen to share the name.
### File Change
| Field | Type | Description |
| ----------- | ------ | ----------------------------------------- |
| `file_path` | string | Relative path within the repository |
| `edits` | array | Individual line-level edits for this file |
### Rename Edit
| Field | Type | Description |
| ------------ | ------ | ---------------------------- |
| `line` | number | 1-based line number |
| `old_text` | string | Original line text (trimmed) |
| `new_text` | string | Modified line text (trimmed) |
| `confidence` | string | `"graph"` or `"ast_search"` |
## Workflow
### Safe Rename (Recommended)
1. **Preview** the rename with `dry_run: true` (default)
2. **Review** the edits, paying attention to `ast_search` confidence edits
3. **Apply** by re-calling with `dry_run: false`
### Quick Rename
For well-isolated symbols with few references:
```
Rename getUserById to findUserById and apply the changes
```
The agent will call with `dry_run: false` directly.
## Tips
* **Always preview first** for symbols with many references
* **Use `symbol_uid`** from `noodlbox_symbol_context` results for unambiguous renames
* **Check `graph_edits` vs `ast_search_edits`** to understand edit confidence distribution
* **Auto-accept graph edits** -- they come from semantic analysis of the knowledge graph
* **Manually review `ast_search` edits** -- they may include false positives
* File paths are all relative to the repository root
## Related
* [Symbol Context](/mcp/tools/symbol-context) - Understand a symbol before renaming
* [Impact Detection](/mcp/tools/impact-detection) - Check impact after rename
* [Context Search](/mcp/tools/context-search) - Find related code
* [Refactoring Workflow](/workflows/refactoring) - Guided refactoring workflows
# Symbol Context (/mcp/tools/symbol-context)
Get a complete view of a code symbol: its definition, categorized references, community membership, and linked documentation.
## Parameters
| Parameter | Type | Required | Default | Description |
| ------------------- | ------- | -------- | ------- | ---------------------------------------------------------------- |
| `repository` | string | Yes | - | Repository name (e.g., "owner/repo") |
| `symbol_name` | string | No | - | Symbol name (e.g., "validateBooking", "BookingService.validate") |
| `symbol_uid` | string | No | - | Direct symbol UID from prior tool calls (zero-ambiguity lookup) |
| `file_path` | string | No | - | Relative file path to disambiguate common names |
| `include_content` | boolean | No | `false` | Include full symbol source code |
| `include_documents` | boolean | No | `false` | Include linked markdown documentation |
Either `symbol_name` or `symbol_uid` must be provided. Use `symbol_uid` when you already have a symbol ID from a prior tool call for instant, unambiguous lookup.
## Usage
Ask your agent:
> "Show me the full context for the authenticateUser function"
> "What calls BookingService.validate and what does it depend on?"
> "Get the symbol context for the function at src/auth/login.ts"
## Response Format
The response is a tagged enum with two possible outcomes:
### Found
When the symbol is uniquely identified, returns full 360-degree context:
```json
{
"status": "found",
"symbol": {
"uid": "abc123",
"name": "authenticateUser",
"kind": "Function",
"file_path": "src/auth/login.ts",
"start_line": 45,
"start_column": 0,
"end_line": 72,
"signature": "async function authenticateUser(credentials: Credentials): Promise",
"content": "...",
"centrality_score": 0.85
},
"incoming": {
"calls": [
{
"symbol_uid": "def456",
"name": "handleLogin",
"file_path": "src/controllers/auth.ts",
"line": 23,
"column": 4,
"kind": "Function"
}
],
"imports": [],
"extends": [],
"implements": [],
"contains": [],
"uses": []
},
"outgoing": {
"calls": [
{
"symbol_uid": "ghi789",
"name": "validateCredentials",
"file_path": "src/auth/validator.ts",
"line": 12,
"column": 0,
"kind": "Function"
}
],
"imports": [],
"extends": [],
"implements": [],
"contains": [],
"uses": []
},
"community": {
"community_uid": "comm_001",
"label": "Authentication",
"size": 24
},
"documents": [
{
"document_uid": "doc_001",
"title": "Authentication Guide",
"file_path": "docs/auth/README.md"
}
]
}
```
### Ambiguous
When multiple symbols match the query, returns candidates for disambiguation:
```json
{
"status": "ambiguous",
"message": "Found 3 symbols matching 'validate'. Use symbol_uid or file_path to disambiguate.",
"candidates": [
{
"uid": "abc123",
"name": "validate",
"kind": "Function",
"file_path": "src/booking/validator.ts",
"line": 15
},
{
"uid": "def456",
"name": "validate",
"kind": "Method",
"file_path": "src/payment/processor.ts",
"line": 42
},
{
"uid": "ghi789",
"name": "validate",
"kind": "Function",
"file_path": "src/auth/input.ts",
"line": 8
}
]
}
```
To resolve ambiguity, re-call the tool with the `symbol_uid` from the desired candidate.
## Response Fields
### Symbol Detail
| Field | Type | Description |
| ------------------ | ------ | --------------------------------------------------------------------- |
| `uid` | string | Unique symbol identifier (use for re-lookups) |
| `name` | string | Symbol name |
| `kind` | string | Symbol kind (Function, Class, Method, Interface, etc.) |
| `file_path` | string | Relative path within the repository |
| `start_line` | number | Start line of the symbol definition |
| `start_column` | number | Start column |
| `end_line` | number | End line |
| `signature` | string | Symbol signature (always included when available) |
| `content` | string | Full source code (only when `include_content: true`) |
| `centrality_score` | number | Importance score from community detection (higher = more central hub) |
### Categorized Edges
References are grouped by relationship type. Each edge includes the target symbol's `symbol_uid`, `name`, `file_path`, `line`, `column`, and `kind`.
| Category | Description |
| ------------ | ------------------------------------------------------ |
| `calls` | Function/method calls |
| `imports` | Import references |
| `extends` | Class inheritance |
| `implements` | Interface implementation |
| `contains` | Parent-child containment (e.g., class contains method) |
| `uses` | Variable/type usage |
Outgoing edges are deduplicated by target symbol. Empty categories are omitted from the response.
### Community Info
| Field | Description |
| --------------- | ---------------------------------- |
| `community_uid` | Community identifier |
| `label` | Human-readable community label |
| `size` | Number of symbols in the community |
## Lookup Precision
The tool supports three tiers of lookup precision:
| Tier | Parameter | Speed | Ambiguity |
| -------------- | --------------------------- | --------------- | -------------------------------------------------- |
| 1. UID lookup | `symbol_uid` | Sub-millisecond | None |
| 2. Name + file | `symbol_name` + `file_path` | Fast | Low |
| 3. Name only | `symbol_name` | Fast | Possible (returns `ambiguous` if multiple matches) |
## Tips
* **Start with name lookup**, then use `symbol_uid` from results for follow-up queries
* **Use `file_path`** to disambiguate common names like "validate", "process", "handle"
* **Check `centrality_score`** to identify key hub symbols in the architecture
* **Enable `include_documents`** to find documentation linked to the symbol
* **Combine with Cypher queries** for custom relationship traversals
## Related
* [Context Search](/mcp/tools/context-search) - Find symbols by natural language
* [Rename Symbol](/mcp/tools/rename-symbol) - Multi-file coordinated rename
* [Cypher Query](/mcp/tools/cypher-query) - Custom graph queries
* [Impact Detection](/mcp/tools/impact-detection) - Analyze change impact