Semantic codebase indexing and search

[dineshkumarkummara]

What feature would you like to see?

Proposal: Add Semantic Index and Search to Codex CLI

Summary

Codex CLI is strong at local agentic coding, but it struggles to reliably find the right places in medium to large codebases because it lacks a first-class semantic search capability. Users currently fall back to grep or filename heuristics, which break down in polyglot repositories, renamed identifiers, or when concepts are expressed differently than the query.

Adding an official semantic index and search flow will materially improve Codex’s accuracy and speed on large projects and aligns with OpenAI’s direction to make Codex handle larger contexts and complex, multi-step software tasks.

Problem Statement and User Evidence

Community requests:
An earlier issue specifically asked for semantic code search via an index and was closed without the feature landing in core, indicating unmet demand and opportunity to contribute.

Current limitations:
Without semantic retrieval, Codex relies on keyword search and path heuristics, which miss relevant code when names differ or when logic spans multiple files and languages. This leads to wrong or incomplete edits and extra back-and-forth. Community discussions repeatedly call for deeper “code intelligence.”

Strategic fit:
Codex has recently expanded in IDEs, terminals, and GitHub with a push toward larger tasks and persistent state. A built-in index that the agent can query is complementary to that direction.

Goals and Non-Goals

Goals

1. Make Codex reliably find relevant code across large and polyglot repos through vector retrieval that understands meaning, not just tokens.
2. Keep the developer workflow simple — one command to build an index, one to search it, with minimal configuration.
3. Enable both human-initiated searches and future agent-initiated tool use.

Non-goals

• Replace static analysis, LSP features, or heavyweight language servers.
• This is retrieval to locate relevant snippets fast and feed them to Codex, not a full IDE indexer.

Proposed Solution

CLI Subcommands

codex index
Builds a local semantic index of the project using OpenAI embeddings and stores vectors plus metadata on disk.

codex search "<natural language query>"
Returns the most similar code snippets with file path and line ranges. Output is optimized for copy-pasting into a prompt or for agent consumption.

This approach maintains compatibility with existing workflows while delivering a major improvement for large repositories.

Why This Benefits Users

Developers using Codex across IDEs and terminals will gain faster, more accurate navigation and edits on real-world projects. As Codex takes on multi-file changes and long-running feature work, retrieval becomes critical.

Detailed Design

User-Facing CLI

codex index

• Scans the current workspace, skipping common build/vendor folders.
• Splits code into logical chunks (~200–400 lines).
• Embeds them and writes an index at .codex_index.
• Prints a progress summary at completion.

codex search "refactor image upload to be async" --top 8

• Embeds the query.
• Runs approximate nearest-neighbor search over the local index.
• Prints top K hits with file path, line ranges, short code excerpts, and similarity scores.

Configuration and Flags

• --src <path> to index a specific directory
• --top <K> for number of search results
• --filter <glob or extension> to narrow search output
• Configurable embedding model (default to current OpenAI model)
• Optional backend selection for future pluggability

Core Components

Chunking
Use pragmatic, language-agnostic splitting by blocks or functions. Store file paths and spans per chunk. Optional tree-sitter parsing can be added later.

Embeddings
Use OpenAI’s embeddings API for vector representations. Store model metadata for compatibility. Allow swapping models via config.

Vector Store
Use a local FAISS index via Rust bindings for speed and zero external dependencies.

• Stored at .codex_index/index.bin
• Metadata sidecar JSON maps vector IDs to file paths and line ranges
  Alternative backends like Qdrant or SQLite-ANN can be added later if requested.

Search
Normalize embeddings for cosine similarity and return top K results.
Output includes readable snippets with file paths and line spans for quick navigation.

Agent Integration Path

Near-term: Human-driven usage.
Mid-term: Expose search as a callable tool so Codex can autonomously pull context during tasks.
This leverages the tool-use push without tightly coupling to a specific interface.

Performance and Cost Considerations

• Indexing cost/time scale with project size; embedding is a one-time operation per chunk.
• Search is instantaneous and local once built.
• This shifts cost from repeated scans to a cacheable, one-time build step.
• Incremental indexing can be added later by hashing files and re-embedding changed chunks only.

Privacy and Security

• Indexing is limited to the current workspace; no traversal outside it.
• Embeddings are created by sending code chunks to the OpenAI embeddings API, documented publicly.
• Users can opt out by not running index.
• Future enhancement could include offline local-model indexing.

Alternatives Considered

• Pure keyword search: Fast but fails with synonymy and refactors.
• IDE LSPs: Strong per-language but not suited for multi-language, terminal-first workflows.
• External vector DBs: Add operational complexity; local FAISS index keeps setup frictionless.

Compatibility and UX

