YodaMan is a developer tool that runs entirely on your own machine. It searches your code, maps how your files depend on each other, and keeps track of what your project's specs say. It answers questions with a local model through Ollama. Nothing leaves your computer: no cloud model, no API key, no telemetry.

Under the hood, every search goes through three steps:

  1. Context Expert (ctx) finds the code that matches your question.
  2. Graphify ranks the results using your project's dependency graph.
  3. OpenSpec tags each result with the spec that describes it.

This post covers two releases that shipped together: YodaMan 0.6.7 and Context Expert 1.4.0.

We wrote down what YodaMan does. All of it.

Before this release, YodaMan had no written description of how it is supposed to behave. The code was the only source of truth, and code is a poor place to look up intent.

So we wrote one. YodaMan now has a full OpenSpec specification: 17 areas (search, the agent, approvals, the desktop app, plugins, releases and more) and about 250 requirements. Each requirement says what the tool must do, with concrete examples: the exact route, the exact error message, the exact file.

Writing it meant checking every claim against the code. That is where things got interesting.

Writing the spec found about 50 bugs

When you describe behaviour precisely, you notice where the code does something else. We found about fifty places like that. A few highlights:

  • Ask skipped the search pipeline. The "ask a question" route called Context Expert directly, so answers were not scoped to your workspace and not ranked by your dependency graph. It now goes through all three steps, like every other search.
  • A live update channel did not check who was asking. Any web page open in your browser could listen to it. It now gets the same checks as the rest of the API.
  • Folder paths were trusted too much. Several actions, including git commits and the agent, accepted any folder you named. They now only work on workspaces you have added to YodaMan.
  • Text could turn into command-line flags. A file or branch name starting with - could be read by git as an option. That is closed for git, Context Expert and Graphify.
  • Your disabled plugins came back after every upgrade. The list lived inside the app itself. It now lives in your data folder.
  • The Lightsaber plugin never reported a hotspot. A broken regular expression made every file look simple.
  • Holocron VR could not draw its 3D view. It crashed on the first frame. It now renders, and VR goes through three.js's own WebXR support.

There were also smaller ones: an approval that accepted the text "false" as a yes, a Dashboard button that could not work on most setups, a help command that hung instead of printing help, and docs that described routes and flags that no longer existed. The documentation was checked line by line against the code and corrected throughout.

Tests that stop the same bug coming back

Fixing a bug is half the job. The other half is making sure it cannot quietly return.

Every fix in this release ships with a test that fails on the old code and passes on the new code. We checked each one by putting the bug back and watching the test fail.

Where a bug was one example of a pattern, we added a broader "guard" test that scans the whole codebase for that pattern. For example:

  • Every API error must include an error code.
  • Text from a request must never reach git or another tool as a flag.
  • Any route that takes a folder must check that it is a registered workspace.
  • The VS Code extension and mobile app may only read fields the server actually sends.

There are 16 of these guards now. The next time someone writes one of these bugs, the build fails before it ships.

From now on, every change starts as a spec

The biggest change in this release is in how YodaMan is built. Every feature, fix and chore now starts as an OpenSpec change: a short proposal, a list of tasks, and the spec updates it will make. When it is done, it is checked against the spec and archived, so the spec always matches the code.

The OpenSpec workflows ship inside the repository, so anyone contributing with Claude Code gets them automatically. The same setup now covers all five YodaMan projects: the core app, Context Expert, Holocron VR, Lightsaber and the Homebrew tap.

Context Expert 1.4.0: better search in more languages

Context Expert is the search engine behind YodaMan. It splits your code into chunks, turns them into vectors on your machine, and finds the best matches for a question. Version 1.4.0 makes those chunks smarter.

  • 15 languages are split at their definitions. C, C++, PHP, Ruby, PowerShell, Dart, Kotlin and Swift join the list. Each method becomes its own chunk, labelled with its class, so search results point at the function you meant, not half a file.
  • New file types are indexed: Dart, VB.NET, PowerShell, plus Makefiles, Gemfiles, Podfiles and friends, which were silently skipped before.
  • Nothing gets dropped. Some lines (like a lone else { at the end of a file) fell outside every chunk and were never indexed. Every non-blank line now lands in exactly one chunk. A file the parser cannot read is still indexed, split by size, with a warning.
  • No compiler needed. Languages without a prebuilt parser ship as WebAssembly, so installing never builds anything.
  • Lots of small fixes: .tsx files use the right grammar, minified bundles are skipped, search.top_k from your config is respected, tags you set are kept on re-index, and a failed first index leaves nothing behind.

Because chunks are split differently, re-index your projects after upgrading:

ctx index <path> --force 

Upgrading

YodaMan needs Node 24 or later.

# Homebrew brew upgrade yodaman # or npm npm install -g yodaman@0.6.7 

Then let YodaMan bring Context Expert and the other tools up to date:

yodaman setup 

Desktop downloads for macOS and Linux, the VS Code extension and the Holocron VR plugin are on the website. The VS Code extension updates from the Marketplace.

Thanks for reading

YodaMan is open source under the MIT licence. If you try it, find a bug, or want to help, the repository is at github.com/Yoda-Man/yodaman. Issues and pull requests are welcome, and now every one of them starts with a spec.