Once a repository is indexed, your assistant can find code by what it does rather than by guessing file names. That is the difference between searching for the word "cache" and asking where you decide what to evict.
What leaves your computer, and what does not
Korium CLI reads your repository on your own machine and works out where every function, type and module is defined. It sends Korium that map. It does not send your code.
For each symbol it finds, exactly seven things travel:
- The name, fully qualified, and what kind of thing it is.
- The file path, relative to the repository, and the first and last line of the symbol.
- How it was found, and two fingerprints plus a line count, so a later index can tell what moved.
No source text of any kind is included. You can see this for yourself before you send anything, with --cards-out in step 4.
Nothing is indexed in the background and nothing is watched. Each index is a command you run, in a folder you chose.
Install Korium CLI
The download is on your dashboard, on the right, with the current version and size. There is no public download link, because the app is for teams using the code index.
You get Korium.pkg. Open it, review and accept the End User License Agreement, then follow the Mac installer. It asks for an administrator password because it installs the command for everyone who uses the Mac.
When the installer finishes, open a terminal and check the command is there:
korium-cli helpThe installer puts the command at /usr/local/bin/korium-cli. There is nothing to move, no link to make, and no PATH setting to add.
The command and its installer are signed and notarized by Apple. The password prompt grants permission to install in a system folder; it is not a warning that the software is untrusted.
Sign in
Run this once on each Mac you index from:
korium-cli loginIt opens your browser and asks you to sign in to Korium, the same sign-in you use for the dashboard. When you are done, the terminal says you are signed in.
Your sign-in is kept in your Mac's keychain, so you will not be asked again on that machine.
Korium CLI never wants a token pasted on a command line, and you should never give it one. If something suggests otherwise, stop and talk to Kyroco.
Check it works
korium-cli statusYou want all three lines to be good news:
Server api.kyroco.ai, reachable
Sign-in signed in, and tied to this Mac
Connection your sign-in worksThe first line says your machine can reach Korium. The second says this Mac holds a sign-in. The third says that sign-in is still good. If any line disagrees, fix that one before going on.
Rehearse before you send anything
From inside the repository you want to index, run:
korium-cli index --dry-runThis reads the repository and tells you what it found. It sends nothing, and it works even before you have signed in.
You will see something like this:
Read 261 files at commit deb1b8536b77 in 1s.
Found 4444 symbols in 260 files.It also names any file it read and found nothing in, so a file missing from your searches later is never a mystery.
To see exactly what would be sent, write it to a file and read it:
korium-cli index --dry-run --cards-out /tmp/cards.jsonAdd --include <folder> to work on part of the repository first. You can repeat it for several folders.
Index your repository
Same command, without the rehearsal flag:
korium-cli indexReading and sending are quick. Making the symbols searchable takes longer, and the command waits and reports progress while it happens:
Sent 4444 symbols across 260 files at commit deb1b8536b77 in 4s.
Waiting for Korium to make them searchable...
1,076 of 3,462 symbols embedded, 1m 30s so far
Done in 5m 19s more. Searches now find this commit.A few hundred symbols are ready in seconds. A few thousand take minutes. The number it reports is often smaller than the number it sent, because symbols Korium already knows are not processed twice.
Those progress lines only appear as they happen when you can see the terminal. If you send the output to a file or pipe it into something else, nothing appears until the command finishes. It is working; you just cannot see it yet.
Search it
Ask a question the way you would ask a colleague:
korium-cli search "where we decide what to evict from the cache"You get back the commit being answered from, then the places that match, each with its file and line range:
Answering from commit deb1b8536b77
lib/cache/policy.ex:88-134 MyApp.Cache.Policy.evict (function)Your assistant can ask the same question through Korium directly, which is the point of indexing in the first place. Ask it to read the Korium code-index guide and it will take you through that side.
Keeping the index current
An index answers for one commit. Run korium-cli index again after you have made changes, and only the files that changed are sent.
Three things are worth knowing before you rely on that.
- The shortcut is per machine, not per repository. Korium tracks what this Mac has sent. A teammate indexing the same repository for the first time sends all of it, even though Korium already has it.
- Re-indexing the same commit needs
--replace. The first index of a commit is the one that keeps answering, so a second run on the same commit changes nothing unless you say so. This is the one that surprises people: the command succeeds and your searches do not change. - Deleting symbols needs
--allow-removals. Use it when files you changed have no symbols left in them, or when the repository genuinely got much smaller.
Use --full when you want to send everything regardless, and --branch <name> to record which branch this commit is the head of.
Tell your assistant to use it
An assistant with no index finds code by reading files and matching text. On a large repository that is slow, and it misses anything you cannot already name.
Indexing does not change that on its own. Your assistant will keep grepping until you tell it not to.
Paste this into your project instructions. That is CLAUDE.md for Claude Code and AGENTS.md for Codex, and both read it automatically at the start of a session.
When you need to find where something lives in this repository, ask the
Korium code search tool before reading the tree. Its name ends in
code_locate. Pass the commit that is actually checked out, from
git rev-parse HEAD, rather than one you remember.
Read the staleness field in the answer before you trust a line number.
Anything other than "fresh" means the symbol may have moved, so open the
file and look.
If the answer is empty, read staleness.reason before doing anything. It
tells you whether the repository is unknown or the commit is unindexed,
and those have different fixes. Only fall back to searching the tree by
hand once you know the index genuinely has nothing.This is a rule about where to look first, not a ban on reading files. Your assistant still opens the file it is pointed at, because the index holds locations and never code.
The first part of the name comes from whatever you called the connection when you added Korium, so no spelling is right on everybody's machine. Describe the tool the way the rule above does, by the end of its name. A rule naming a tool your assistant does not have will make it fail, or quietly skip the step and tell you it worked.
Make the rule stick
Written instructions explain what to do. Hooks make it happen. You want both, for the same reason we learned on the memory side: a rule with nothing enforcing it stops being followed a few hours into a long session, and nobody notices.
You do not have to write the hook yourself. Paste this to your assistant:
Set up a hook for this project that nudges you toward the code index.
Before a tool call that searches or reads across the repository, check
whether the Korium code search tool has been called yet this session. If
it has not, block once with a message saying to ask the code index first
and naming the tool by the end of its name, code_locate. Block once only,
then stand aside for the rest of the session.
Never write out a full Korium tool name, in what you match on or in the
text the block prints. The prefix comes from whatever the connection was
named, so it differs per person. Match on a trailing code_locate.
The block must explain itself and say what to call instead. It must never
fire more than once in a session, and it must never block when the index
has already answered.One block, early, is enough. A gate that fires every time gets switched off within a day, and then you have neither the hook nor the habit.
The same page covers the memory half of this, which is a separate set of checks: Make it automatic.
Re-index when you commit
An index answers for one commit. The way to stop thinking about that is to let git run the command for you.
Create .git/hooks/post-commit in your repository with this in it:
#!/bin/sh
# Keep the Korium code index up with this repository.
# Never blocks the commit, and does nothing on a machine without the tool.
command -v korium-cli >/dev/null 2>&1 || exit 0
branch=$(git rev-parse --abbrev-ref HEAD)
log="$(git rev-parse --git-dir)/korium-index.log"
( korium-cli index --branch "$branch" >>"$log" 2>&1 & ) >/dev/null 2>&1
exit 0Then make it runnable:
chmod +x .git/hooks/post-commitAfter each commit this starts an index in the background and hands your terminal straight back. Only the files that changed are sent, so a normal commit is quick.
Four choices in there are deliberate, and worth keeping if you rewrite it.
- After the commit, not before. An index is filed against a commit, and before the commit exists there is nothing to file it against.
- It never blocks. It backgrounds the work and always exits 0, so a slow index or an outage can never stand between you and a commit.
- It skips itself when the tool is missing. A teammate who has not installed Korium CLI gets a hook that quietly does nothing rather than an error on every commit.
- The log lives inside
.git. That folder is never committed, so the log cannot end up in your history. Read it withcat .git/korium-index.logwhen you want to see what happened.
Git does not share .git/hooks with anyone else. Each person who wants this installs it once. If you would rather keep hooks in the repository, commit the script somewhere tracked and point git at that folder with git config core.hooksPath <folder>, which everyone then sets once.
Every commit starts an index. That is usually fine, because only what changed is sent. If it feels like too much, take the hook off and run korium-cli index when you finish a piece of work instead. The index does not have to be perfect to be useful; it has to be close.
When something looks wrong
Four things account for almost every report.
- Your searches did not change after you re-indexed. You re-indexed the same commit without
--replace. Run it again with that flag. - A file you expected is missing. Check the rehearsal output. It names every file it read and found no symbols in.
- The command seems to hang. It is embedding, and you are not watching a terminal. See step 5.
- There is no Korium CLI card on your dashboard. The code index is invite-only while we grow it. Talk to Kyroco if your team wants it.
To sign a machine out, run korium-cli logout. It removes that Mac's sign-in and nothing else.
Every command and option
The app carries its own reference. This is the fastest way to check a flag:
korium-cli helpThe commands are login, status, index, search, logout, licenses and help.
| Option | What it does |
|---|---|
--repo-root <path> | The repository to read. Defaults to the folder you are in. |
--include <path> | Only this folder inside the repository. Repeatable. |
--dry-run | Read and report without sending. Needs no sign-in. |
--cards-out <path> | Also write what was found to a file, as JSON. |
--replace | Make this the index that answers for this commit. |
--full | Send everything, not only what changed. |
--branch <name> | The branch this commit is the head of. |
--allow-removals | Let this index take symbols out of Korium. |
--server <address> | The Korium server to use. You will not normally set this. |
korium-cli help covers everything above. Asking a single command for help, as in korium-cli index --help, is not supported and will tell you so.