• Backward compatible; new commands are opt-in.
• Plain text output compatible with all terminals.
• Index directory (.codex_index) can be safely deleted or ignored in Git.
• Fits seamlessly into Codex’s multi-environment rollout.

Phased Delivery Plan

Phase 1 – MVP

• Implement codex index and codex search commands.
• Add directory scanning, chunking, embeddings, FAISS index build, metadata write.
• Implement query path with top-K results and filters.
• Add documentation and usage examples.

Phase 2 – Quality and Speed

• Parallelize embedding with backoff for rate limits.
• Add incremental indexing via hashing.
• Introduce language-aware chunking for common stacks.

Phase 3 – Agent Integration

• Expose as a lightweight MCP tool for Codex to call autonomously.
• Optionally provide editor jump links (e.g., VS Code).

Success Metrics

• Improved search precision measured by human acceptance during refactors.
• Fewer “can’t find the right file” errors.
• Community adoption and positive issue/PR feedback.
• High maintainability and test coverage.

Risks and Mitigations

• FAISS bindings maintenance: Pin stable crates; allow a Rust ANN fallback.
• Token cost for large repos: Clear documentation and default chunking limits.
• Roadmap overlap: Communicate early with maintainers to align efforts.

What’s Needed from Maintainers

1. Approval to proceed with implementation behind guarded, opt-in commands.
2. Guidance on dependency policy — FAISS vs pure Rust ANN.
3. Preferences on configuration surface and naming.
4. Direction on whether to expose agent tool use in the initial PR or later.

Contribution Plan

• Create a feature branch and integrate new commands into the existing CLI parser.
• Implement indexer and search modules in Rust with clear interfaces and metadata.
• Add comprehensive tests for chunking, metadata, and an integration test on a sample repo.
• Update README and CLI help.
• Respond quickly to review feedback and sign the CLA as required.

Why Now

Codex is expanding rapidly across IDEs and CLIs, with GPT-5-Codex emphasizing sustained, multi-file work. A semantic index is the missing foundation that lets the agent consistently find the right code and make safer changes at scale. Shipping this now compounds the value of recent updates and improves real developer workflows immediately.

Additional information

No response

[github-actions]

Potential duplicates detected. Please review them and close your issue if it is a duplicate.

• Optional /index mode for semantic code search using OpenAI File Search #3504

Powered by Codex Action

[chall37]

Is this something you're actively working on? If so and/or the maintainers indicate approval, I'd be interested to work on it.

The biggest obstacle I see is that the model already seems to rely too heavily on the semantics of function and variable names, and not enough on analyzing actual code flow. This is particularly troublesome in projects (ahem) where meaning of identifiers is... let's say local to the person who created them. I wonder if it wouldn't actually help to run a light obfuscation before asking the model to generate identifiers on its own, which could then be mapped back to the original identifiers for the index. The model could also highlight large discrepancies, like "this function is called X but it really does Y".

[dineshkumarkummara]

Thanks for raising that, I’m not actively working on it yet, but this is exactly the kind of discussion I was hoping for before starting the implementation.

You make a great point about identifier semantics. I’ve noticed the same issue: Codex (and even embeddings-based search) can over-fit to surface tokens rather than real data or control flow. That’s actually one of the motivations for the indexing approach, it gives us an opportunity to add an optional preprocessing layer before embedding.

Your idea of lightweight obfuscation is really interesting. It could help normalize identifiers so the embeddings capture actual logic and relationships instead of names. Conceptually, that could mean:
• Mapping identifiers to generic placeholders (func_1, var_2, etc.) before computing embeddings
• Keeping a mapping file for reverse-lookup when displaying search results
• Comparing embedding similarity between obfuscated and original versions to flag “semantic drift”, like your example of a function named X that actually does Y

If maintainers are open to it, this could even become a flag (e.g. --normalize-identifiers) during indexing, so users can toggle it depending on their repo’s naming quality.

I’ll hold off on coding until there’s confirmation from maintainers, but I really like this idea, it would make the index much more robust across different naming conventions.

[chall37]

I wonder if the model would get confused by too many similar placeholders all at once. The indexer might walk (a cache of) the project both from the entry point as well as the folder structure, applying generated names as it goes and falling back on the original identifiers for hints when needed (for data structures, interfaces, etc.). There might be something in the Reverse Engineering space that is doing something similar already, since it's essentially the same problem.

Here, it wouldn't be about trying to untangle potentially malicious code per se, but nudging the model toward analyzing the control flow more than the identifiers. Probably not so important as a first step, but it seems like a good long-term goal (IMO). It seems like a semantic index could also cut down massively on agentic workloads.

I've only been watching this repo for a short time, but I don't see a lot of activity from maintainers, especially in Issues, but it does appear that there are already some semantic indexing projects designed as MCP servers...

