A free tool that helps you find your way around any codebase, answers your questions with proof, and keeps your code on your own computer.
The problem every developer knows
You open a project you have never seen before. Maybe you just joined the team, maybe you are picking up someone else's work, or maybe it is your own code from two years ago. You have a simple question:
Where do we stop people from logging in too many times?
The answer is in there somewhere. But the search box in your editor only finds the exact words you type, and the code never says "logging in too many times". The person who wrote it is busy, on holiday, or long gone.
So you click through folders, open file after file, and lose an afternoon.
yodaman-ctx (ctx for short) is built to save you that afternoon.
What ctx does, in one sentence
You point ctx at a project once, and from then on you can search it by what the code does, not just what it is called, and ask questions that come back with answers and the exact files and lines they came from.
It is free, open source (MIT licence), and runs entirely on your own machine.
The gaps it fills
1. Finding code when you don't know what it's called
Ordinary search needs the exact word. ctx searches two ways at once:
-
By name. Type an exact function name or error code and ctx finds it, just like a normal search would. It even understands how programmers write names, so
getUserByIdis found whether you type the name itself or "get user by id". - By meaning. Describe what you are looking for in plain words, and ctx finds code that does that, even when it uses completely different words.
It then combines both, so the code that matches your question in both ways rises to the top. It also pays attention to where code lives: a question about the chat agent's tool finds the file whose folder and file name contain those words.
2. Answers you can check, not just trust
Ask ctx a question in plain English, and it answers using your actual code, with a list of the files and line numbers it relied on. You never have to take its word for it: every answer points you to the source so you can see for yourself.
If you want to see exactly what information the answer was built from, ctx will show you that too.
3. Your code never leaves your computer
Many AI coding tools send your code to a company's servers. ctx does not.
- The part that understands meaning runs on your own computer. It downloads once (about 340 MB) and then works offline.
- Answers come from a local AI model that you run yourself through Ollama, a free tool for running models on your own machine.
- There is no cloud service and no account or API key to set up.
For private, sensitive or client code, that matters.
4. Understands how code is organised
ctx doesn't chop files up at random. It reads the structure of the code, so each result is a complete, meaningful piece: a whole function with its comments, or a whole section of a document with its heading.
It does this for TypeScript, JavaScript, Python, Go, Rust, Java and C#. Other languages are still searchable; they are split into evenly sized pieces instead.
5. Reads your documents, too
Requirements and design notes often matter as much as the code. ctx also searches Markdown, plain text, Word documents and PDFs, so an answer can come from a spec as easily as from the source. (A scanned PDF that is only images needs to be converted to text first.)
6. Many projects, one place
Index as many projects as you like. Search one, or search them all at once. In a conversation, ctx works out which project you are asking about, or you can tell it to stay focused on one.
7. Tells you when it needs a refresh
When ctx improves the way it reads code, older indexes keep working but give weaker results. ctx keeps track of this and tells you, with the exact command to run, when a project's index should be rebuilt. A quick health check (ctx check) shows the same thing.
8. Works with your scripts and AI assistants
Every command except the interactive chat can give its results in a structured format (JSON) that other programs can read. That makes ctx easy to plug into scripts, build pipelines, and AI coding assistants. It is also the search engine behind the YodaMan tool.
9. Proves how well it works
ctx comes with a way to measure its own accuracy, and the results are published rather than guessed. On a test of 56 questions about ctx's own code:
| How often it's in the top 5 results | |
|---|---|
| The right file | 91% |
| The exact passage that answers the question | 70% |
You can run the same kind of test on your own projects with ctx eval.
Everything it can do
| Command | What it does for you |
|---|---|
ctx index |
Reads a project (or a folder of documents) so you can search it |
ctx search |
Finds the most relevant code for a question or a name |
ctx ask |
Answers a question from your code, with sources |
ctx chat |
A back-and-forth conversation about your projects |
ctx list |
Shows the projects you have indexed |
ctx status |
Shows how much is stored and which model is in use |
ctx check |
Checks a project is ready to search, and what to fix if not |
ctx remove |
Deletes a project's index |
ctx config |
Changes settings, such as which local model answers |
ctx eval |
Measures how well search works on your own questions |
Inside ctx chat you can focus on one project, add a short description to help ctx route your questions, index a new project without leaving the chat, and export the whole conversation to a Markdown file to share.
What it doesn't do (yet)
Good tools are honest about their limits:
- It isn't right every time. On its own test, the exact answer is in the top five results about 7 times in 10. Some kinds of question are harder than others.
- Very large projects are slower. A search over a project of 25,000 pieces takes about a third of a second. At around 200,000 pieces it can take a few seconds.
- Answers need a local model. Searching works on its own, but to get written answers you need Ollama installed with a model downloaded.
- Some computers use more memory. On most Windows, Mac and Linux machines ctx searches directly from disk. On a few others, such as Windows on ARM, it still works but loads more into memory.
- Upgrades sometimes need a rebuild. After some updates, each project needs to be re-read once. ctx tells you when and how.
Who it's for
- Developers joining a new team who need to understand a codebase quickly.
- Teams working with private code who can't send it to an outside service.
- Anyone juggling several projects who wants one place to search them all.
- People building AI tools and scripts who need reliable, structured code search to plug in.
Getting started
You'll need Node.js version 24 or later. Then, in three steps:
# 1. Read a project
ctx index ~/code/my-app --name my-app
# 2. Search it by what the code does
ctx search "where are sessions refreshed" -p my-app
# 3. Ask a question and get an answer with sources
ctx ask "How does the login flow work?" -p my-app
The install command and full instructions are on GitHub: github.com/Yoda-Man/ctx. It is published on npm as yodaman-ctx.
The short version
yodaman-ctx lets you ask your code questions in plain language and get answers you can check, without your code ever leaving your computer. It finds code by name or by meaning, reads seven programming languages by their structure along with your documents, handles many projects at once, works with your scripts and AI tools, and publishes how well it actually performs.
Less time searching. More time building.
Top comments (0)