Skip to main content

n3Plugins Repository Tooling

Use the narrowest effective tool for the question.

Tooling reduces uncertainty.

1. Preferred Discovery Stack​

When available:

Structural discovery → CodeGraph
Literal lookup       → grep_search / rg
Graph/Dependencies   → codebase-memory-mcp (search_graph, trace_path)
Semantic editing     → serena (IDE-level symbol lookup, refactoring, navigation)
Ground truth         → direct source inspection

These are complementary.

2. CodeGraph​

Use CodeGraph for questions such as:

  • What subsystem owns this behavior?
  • What depends on this class?
  • What are the architectural relationships?
  • What are the likely callers/callees?
  • What package or subsystem boundaries are involved?

For substantive repository work, initialize or synchronize the workspace once when CodeGraph is available.

Do not rebuild the graph unless source changes require it.

Do not commit generated CodeGraph indexes unless the repository adopts them as versioned assets.

Recommended ignore entry:

.codegraph/

3. codebase-memory-mcp​

Use codebase-memory-mcp for knowledge graph queries and deep dependency tracing:

  1. search_graph - find functions, classes, routes, variables by pattern
  2. trace_path - trace who calls a function or what it calls (inbound/outbound)
  3. get_code_snippet - read specific function/class source code
  4. query_graph - run Cypher queries for complex patterns
  5. get_architecture - high-level project summary

When to fall back to grep/glob:

  • Searching for string literals, error messages, config values
  • Searching non-code files (configs, scripts)
  • When MCP graph tools return insufficient results

4. Serena​

Use Serena via MCP for IDE-level code exploration and symbolic editing:

  • Retrieval: Use Serena to find symbols, get file outlines, find references, and view type hierarchies.
  • Refactoring & Editing: Use Serena to rename symbols across files, move files/symbols, inline variables, replace symbol bodies, and safely delete code.

Serena tools are highly token-efficient and less error-prone than standard text replacement because they operate on the syntax tree rather than literal string matching. Use Serena's semantic editing over standard replace_content when possible.

5. grep_search / rg / Literal Search​

Use targeted literal search (grep_search tool or rg) for:

  • class names,
  • methods,
  • annotations,
  • IDs,
  • log text,
  • config groups,
  • plugin names,
  • event names,
  • known constants.

Prefer narrow patterns.

Bad:

search everything for "plugin"

Better:

grep_search "checking for bronze axe" src/
grep_search "InteractionResult" src/main/java/com/n3plugins

Do not perform giant undirected searches when a precise identifier exists.

6. MCP Tools​

MCP services are capability-specific.

Do not assume:

configured locally == available in cloud

A local MCP server using:

127.0.0.1

refers to the current machine only.

For cloud workspaces, expose and authenticate remote MCP access.

Do not attempt local endpoints from cloud after that boundary is established.

7. LLM Context Files​

The repository generates three complementary context files:

llms.txt           navigation index; use it to locate the owning source
llms-optimized.txt compact cross-repository rules and API digest
llms-full.txt      complete concatenated corpus; read only targeted sections

Live source and N3PLUGINS_SOURCE_OF_TRUTH.md still outrank generated context. Do not edit generated LLM files. The generator reads the Source of Truth, AGENTS.md, docs/**/*.md, .agents/skills/**/SKILL.md, and its declared root reports.

After changing any generator input, run:

python scripts/generate_llm_docs.py
python scripts/generate_llm_docs.py --check

--check performs no writes and exits nonzero when any generated file is missing or stale.

8. Cloud MCP and Serena​

Cloud workspaces start MCP servers from .codex/config.toml; setup installs their pinned binaries but does not leave server processes running.

Use the configured tools as follows:

codebase-memory-mcp  primary graph discovery and call tracing
CodeGraph            structural CLI fallback and blast-radius exploration
Serena               Java/TypeScript symbols, references, diagnostics, refactoring
rg                   literals, configuration, logs, scripts, and documentation

Setup generates Serena's ignored .serena/project.yml for Java plus TypeScript. Its cloud context suppresses basic shell and file tools that overlap with the host. Keep Serena optional: an LSP startup failure must not block a task, and agents should use graph tools or direct source inspection as fallback.

Serena project configuration, indexes, caches, logs, and memories are generated environment state. Keep the entire .serena/ directory out of commits.

The n3 Agent Server is a different MCP boundary. Local MCP clients should prefer its direct Streamable HTTP /mcp endpoint; the Node stdio bridge remains for compatibility. Neither localhost endpoint reaches a Windows RuneLite client from cloud workspaces.

9. Git​

Before editing:

git status
git diff

or equivalent tooling.

Determine:

  • what is already modified,
  • whether user work exists,
  • which files belong to the current task.

After editing:

inspect final diff

Be able to explain every changed line.

Never:

  • revert unrelated user changes,
  • reset the repository for cleanliness,
  • overwrite dirty files without inspecting them,
  • force checkout unrelated paths.

10. GitHub​

Use GitHub for repository/PR/issue state when the task requires it.

Do not substitute GitHub search for inspecting a local checkout when the live working tree is the relevant source.

For current upstream facts:

  • verify the current branch/tag/version,
  • verify commit dates,
  • verify actual Maven/package metadata where relevant.

Do not rely on stale remembered commit IDs.

11. External Research​

Prefer primary sources for technical questions:

RuneLite source
official repositories
official Javadocs/documentation
official Maven metadata
official dependency documentation

External examples are evidence, not authority over local architecture.

Never invent an API because a similar project has one.