https://github.com/elastic/semantic-code-search-mcp-server
https://github.com/yichuan-w/LEANN

[dineshkumarkummara]

That’s a really solid observation, I share your concern about placeholder overload. Too many generic identifiers (like hundreds of var_n or func_n) could definitely collapse embedding diversity and confuse the vector space. I like your idea of walking the project graph instead of doing a flat text replacement, building a semantic skeleton rather than a literal rename pass.

A hybrid approach could work well here:
• Selective obfuscation: Replace identifiers only where their naming adds little value (local variables, temporary helpers), while preserving or lightly normalizing domain-heavy names (e.g., CustomerAccount → EntityType1_CustomerAccount instead of Class_23).
• Context-weighted normalization: Use folder hierarchy and imports to group and disambiguate placeholders, so embeddings retain some structural signal even after normalization.
• Dual embedding: We could even maintain two indices here, one for original source, one for normalized and compare them to highlight where identifier semantics diverge from actual behavior (your “X does Y” scenario). That could be incredibly insightful for large, aging codebases.

And agreed the reverse-engineering analogy is spot on. Tools like IDA Pro or Ghidra essentially reconstruct call graphs and reassign symbolic names to drive deeper analysis. The same principles apply here, just in a benign, developer-oriented context.

As for existing MCP servers like the ones you linked (Elastic’s and LEANN), I think those strengthen the case rather than replace it, they show that semantic indexing is valuable, but those projects live as external MCP integrations. What I’m proposing here is to bring that capability natively into Codex CLI, so that both local users and the Codex agent itself can leverage it out of the box without separate setup.

Long-term, that could indeed cut down on agentic workloads massively. Instead of repeatedly scanning or prompting over raw files, the agent could query the precomputed semantic index and operate on compressed representations, effectively turning Codex into a self-optimizing retrieval layer for code.

Definitely appreciate your insight, I’d be interested in collaborating if this moves forward or if maintainers give the green light.

[CaliLuke]

Apologies if this is obvious — just hoping to contribute something useful.

I think the concern about Codex over-indexing function names is valid — but it might be a case of premature optimization.

A good next step could be to prototype a minimal eval setup to observe the behavior of a toy code-indexing system. You could even run this directly on the Codex CLI codebase or another well-known open-source project. That would make the evals easy to generate and the results self-evident.

In general, when you notice misbehavior, the fastest way to improve the model is to capture it in a small, reproducible eval and then iterate until those cases disappear.

[dineshkumarkummara]

That’s a great point,I completely agree that before adding abstraction or normalization layers, it makes sense to observe the current model’s behavior in a controlled setup.

A minimal eval on a known repo (like Codex CLI itself or a smaller open-source project) would definitely clarify how much the model currently relies on naming semantics versus actual code flow. It would also help quantify the practical gain of adding a semantic index at all.

I was planning to start with a prototype indexer that only chunks and embeds files, then run a few evaluation passes:
1. Baseline: direct keyword search or name-based retrieval
2. Semantic-only: query using embeddings without any identifier normalization
3. Hybrid: embedding after simple normalization (e.g., variable → generic token)

That should produce some measurable signal about whether semantic indexing actually improves retrieval quality or reduces context misses.

If you or others are already running lightweight evals internally, I’d be happy to align with whatever metrics or harness you use, the goal would be to get a reproducible dataset of “retrieval errors” we can iterate on.

Thanks for surfacing this, I think you’re right that it’s the pragmatic next step to turn the idea into something testable.

[allenanswerzq]

Hi everyone — I’m currently working on this project and running some experiments related to the topics being discussed here.

The repo is available at: https://github.com/allenanswerzq/llmcc

My goal is to set up a lightweight indexing system, integrate it with Codex, and observe how it behaves — essentially what @CaliLuke mentioned earlier.

It can already parse the Codex repo — you can try it out if interested with:

cargo run --release -- --dir ./codex

If anyone is exploring similar ideas, feel free to take a look or collaborate. Contributions and feedback are very welcome!

[allenanswerzq]

On the other hand, been trying the new Claude Haiku 4.5 model in github copilot, feels its already very very good in terms of speed and context understanding... maybe an indexing isn't need after all in the future, with model grow stronger and stronger, who would know ;-).

[OriNachum]

@allenanswerzq I am also working on it and I have a full coded solution that I never got the chance to test :D

I'm looking forward to see yours succeed!

I think there are many approaches to "correct indexing" as it is not trivial, so any approach is welcome.
My repo:
https://github.com/teabranch/agentic-code-indexer

[allenanswerzq]

@OriNachum thanks for the nice comments, I feel right now the direction is more "agentic" (like using tools rg, grep etcc) of doing everything, so a very simple indexing tool might be useful in this scenarios.