# 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, 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)
* macOS (Intel)
* Linux (x64)
* Linux (ARM64)
* An MCP-compatible client (e.g., Claude Code, Cursor, Codex)
## Choose Your Approach
**Minimal setup, agent-driven**
Install once, let your agent handle analyze, search, and delete via MCP tools.
Best for: Getting started quickly
**Full control, explicit commands**
Run each CLI command yourself for complete control over the workflow.
Best for: CI/CD, scripting, batch operations
## Quick Start
### How It Works
Your agent has MCP tools to analyze, delete, search, and query repositories. You just need to initialize once.
### Install the CLI
Sign in to [noodlbox.io](https://noodlbox.io) and follow the installation instructions.
The installer runs `noodl init` automatically, which:
* Authenticates with noodlbox (opens browser)
* Configures MCP for your agents (Claude Code, Cursor, Codex)
### Let your agent work
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 follow the installation instructions in the dashboard.
### Authenticate
```bash
noodl auth
```
This opens your browser to authenticate with noodlbox.
### Analyze your repository
```bash
noodl analyze /path/to/your/repo
```
This extracts code entities and relationships, building a knowledge graph of your codebase.
### Configure your AI 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:generate_map`.
**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"]
```
### Explore your codebase
Start asking your agent questions:
```
"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
Navigate your codebase through communities and processes
Track down bugs using graph-based analysis
Understand dependencies and verify 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
# Claude Code Plugin (/integrations/claude-code-plugin)
The noodlbox plugin for Claude Code provides skills, commands, and agents 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 three 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` |
| **Agents** | Isolated exploration tasks | Spawned by commands for heavy work |
## Commands
Plugin commands use the `/noodlbox:command` format. These are the same as MCP prompts but with Claude Code's plugin namespacing:
| Plugin Command | MCP Equivalent |
| ------------------------- | ------------------------------- |
| `/noodlbox:init` | `/mcp__noodlbox__init` |
| `/noodlbox:generate_map` | `/mcp__noodlbox__generate_map` |
| `/noodlbox:detect_impact` | `/mcp__noodlbox__detect_impact` |
### `/noodlbox:init`
**Experimental** - This feature is still in development.
Initialize human-readable labels for communities and processes.
```
/noodlbox:init [repository]
```
Creates `.noodlbox/labels.json` with descriptive names for:
* **Communities** - "Authentication System" instead of "community\_42"
* **Processes** - "User Login Flow" instead of "handleLogin\_to\_validateToken"
The labels file is used by the CLI, MCP resources, and architecture generation.
### `/noodlbox:generate_map`
Generate comprehensive architecture documentation.
```
/noodlbox:generate_map [repository]
```
Creates an `ARCHITECTURE/` directory with:
* `README.md` - Overview, stats, mermaid diagram, module descriptions
* `{process-slug}.md` - Individual files for each key process
**Output structure:**
```
ARCHITECTURE/
├── README.md # Main overview + diagram
├── user-login-flow.md # Process documentation
├── checkout-process.md
└── ...
```
If `.noodlbox/labels.json` exists, uses human-readable names for modules and processes.
### `/noodlbox:detect_impact`
Analyze git changes and understand their ripple effects.
```
/noodlbox:detect_impact [change_scope]
```
**Change scopes:**
| Scope | Git Equivalent | Use Case |
| ---------- | ------------------- | ------------------------- |
| `unstaged` | `git diff` | Before staging |
| `staged` | `git diff --staged` | Before commit |
| `all` | `git diff HEAD` | All uncommitted (default) |
| `compare` | `git diff ` | Compare with branch |
**Output includes:**
* Changed symbols with file locations
* Impacted processes and their execution flows
* Risk level based on centrality scores
* Cross-community impact analysis
* Recommendations for testing
## Agents
Agents handle heavy exploration in isolated context to avoid polluting your conversation.
### Codebase Analyst
Adaptive exploration agent that scales based on codebase size:
| Scale | Communities | Strategy |
| ------ | ----------- | ------------------- |
| Small | \< 10 | Full exploration |
| Medium | 10-50 | Strategic sampling |
| Large | > 50 | High-level overview |
Used by `/noodlbox:generate_map` and `/noodlbox:detect_impact` for large codebases.
### Labeller
Generates human-readable labels for communities and processes. Used by `/noodlbox:init` (experimental).
## Skills
Skills teach Claude when and how to use Noodlbox tools effectively. They're automatically loaded with the plugin.
| Skill | When Claude Uses It |
| ---------------------------- | ---------------------------------------------------- |
| **Exploring Codebases** | "How does X work?", "What's the architecture?" |
| **Tracing Call Graphs** | "What calls X?", "Trace the flow from A to B" |
| **Assessing Change Impact** | "What will this break?", "Check the blast radius" |
| **Generating Documentation** | "Document the architecture", "Create a codebase map" |
Claude automatically selects the right skill based on your question - no need to invoke them manually.
## 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:generate_map # Generate architecture docs
```
## Workflow: Pre-Commit Review
Before committing changes:
```
1. /noodlbox:detect_impact staged # See what's affected
2. Review impacted processes
3. Plan testing based on impact
```
## Labels File
The `.noodlbox/labels.json` file stores 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:detect_impact` 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 same 6 skills:
* **Exploring Codebases** - Architecture and flow understanding
* **Debugging** - Bug tracking with graph queries
* **Refactoring** - Impact analysis for changes
* **Change Planning** - Pre-commit impact assessment
* **Generating Documentation** - Architecture map creation
* **Setup** - Initialize noodlbox context in a project
# 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_detect_impact` | Analyze git changes and their ripple effects |
| `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.
## 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.
## 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
# MCP Server (/mcp)
The MCP (Model Context Protocol) server connects noodlbox to agents like Claude Code and Cursor, 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
* **Prompts** - Pre-built exploration workflows
## 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"]
```
[Full setup guide →](/getting-started#manual-configuration)
## Tools
The MCP server provides tools for interacting with noodlbox.
**Depth Control:** Query tools support a `depth` parameter to control result detail:
* `"definitions"` (default) - Symbol signatures and full body content
* `"full"` - Symbols plus all relationships (calls, imports, edges)
### Query Tools
Find relevant code with natural language queries
Execute graph queries to explore code relationships
Analyze git changes to understand impact
### Management Tools
| Tool | Description |
| ------------------ | -------------------------------------------------- |
| `noodlbox_analyze` | Analyze a repository and build its knowledge graph |
| `noodlbox_delete` | Delete an analyzed repository from noodlbox |
These tools allow your agent to manage repositories directly through MCP.
## Resources
Access structured data through MCP resources using `@noodlbox:uri` syntax:
List analyzed repositories
Knowledge graph structure
Communities, processes, and navigation
## Prompts
Pre-built workflows that guide systematic code exploration:
| Prompt | MCP Command | Description |
| --------------- | ------------------------------- | ------------------------------------------------------------------------- |
| `init` | `/mcp__noodlbox__init` | Create human-readable labels (experimental) |
| `generate_map` | `/mcp__noodlbox__generate_map` | Generate `ARCHITECTURE/` directory with mermaid diagram and process files |
| `detect_impact` | `/mcp__noodlbox__detect_impact` | Guide for analyzing git changes with workflow-specific guidance |
**Usage:** Ask your agent to "use the generate\_map prompt" or use the MCP slash command directly.
**Claude Code users:** Use plugin commands instead: `/noodlbox:generate_map`, `/noodlbox:detect_impact`. See the [Claude Code plugin guide](/integrations/claude-code-plugin).
## Tools vs Resources vs Prompts
| Use | When |
| ------------- | --------------------------------------------------------- |
| **Tools** | Custom queries, searching patterns, analyzing impact |
| **Resources** | Structured data, exploring communities, viewing processes |
| **Prompts** | Guided workflows, systematic exploration, onboarding |
## 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: "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
# 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"
}
}
}
```
## Generating Labels
**Experimental** - The `/noodlbox:init` command is still in development.
Use the `/noodlbox:init` command in Claude Code to generate labels:
```
/noodlbox:init owner/my-repo
```
This spawns a labeller agent that:
### Reads all communities and their key symbols
### Analyzes symbol names, file paths, and patterns
### Generates descriptive labels and descriptions
### Writes the `.noodlbox/labels.json` file
For large codebases, the labeller processes communities in batches for efficiency.
## How Labels are Generated
### 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.
### Architecture Generation
The `/noodlbox:generate_map` command uses labels for:
* Module names in `ARCHITECTURE/README.md`
* Process file names (e.g., `user-login-flow.md`)
* Section titles and descriptions
### Impact Analysis
The `/noodlbox:detect_impact` command uses labels for:
* Process names in impact reports
* Community names in cross-module analysis
## Updating Labels
Re-run the init command to regenerate labels:
```
/noodlbox:init owner/my-repo
```
This will:
### Read existing labels
### Detect new communities/processes
### Generate labels for new items
### Preserve existing labels (unless they no longer exist)
## Manual Editing
You can manually edit `.noodlbox/labels.json` to:
* Improve auto-generated labels
* Add 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
# 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 must use the `owner/repo` format:
```bash
# Correct
noodl analyze /path/to/repo # Creates owner/repo from git remote
noodl delete owner/my-repo # Reference by name
noodl search owner/my-repo "query" # Search in repository
# Invalid
noodl delete my-repo # Missing owner prefix
```
## Core Commands
Commands for analyzing and querying your codebase.
### noodl analyze
Analyze a repository and build its knowledge graph.
```bash
noodl analyze
```
**Examples:**
```bash
noodl analyze . # Current directory
noodl analyze /path/to/repo # Absolute path
noodl analyze --force . # Re-analyze from scratch
```
### noodl list
List all analyzed repositories.
```bash
noodl list
```
### noodl delete
Delete an analyzed repository from noodlbox.
```bash
noodl delete
```
**Examples:**
```bash
noodl delete owner/my-repo
```
### 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 ""
```
**Examples:**
```bash
noodl search owner/my-repo "authentication flow"
noodl search owner/my-repo "functions that call the database"
```
### noodl query
Execute a Cypher query against the knowledge graph.
```bash
noodl query ""
```
**Examples:**
```bash
noodl query owner/my-repo "MATCH (s:CODE_SYMBOL) RETURN s.name LIMIT 10"
```
## 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
```
## Integration Commands
Commands for configuring AI agent integrations.
### noodl init
First-time setup for noodlbox. This is the recommended starting point.
```bash
noodl init
```
This command:
* Creates required directories (`~/.noodlbox/state`, `~/.noodlbox/repositories`)
* Authenticates with noodlbox (opens browser)
* Configures MCP for your agents (Claude Code, Cursor, Codex)
**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
```
This command:
* Removes `~/.noodlbox` directory (all data, config, repositories)
* Re-runs `noodl init` for fresh setup
Use this when you need to start completely fresh or fix configuration issues.
### noodl configure
Configure AI agents (Claude Code, Cursor, Codex) globally.
```bash
noodl configure
```
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 (/skills/change-planning)
Analyze uncommitted git changes and understand their ripple effects through the codebase.
**Invoke with:** `/noodlbox:change-planning`
## Quick Decision
| Workflow | change\_scope | base\_ref |
| ----------------- | ------------- | --------- |
| Before staging | `"unstaged"` | - |
| Before commit | `"staged"` | - |
| All uncommitted | `"all"` | - |
| Compare to branch | `"compare"` | `"main"` |
## Tool Reference
### noodlbox\_detect\_impact
Detect which processes are affected by git changes.
```
noodlbox_detect_impact(
repository: "current",
change_scope: "all",
include_content: false,
max_processes: 10
)
```
**Parameters:**
* `change_scope`: What changes to analyze (see table above)
* `base_ref`: Branch/commit to compare against (for `"compare"` scope)
* `include_content`: Include symbol source code in response
* `max_processes`: Limit results per page
## Risk Assessment
| Metric | Low Risk | Medium Risk | High Risk |
| -------------------------- | -------- | ----------- | --------- |
| `changed_symbols_count` | \< 5 | 5-15 | > 15 |
| `total_impacted_processes` | \< 10 | 10-30 | > 30 |
| Cross-community changes | None | 1-2 | > 2 |
## Workflow Checklist
### Pre-Commit Review
```
Pre-Commit Checklist:
- [ ] Run impact detection (scope: staged)
- [ ] Check changed_symbols count
- [ ] Review each impacted_process
- [ ] Verify changes are intentional
- [ ] Split commit if impact > 10 processes
```
### Code Review
```
Code Review Checklist:
- [ ] Run impact detection (scope: compare, base_ref: target_branch)
- [ ] Check cross-community impact
- [ ] Verify test coverage for impacted areas
- [ ] Flag high-centrality changes
- [ ] Document coordination needs
```
## Example: Pre-Commit Check
**Task:** "What will my changes affect before I commit?"
### Run impact detection
> "What will my staged changes affect?"
**Uses:** `noodlbox_detect_impact` with `change_scope: "staged"`
Summary: 3 changed symbols, 7 impacted processes
### Review changed symbols
* validatePayment (src/payments/validator.ts:42) - Modified
* PaymentError (src/payments/errors.ts:15) - Modified
* formatAmount (src/payments/utils.ts:88) - Modified
### Review impacted processes
* "Checkout flow" (5 steps affected)
* "Payment retry" (3 steps affected)
* "Webhook handler" (2 steps affected)
### Assess risk
* Changed: 3 symbols → Low
* Impacted: 7 processes → Low
* Cross-community: None → Low
* **Overall: Low risk, safe to commit**
## Output Format
### Low Impact (\< 10 processes)
```markdown
## Impact Summary
- **Changed**: 3 symbols in 2 files
- **Affected**: 7 processes
- **Risk**: Low
## Changed Code
| Symbol | File | Type |
|--------|------|------|
| validatePayment | src/payments/validator.ts:42 | Modified |
## Affected Flows
1. **Checkout flow** - 5 steps include changed symbols
- Entry: `handleCheckout` → `processPayment` → `validatePayment`
- Risk: Low (isolated change)
## Recommendations
- [ ] Run payment integration tests
- [ ] Verify checkout flow manually
```
### High Impact (> 10 processes)
Delegate to codebase-analyst agent for detailed analysis.
## When to Use Something Else
| Need | Use Instead |
| ----------------------- | ------------------------------------------------------------ |
| Explore unfamiliar code | [Exploring Codebases](/skills/exploring-codebases) |
| Generate documentation | [Generating Documentation](/skills/generating-documentation) |
| Debug failing code | [Debugging](/skills/debugging) |
| Plan large refactors | [Refactoring](/skills/refactoring) |
# Debugging (/skills/debugging)
Investigate bugs by understanding code relationships and tracing execution paths.
**Invoke with:** `/noodlbox:debugging`
## Quick Start
```
1. noodlbox_query_with_context → Find code related to the error
2. READ map://current/process/[id] → Trace execution flow
3. noodlbox_raw_cypher_query → Find callers/callees of suspect code
```
## Tool Reference
### noodlbox\_query\_with\_context
Find code semantically related to the error or symptom.
```
noodlbox_query_with_context(
repository: "current",
q: "payment validation error handling",
task_context: "debugging payment failures",
current_goal: "find where validation errors originate",
search_intention: "trace error path",
limit: 5,
max_symbols: 10
)
```
### noodlbox\_detect\_impact
Find what recent changes might have introduced the bug.
```
noodlbox_detect_impact(
repository: "current",
change_scope: "all",
include_content: true
)
```
### noodlbox\_raw\_cypher\_query
Trace callers and callees of suspect functions.
```cypher
-- Who calls the failing function?
MATCH (caller)-[:CALLS]->(target:CODE_SYMBOL {name: "validatePayment"})
RETURN caller.name, caller.file_path LIMIT 20
-- What does the failing function call?
MATCH (source:CODE_SYMBOL {name: "validatePayment"})-[:CALLS]->(target)
RETURN target.name, target.file_path LIMIT 20
```
## Workflow Checklist
```
Bug Investigation:
- [ ] Understand the symptom (error message, unexpected behavior)
- [ ] Search for related code with query_with_context
- [ ] Identify the failing function/component
- [ ] Trace callers to find entry points
- [ ] Trace callees to find dependencies
- [ ] Check recent changes with detect_impact
- [ ] Read source files for root cause
- [ ] Form hypothesis and verify
```
## Example: Debug Payment Failure
**Task:** "The payment endpoint returns a 500 error intermittently"
### Find payment error handling
> "Find code related to payment error handling"
**Uses:** `noodlbox_query_with_context`
Results show: validatePayment, handlePaymentError, PaymentException
### Trace callers
> "Who calls validatePayment?"
**Uses:** `noodlbox_raw_cypher_query`
Callers: processCheckout, webhookHandler
### Trace callees
> "What does validatePayment call?"
**Uses:** `noodlbox_raw_cypher_query`
Callees: verifyCardExpiry, checkAmount, fetchRates (external call!)
### Form hypothesis
`fetchRates` calls external API → intermittent failures
Read `src/external/currency.ts` to verify error handling
### Root cause found
`fetchRates` doesn't handle timeout properly
## 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 |
| Performance issue | Find hot paths via centrality |
| Recent regression | Use detect\_impact to find recent changes |
## When to Use Something Else
| Need | Use Instead |
| ----------------------- | ------------------------------------------------------------ |
| Explore unfamiliar code | [Exploring Codebases](/skills/exploring-codebases) |
| Plan safe changes | [Change Planning](/skills/change-planning) |
| Large refactoring | [Refactoring](/skills/refactoring) |
| Generate documentation | [Generating Documentation](/skills/generating-documentation) |
# Exploring Codebases (/skills/exploring-codebases)
Semantic code exploration that returns **processes** (execution flows) instead of isolated file matches.
**Invoke with:** `/noodlbox:exploring-codebases`
## Quick Start
```
1. READ map://current → Get codebase overview (~200 tokens)
2. READ map://current/community/[id] → Drill into relevant module
3. noodlbox_query_with_context → Search for specific concepts
```
## Workflow Checklist
```
Exploration Progress:
- [ ] Read map overview
- [ ] Identify relevant community
- [ ] Drill into community detail
- [ ] Search for specific symbols
- [ ] Read source files
```
## Tool Reference
### noodlbox\_query\_with\_context
Semantic search returning processes ranked by relevance.
```
noodlbox_query_with_context(
repository: "current",
q: "payment validation",
task_context: "exploring payment system",
current_goal: "understand validation flow",
search_intention: "find entry points",
limit: 5,
max_symbols: 10
)
```
**Output structure:**
```
Process: "Payment validation starting with validatePayment"
├── validatePayment (src/payments/validator.ts:42) ← matched
├── checkAmount (src/payments/validator.ts:78)
├── verifyCard (src/payments/card.ts:15)
└── processTransaction (src/payments/processor.ts:23)
```
**Start with `limit: 3-5`**. Increase only if needed.
## Resources
### map\://current
Codebase overview with communities, stats, and cross-flows.
```yaml
repository: my-project
stats: { communities: 15, symbols: 2400, processes: 890 }
communities:
- id: abc123, label: PaymentProcessing, symbols: 47
- id: def456, label: UserAuthentication, symbols: 32
cross_flows:
- from: PaymentProcessing, to: UserAuthentication, calls: 12
```
**Token cost:** \~200 tokens. Read first when unfamiliar with codebase.
### map\://current/community/\[id]
Community detail with symbols ranked by importance.
```yaml
id: abc123
label: PaymentProcessing
symbols:
- name: validatePayment, centrality: 0.92, file: src/payments/validator.ts
- name: processCharge, centrality: 0.78, file: src/payments/processor.ts
entry_points:
- name: handlePaymentRequest, callers: [APIGateway, WebhookHandler]
processes:
- id: xyz789, label: "Payment validation flow"
```
**Token cost:** \~500 tokens. Use after identifying relevant community.
### map\://current/process/\[id]
Full execution trace with file paths and line numbers.
**Use when:** Need complete call chain for a specific flow.
## Key Concepts
| Term | Meaning |
| --------------- | ------------------------------------------------------ |
| **Community** | Cluster of tightly-coupled symbols (functional module) |
| **Process** | Execution flow from entry point through call chain |
| **Centrality** | Symbol importance - high means many callers/callees |
| **Entry point** | Symbol called from outside its community |
## Example: Explore Authentication
**Task:** "How does authentication work in this codebase?"
### Get overview
> "Show me the codebase map"
**Uses:** `map://current`
See "UserAuthentication" community (32 symbols, high cohesion)
### Drill into auth community
> "Show me the Authentication community"
**Uses:** `map://current/community/[auth-id]`
Key symbols: login, validateToken, refreshSession
### Search for specifics
> "Find code related to token validation"
**Uses:** `noodlbox_query_with_context`
Focused results from the auth area with file paths and line numbers
### Read source
Read `src/auth/token.ts` to understand implementation details
## When to Use Something Else
| Need | Use Instead |
| ------------------- | ------------------------------------------ |
| Check change impact | [Change Planning](/skills/change-planning) |
| Debug failing code | [Debugging](/skills/debugging) |
| Plan refactoring | [Refactoring](/skills/refactoring) |
| Find exact string | Grep (faster for literal matches) |
| Read specific file | Read tool directly |
# Generating Documentation (/skills/generating-documentation)
Create architecture documentation from the code knowledge graph.
**Invoke with:** `/noodlbox:generating-documentation`
## Available Commands
### /noodlbox:init
Generate human-readable labels for communities and processes.
Creates `.noodlbox/labels.json` with descriptive names.
### /noodlbox:generate\_map
Generate comprehensive architecture documentation.
Creates `ARCHITECTURE/` directory with:
* `README.md` - Main overview with mermaid diagram
* `[process-slug].md` - Individual process files
## Quick Start
```
1. Check for labels: Look for .noodlbox/labels.json
2. If missing: Run /noodlbox:init first
3. Then: Run /noodlbox:generate_map
```
## Workflow Checklist
### Generate Labels
```
Label Generation:
- [ ] Read map://current for community list
- [ ] For each community, identify purpose
- [ ] Generate descriptive labels
- [ ] Create .noodlbox/labels.json
- [ ] Verify labels make sense
```
### Generate Architecture Map
```
Architecture Map:
- [ ] Check for .noodlbox/labels.json
- [ ] Read map://current for overview
- [ ] Drill into top communities
- [ ] Generate mermaid diagram
- [ ] Write ARCHITECTURE/README.md
- [ ] Create process files
```
## Resources Used
### map\://current
Get codebase overview with communities and cross-flows.
```yaml
repository: my-project
stats: { communities: 15, symbols: 2400, processes: 890 }
communities:
- id: abc123, label: PaymentProcessing, symbols: 47
cross_flows:
- from: PaymentProcessing, to: UserAuthentication, calls: 12
```
### map\://current/community/\[id]
Get community detail with symbols and processes.
### map\://current/process/\[id]
Get full execution trace for a process.
## Mermaid Diagram Tips
```mermaid
graph TB
subgraph Auth["Authentication System"]
login[login]
validate[validateToken]
end
subgraph Payment["Payment Processing"]
checkout[checkout]
process[processPayment]
end
Auth -->|47 calls| Payment
```
**Guidelines:**
* Sanitize IDs: Replace spaces with underscores
* Use subgraphs for communities
* Add call counts on edges
* Keep labels short
* Use `graph TB` for top-to-bottom layout
## Example: Generate Architecture Map
**Task:** "Document the architecture of this codebase"
### Check for existing labels
Look for `.noodlbox/labels.json`
→ Not found
### Generate labels first
> "/noodlbox:init"
→ Created `.noodlbox/labels.json` with 15 community labels
### Read overview
> "Show me the codebase map"
**Uses:** `map://current`
→ 15 communities, 2400 symbols, 890 processes
→ Top communities: PaymentProcessing, UserAuthentication, DataAccess
### Explore key communities
> "Show me the PaymentProcessing community"
**Uses:** `map://current/community/[payment-id]`
→ Key symbols: validatePayment, processCharge
→ Entry points: handlePaymentRequest
→ 12 processes
### Generate README
Write `ARCHITECTURE/README.md` with:
* Summary from community analysis
* Stats from map
* Data flows from cross\_flows
* Mermaid diagram from communities
### Generate process files
For each key process:
* Read `map://current/process/[id]`
* Write `ARCHITECTURE/[process-slug].md`
## Output Structure
```
ARCHITECTURE/
├── README.md # Main overview
├── checkout-flow.md # Process: Checkout flow
├── user-login.md # Process: User login
└── payment-processing.md # Process: Payment processing
```
## When to Use Something Else
| Need | Use Instead |
| ------------------- | -------------------------------------------------- |
| Explore code first | [Exploring Codebases](/skills/exploring-codebases) |
| Check change impact | [Change Planning](/skills/change-planning) |
| Debug failing code | [Debugging](/skills/debugging) |
| Plan refactoring | [Refactoring](/skills/refactoring) |
# Skills (/skills)
Skills are structured prompts that guide your AI agent through complex tasks using noodlbox's knowledge graph.
B[Debug]
B --> C[Plan]
C --> D[Refactor]
D --> E[Document]
style A fill:#e3f2fd
style B fill:#ffebee
style C fill:#fff3e0
style D fill:#e8f5e9
style E fill:#f3e5f5`}
/>
## Available Skills
Navigate unfamiliar code and understand architecture
Trace bugs and find root causes
Analyze blast radius before committing
Plan safe renames, extractions, and restructuring
Create architecture docs from the knowledge graph
Initialize noodlbox context for a project
## How to Use Skills
Skills are invoked via slash commands in your AI agent:
```
/noodlbox:exploring-codebases
/noodlbox:debugging
/noodlbox:change-planning
/noodlbox:refactoring
/noodlbox:generating-documentation
/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 |
| ---------------------------------- | ------------------------------------------------------------ |
| "How does this code work?" | [Exploring Codebases](/skills/exploring-codebases) |
| "Why is this failing?" | [Debugging](/skills/debugging) |
| "What will my changes break?" | [Change Planning](/skills/change-planning) |
| "I want to rename/move this" | [Refactoring](/skills/refactoring) |
| "Document the architecture" | [Generating Documentation](/skills/generating-documentation) |
| "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
# Refactoring (/skills/refactoring)
Plan and execute safe refactoring by understanding dependencies and impact.
**Invoke with:** `/noodlbox:refactoring`
## Quick Start
```
1. noodlbox_query_with_context → Find the code to refactor
2. noodlbox_raw_cypher_query → Map all dependencies
3. noodlbox_detect_impact → Preview blast radius
```
## Tool Reference
### noodlbox\_query\_with\_context
Find code related to the refactoring target.
```
noodlbox_query_with_context(
repository: "current",
q: "payment processing service",
task_context: "planning to split PaymentService",
current_goal: "find all payment-related code",
search_intention: "map dependencies before refactor",
limit: 10
)
```
### noodlbox\_raw\_cypher\_query
Map dependencies for safe refactoring.
```cypher
-- Find all callers (what depends on this?)
MATCH (caller)-[:CALLS]->(target:CODE_SYMBOL {name: "PaymentService"})
RETURN caller.name, caller.file_path, caller.community_id
ORDER BY caller.community_id
-- Find all callees (what does this depend on?)
MATCH (source:CODE_SYMBOL {name: "PaymentService"})-[:CALLS]->(callee)
RETURN callee.name, callee.file_path
ORDER BY callee.name
-- Find symbols that would need updating after rename
MATCH (s:CODE_SYMBOL)
WHERE s.name CONTAINS "Payment"
RETURN s.name, s.kind, s.file_path
ORDER BY s.file_path
```
### noodlbox\_detect\_impact
Preview what would be affected by the refactor.
```
noodlbox_detect_impact(
repository: "current",
change_scope: "all",
include_content: false,
max_processes: 20
)
```
## Workflow Checklists
### Rename a Symbol
```
Rename Refactoring:
- [ ] Find all references to the symbol
- [ ] Check for string literals using the name
- [ ] Identify test files that reference it
- [ ] Check for external API surface changes
- [ ] Plan rename order (interfaces → implementations → usages)
- [ ] Verify no dynamic references (reflection, string keys)
```
### Extract Module
```
Extract Module Refactoring:
- [ ] Identify code to extract
- [ ] Map all internal dependencies
- [ ] Map all external callers
- [ ] Define new module interface
- [ ] Plan extraction order
- [ ] Update imports across codebase
```
### Split Service
```
Split Service Refactoring:
- [ ] Map current service responsibilities
- [ ] Group related methods by domain
- [ ] Identify shared state/dependencies
- [ ] Define new service boundaries
- [ ] Plan migration path
- [ ] Create facade for backwards compatibility (if needed)
```
## Example: Rename getUserById to findUserById
**Task:** "I want to rename getUserById to findUserById. What needs to change?"
### Find all references
> "Find all callers of getUserById"
**Uses:** `noodlbox_raw_cypher_query`
Callers: AuthService.validateToken, ProfileController.getProfile, OrderService.getOrderOwner, UserController.show
### Find the definitions
> "Where is getUserById defined?"
**Uses:** `noodlbox_raw_cypher_query`
Definitions: UserService (src/users/service.ts), UserRepository (src/users/repository.ts)
### Check for tests
> "Find tests for getUserById"
**Uses:** `noodlbox_query_with_context`
Tests: user.service.spec.ts, user.repository.spec.ts
### Create rename plan
Files to update:
1. src/users/service.ts (definition)
2. src/users/repository.ts (definition)
3. src/auth/service.ts (caller)
4. src/profile/controller.ts (caller)
5. src/orders/service.ts (caller)
6. src/users/controller.ts (caller)
7. src/users/service.spec.ts (test)
8. src/users/repository.spec.ts (test)
## Example: Split PaymentService
**Task:** "Can I split PaymentService into separate services? Show dependencies."
### Understand current structure
> "What methods does PaymentService have?"
**Uses:** `noodlbox_query_with_context`
Methods: processPayment, refundPayment, validateCard, calculateFees, sendReceipt, generateReport
### Map internal dependencies
> "What do PaymentService methods call internally?"
**Uses:** `noodlbox_raw_cypher_query`
* processPayment → validateCard, calculateFees, sendReceipt
* refundPayment → calculateFees
### Map external callers
> "Who calls PaymentService from outside?"
**Uses:** `noodlbox_raw_cypher_query`
* CheckoutHandler → processPayment
* WebhookHandler → processPayment
* AdminController → refundPayment
* ReportJob → generateReport
### Suggest split
Based on dependencies:
* **PaymentProcessingService**: processPayment, validateCard, calculateFees
* **PaymentNotificationService**: sendReceipt
* **PaymentReportService**: generateReport
* **PaymentRefundService**: refundPayment, calculateFees (shared)
## Risk Assessment
| Metric | Low Risk | Medium Risk | High Risk |
| ----------------------- | -------- | ----------- | --------- |
| Callers count | \< 5 | 5-20 | > 20 |
| Cross-community callers | 0 | 1-2 | > 2 |
| External API change | No | Deprecation | Breaking |
| Shared state | None | Read-only | Mutable |
## When to Use Something Else
| Need | Use Instead |
| ----------------------- | ------------------------------------------------------------ |
| Quick change impact | [Change Planning](/skills/change-planning) |
| Explore unfamiliar code | [Exploring Codebases](/skills/exploring-codebases) |
| Debug failing code | [Debugging](/skills/debugging) |
| Generate documentation | [Generating Documentation](/skills/generating-documentation) |
# 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
# Change Analysis (/workflows/change-analysis)
Analyze code before and after making changes to refactor safely.
B[Find Dependencies]
end
subgraph After
C[Check Changes] --> D[Verify Impact]
end
Before --> Make[Make Changes]
Make --> After`}
/>
## Before Making Changes
> "What functions call authenticateUser?"
> "What does authenticateUser depend on?"
> "Show me all the symbols in src/auth.ts"
> "What external code depends on src/auth.ts?"
**Uses:** [Context Search](/mcp/tools/context-search) and [Cypher Query](/mcp/tools/cypher-query) tools
## After Making Changes
> "What's the impact of my unstaged changes?"
> "Show me what processes are affected by my staged changes"
> "Compare my branch against main and show the blast radius"
**Uses:** [Impact Detection](/mcp/tools/impact-detection) tool
**Command:** `/noodlbox:detect_impact [scope]`
Look for `potentially_affected` symbols - code that calls or is called by your changes.
### Depth Control
Use the `depth` parameter to control result detail:
| Depth | When to Use |
| ------------------------- | ------------------------------------------------------------------------ |
| `"definitions"` (default) | Quick impact check - symbol signatures and bodies |
| `"full"` | Deep analysis - includes all relationship data (callers, callees, edges) |
> "Check impact with full relationship data: use depth full"
## Common Questions
| Question | Tool/Resource |
| --------------------------- | ------------------------------------------------ |
| "What calls this function?" | [Cypher Query](/mcp/tools/cypher-query) |
| "What does this depend on?" | [Cypher Query](/mcp/tools/cypher-query) |
| "Find code in this file" | [Context Search](/mcp/tools/context-search) |
| "Impact of my changes?" | [Impact Detection](/mcp/tools/impact-detection) |
| "Cross-community flows?" | [Codebase Map](/mcp/resources/codebase-map) |
| "Trace this process" | [Process Trace](/mcp/resources/process-resource) |
# Code Exploration (/workflows/code-exploration)
Get oriented in a new codebase using communities, processes, and search.
B[Find Community]
B --> C[Trace Process]
C --> D[Query Details]`}
/>
## Quick Start
> "Show me the codebase map"
> "Which communities handle authentication?"
> "Trace the login process"
> "What functions call authenticateUser?"
## Step-by-Step
### Get the Map
> "Show me the codebase map"
**Uses:** [Codebase Map](/mcp/resources/codebase-map) resource
Look for: communities, cohesion scores, cross-flows
### Explore a Community
> "Show me details about the Authentication community"
**Uses:** [Community Detail](/mcp/resources/community-resource) resource
Focus on: entry points, key symbols, processes
### Trace a Process
> "Trace the login process"
**Uses:** [Process Trace](/mcp/resources/process-resource) resource
See the exact function call sequence
### Search for Code
> "Find code related to payment processing"
**Uses:** [Context Search](/mcp/tools/context-search) tool
Returns processes ranked by relevance
### Deep Exploration with Depth
> "Search for authentication with full relationship data"
Use `depth: "full"` to see how code connects:
| Depth | What You Get |
| --------------- | ---------------------------------------------------- |
| `"definitions"` | Symbol signatures and bodies (default, fast) |
| `"full"` | Symbols plus relationships (callers, callees, edges) |
## Common Questions
| Question | Tool/Resource |
| ------------------------------- | ----------------------------------------------------- |
| "Show me the codebase map" | [Codebase Map](/mcp/resources/codebase-map) |
| "What communities exist?" | [Codebase Map](/mcp/resources/codebase-map) |
| "Show me the Auth community" | [Community Detail](/mcp/resources/community-resource) |
| "Trace the login process" | [Process Trace](/mcp/resources/process-resource) |
| "Find code related to payments" | [Context Search](/mcp/tools/context-search) |
| "What functions call X?" | [Cypher Query](/mcp/tools/cypher-query) |
# Debugging (/workflows/graph-queries)
Use the knowledge graph to trace bugs, find root causes, and understand error propagation.
B[Error Message]
A --> C[Unexpected Behavior]
A --> D[Data Issue]
B --> E[Search → Trace Callers]
C --> F[Find Function → Trace Dependencies]
D --> G[Find Handlers → Trace Chain]
E --> H[Root Cause]
F --> H
G --> H`}
/>
## Debugging Workflows
### Error Message
> "Find code related to UserNotFoundError"
> "What functions throw or catch UserNotFoundError?"
> "Trace callers of the function that throws this error"
**Uses:** [Context Search](/mcp/tools/context-search) to find error code, [Cypher Query](/mcp/tools/cypher-query) to trace callers
### Unexpected Behavior
> "Where is calculateTotal defined?"
> "What does calculateTotal call?"
> "What functions call calculateTotal?"
**Uses:** [Cypher Query](/mcp/tools/cypher-query) for relationship traversal
### Data Flow Issues
> "Trace the data flow from handleRequest to the database"
> "Find all functions that handle userId"
**Uses:** [Context Search](/mcp/tools/context-search) and [Cypher Query](/mcp/tools/cypher-query) for path tracing
## Using Processes
> "Show me the codebase map"
> "Trace the checkout process"
> "What processes involve the payment module?"
**Uses:** [Codebase Map](/mcp/resources/codebase-map) and [Process Trace](/mcp/resources/process-resource) resources
Bugs often occur at community boundaries - look at cross-community flows.
## Depth for Debugging
Use the `depth` parameter on search tools to control detail level:
| Depth | When to Use |
| ------------------------- | -------------------------------------------------------- |
| `"definitions"` (default) | Quick lookup - find where something is defined |
| `"full"` | Deep debugging - see callers, callees, and relationships |
> "Search for authentication handlers with full relationship data"
Using `depth: "full"` reveals how code connects - critical for tracing bug propagation.
## Common Questions
| Question | Tool/Resource |
| ------------------------- | ------------------------------------------------ |
| "Find error-related code" | [Context Search](/mcp/tools/context-search) |
| "What calls this?" | [Cypher Query](/mcp/tools/cypher-query) |
| "What does this call?" | [Cypher Query](/mcp/tools/cypher-query) |
| "Trace this process" | [Process Trace](/mcp/resources/process-resource) |
| "Cross-community flows" | [Codebase Map](/mcp/resources/codebase-map) |
| "Impact of changes" | [Impact Detection](/mcp/tools/impact-detection) |
# Workflows (/workflows)
Step-by-step guides for common development tasks.
B[Analyze]
B --> C[Change]
C --> D[Verify]
D --> A
style A fill:#e1f5fe
style B fill:#fff3e0
style C fill:#e8f5e9
style D fill:#fce4ec`}
/>
Discover and understand unfamiliar codebases
Understand dependencies and verify impact
Track down bugs using the knowledge graph
## How to Use These Guides
Each workflow guide includes:
1. **Scenario**: The problem you're solving
2. **Tools & Resources**: What you'll use
3. **Step-by-Step**: Detailed instructions
4. **Example Queries**: Copy-paste ready examples
5. **Tips**: Best practices
## Related
* [Platform](/platform) - Understand communities, processes, and the knowledge graph
* [MCP Server](/mcp) - Tools and resources for querying and analysis
# 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
# 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 |
| `q` | string | Yes | Natural language query |
| `task_context` | string | Yes | What you're working on |
| `current_goal` | string | Yes | Your immediate objective |
| `search_intention` | string | Yes | Why you're searching |
| `include_content` | boolean | No | Include full symbol content (default: false) |
| `limit` | number | No | Max processes (1-100, default: 10) |
| `max_symbols` | number | No | Max symbols per process (1-100, default: 20) |
| `depth` | string | No | Result detail level: `"definitions"` (default) or `"full"` |
### Depth Parameter
Controls how much detail is returned for matched symbols:
| Value | Description |
| ------------------------- | ------------------------------------------------------ |
| `"definitions"` (default) | Symbol signatures and full body content only |
| `"full"` | Symbols plus all relationships (calls, imports, edges) |
Use `"full"` when you need to understand how code connects across the codebase.
## 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
Results are grouped by process:
```json
{
"processes": [
{
"process_label": "UserAuthentication",
"relevance_score": 0.95,
"symbols": [
{
"symbol_name": "authenticateUser",
"file_path": "src/auth/authenticate.ts",
"line_number": 45
}
]
}
]
}
```
## 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: true`** only when you need full function bodies
## Related
* [Cypher Query](/mcp/tools/cypher-query) - Precise graph queries
* [Code Exploration](/workflows/code-exploration) - Discovery workflows
# 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 |
| `cypher` | string | Yes | Cypher query (read-only) |
| `max_results` | number | No | Max results (default: 10000) |
## Common Queries
### Find functions by name
```cypher
MATCH (s:CODE_SYMBOL)
WHERE s.symbol_type = "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 high-cohesion communities
```cypher
MATCH (c:Community)
WHERE c.cohesion > 0.8
RETURN c.label, c.cohesion, c.symbol_count
ORDER BY c.cohesion DESC
```
## Tips
* Always use `LIMIT` to avoid large result sets
* Filter early with `WHERE` for better performance
* Specify node labels (`CODE_SYMBOL`, `File`, `Community`, `Process`)
### Depth in Cypher Queries
Unlike higher-level tools with a `depth` parameter, Cypher queries give you full control over what data you retrieve:
| 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` |
Write operations (CREATE, DELETE, SET) are blocked.
## Related
* [Database Schema](/mcp/resources/database-schema) - Node types and properties
* [Graph Debugging](/workflows/graph-queries) - Debugging workflows
# Impact Detection (/mcp/tools/impact-detection)
Analyze your uncommitted changes to see which processes and symbols are affected before committing.
## Parameters
| Parameter | Type | Required | Description |
| ----------------- | ------- | -------- | ---------------------------------------------------------- |
| `repository` | string | Yes | Repository name |
| `change_scope` | string | No | What to analyze (default: "unstaged") |
| `base_ref` | string | No | Base reference for comparison (default: "HEAD") |
| `include_content` | boolean | No | Include symbol signatures (default: false) |
| `depth` | string | No | Result detail level: `"definitions"` (default) or `"full"` |
### Depth Parameter
| Value | Description |
| ------------------------- | ----------------------------------------------------------------------------- |
| `"definitions"` (default) | Returns affected symbol signatures and bodies only |
| `"full"` | Returns affected symbols plus all relationship data (callers, callees, edges) |
## Change Scopes
B[Before staging]
C[staged] --> D[Before committing]
E[all] --> F[Everything uncommitted]
G[compare] --> H[Against branch/commit]`}
/>
| Scope | Use Case |
| ---------- | -------------------------------------------- |
| `unstaged` | See impact before staging |
| `staged` | Review before committing |
| `all` | Full picture of uncommitted work |
| `compare` | Compare against branch (use with `base_ref`) |
## 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
{
"changed_files": [
{
"file_path": "src/auth/login.ts",
"change_type": "modified",
"affected_symbols": ["authenticateUser", "validateCredentials"]
}
],
"affected_processes": [
{
"process_label": "UserAuthentication",
"process_type": "cross_community",
"affected_symbols": [
{
"symbol_name": "authenticateUser",
"change_type": "modified"
},
{
"symbol_name": "checkPermissions",
"change_type": "potentially_affected"
}
]
}
]
}
```
## What to Look For
* **`modified`**: Symbols you directly changed
* **`potentially_affected`**: Symbols that call or are called by modified code
* **`cross_community`**: Changes spanning multiple areas have wider impact
## Common Workflows
**Before committing:**
```
/noodlbox:detect_impact staged
```
**Before creating PR:**
```
/noodlbox:detect_impact compare --base_ref main
```
## Related
* [Change Analysis](/workflows/change-analysis) - Full refactoring workflow
* [Process Trace](/mcp/resources/process-resource) - Understand affected flows