mirror of
https://github.com/openmc-dev/openmc.git
synced 2026-07-21 06:25:30 -04:00
b215f13218
Co-authored-by: John Tramm <jtramm@gmail.com> Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
104 lines
4.7 KiB
ReStructuredText
104 lines
4.7 KiB
ReStructuredText
.. _devguide_agentic_tools:
|
|
|
|
===========================
|
|
Agentic Development Tools
|
|
===========================
|
|
|
|
OpenMC ships a set of tools designed for AI coding agents (such as
|
|
`Claude Code`_) that agents can use to navigate and understand the codebase.
|
|
|
|
.. _Claude Code: https://claude.ai/code
|
|
|
|
Motivation
|
|
----------
|
|
|
|
Agentic tools like Claude Code are skilled at using grep to navigate and
|
|
understand large code bases. However, grep can only find exact text matches —
|
|
it cannot discover code that is *conceptually* related but uses different
|
|
naming. Without a "global view" of the codebase that a human developer will
|
|
build up over time, the agent is generally blind to any file it hasn't
|
|
tokenized fully. While it can grep to see who else calls a function, it
|
|
remains blind if other areas might be related but not share identical naming
|
|
conventions.
|
|
|
|
This problem is mitigated somewhat by using a model with a longer context
|
|
window. OpenMC has somewhere around ~1 million tokens of C++ and ~1 million
|
|
tokens of python. While Claude Code in early 2026 only has a context window
|
|
of 200k tokens, beta versions have extended context windows of 1M tokens,
|
|
and it's not unreasonable to assume that models may be available in the near
|
|
future that greatly exceed these limits.
|
|
|
|
However, even assuming the entire repository can be fit within a context
|
|
window, there are several downsides to doing this.
|
|
`Model performance degrades significantly as context size increases`_.
|
|
Benchmark results are
|
|
greatly improved if the model has less garbage to pick through. Additionally, API usage
|
|
is typically billed as tokens in/out per turn. As the context file
|
|
grows these costs become much larger. As such, there is still significant
|
|
motivation to solving the above problem, so as to ensure only relevant
|
|
information is drawn into context so as to maximize model performance and
|
|
minimize costs.
|
|
|
|
Setup
|
|
-----
|
|
|
|
The tools are registered as an `MCP (Model Context Protocol)`_ server in
|
|
``.mcp.json`` at the repository root. AI agents that support MCP (such as
|
|
Claude Code) discover them automatically on session start. The underlying
|
|
Python scripts can also be run directly from the command line.
|
|
|
|
All tools run entirely locally — no API keys or external service accounts are
|
|
required. Python dependencies are installed automatically into an isolated
|
|
virtual environment at ``.claude/cache/.venv/`` on first use.
|
|
|
|
.. _Model performance degrades significantly as context size increases: https://www.anthropic.com/news/claude-opus-4-6
|
|
.. _MCP (Model Context Protocol): https://modelcontextprotocol.io
|
|
|
|
RAG Semantic Search
|
|
-------------------
|
|
|
|
The RAG (Retrieval-Augmented Generation) semantic search addresses this
|
|
problem — it finds code by meaning, not just text match, surfacing related code
|
|
across subsystems that ``grep`` would miss entirely. Two MCP tools are provided:
|
|
|
|
- **openmc_rag_search** — Given a natural-language query, returns the most
|
|
relevant code chunks with file paths, line numbers, and a preview. Can search
|
|
code, documentation, or both. Can also find code related to a given file.
|
|
- **openmc_rag_rebuild** — Rebuilds the search index. Should be called after
|
|
pulling new code or switching branches.
|
|
|
|
How it works
|
|
^^^^^^^^^^^^
|
|
|
|
The search pipeline runs entirely on your local CPU:
|
|
|
|
1. **Chunking.** All C++, Python, and RST files are split into overlapping
|
|
fixed-size windows (~1000 characters, 25% overlap). This ensures every line
|
|
of code appears in at least one chunk and most lines appear in two.
|
|
|
|
2. **Embedding.** Each chunk is embedded into a 384-dimensional vector using
|
|
the `all-MiniLM-L6-v2`_ sentence-transformer model (22 million parameters).
|
|
This model runs on CPU with no GPU required. No API key is needed — the
|
|
model weights are downloaded once from Hugging Face and cached locally.
|
|
|
|
3. **Indexing.** The vectors are stored in a local LanceDB_ database on disk.
|
|
Building the full index takes approximately 5 minutes on a machine with
|
|
10 CPU cores. The index is stored in ``.claude/cache/rag_index/`` and
|
|
persists across sessions.
|
|
|
|
4. **Searching.** Your query is embedded using the same model, and the closest
|
|
chunks are retrieved by vector similarity. Results include the file path,
|
|
line range, file type, similarity distance, and a text preview.
|
|
|
|
.. _all-MiniLM-L6-v2: https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2
|
|
.. _LanceDB: https://lancedb.com
|
|
|
|
Requirements
|
|
^^^^^^^^^^^^
|
|
|
|
No system dependencies beyond **Python 3.12+** with ``pip``. An internet
|
|
connection is required on first use to download the Python packages and
|
|
embedding model weights; subsequent runs are fully offline. The Python packages
|
|
(``sentence-transformers``, ``lancedb``) and their dependencies (including
|
|
PyTorch, ~2GB) are installed automatically into an isolated virtual environment
|
|
on first use.
|