Keep the index current with Git and GitHub

1. Install the local post-commit hook

From the repository you want to maintain:

korium-cli hooks install

The CLI uses Git’s configured hooks directory, including core.hooksPath. It will not overwrite a hook it did not create. If another tool, such as husky or lefthook, owns post-commit, install prints the lines to add at the end of that tool’s hook; review them and merge them with that tool’s owner. The lines start with a comment the CLI recognizes, so the next install says the hook already runs them instead of printing them again.

If core.hooksPath comes from your global git configuration rather than the repository’s, every repository on the Mac that does not set its own shares that folder, and so shares the hooks installed there. Install says so when it happens.

The installed hook runs korium-cli index --allow-removals --no-wait --from-hook after an ordinary commit. It updates the index of the branch the commit was made on. It permits intentional symbol removals and returns after upload acceptance, without holding the commit open while the server publishes the index.

The hook never holds a commit for a sign-in. If this Mac is not signed in, it opens the Korium sign-in in your browser in the background and the commit finishes at once; the index is updated when you finish signing in. While that sign-in is open, later commits do not open another. If you decline, or do not finish in time, hooks do not open the sign-in again for an hour, or until you run a korium-cli command yourself; until then each one prints a line saying the index was not updated and to run korium-cli login. On a Mac session that cannot open a browser, such as an ssh login, the hook prints that same line. A hook installed by an earlier korium-cli behaves the same way.

You may not need to type hooks install at all. When you index a repository from a terminal and it has no Korium hook, korium-cli asks once: “Keep this repository’s index current automatically? [y/N]”. Yes does exactly what korium-cli hooks install does. No, or Enter, is remembered for that repository, and korium-cli hooks install still works whenever you change your mind. The same question follows korium-cli login when you run it inside a repository. A hook, a pipe, CI or an agent is never asked, and a repository whose hooks you removed with hooks uninstall is not asked again.

Delete a branch’s index when you delete the branch

korium-cli hooks install --branch-deletes

This also installs a reference-transaction hook, so git branch -d or -D on a local branch deletes Korium’s index of that branch. It is opt-in because a branch’s index belongs to the whole workspace, not to one checkout. Renaming a branch with git branch -m never deletes an index; the index under the old name stays, and unless it is the trunk, Korium removes it once nobody has indexed that name for 14 days. The hook never deletes the trunk or a repository’s last index: Korium refuses those without --allow-removals, and the hook never sends it. The hook works in the background, so git branch -d never waits on Korium. What it did, refusals included, is written to ~/.local/state/korium-cli/branch-deletes.log rather than printed. A post-commit hook owned by another tool does not stop this one from being installed.

To delete a branch’s index yourself, run korium-cli delete BRANCH from the repository. It deletes Korium’s index and leaves your git branch alone.

Know what that hook does not cover

A merge does not run Git’s post-commit hook. Replayed commits during operations such as rebase, cherry-pick and revert are deliberately skipped by Korium’s hook. Run korium-cli index after the operation settles, or let the next ordinary commit do it.

A post-commit failure does not undo the commit. The commit may be fine while the search index is still stale. A successful no-wait run is also not a publication check.

The Git hook sees only commits. An agent edits between commits, so korium-cli hooks install also prints an end-of-task hook for Claude Code, described in the Claude Code guide; Codex has its own task-end example. Each hook updates only the index of the branch it runs on. When a second one runs and no file has changed since the first, it finds nothing to send.

Use the setup checklist to verify transcript sources, memory connections and your branch code indexes before automating the work.

Remove the hook safely

korium-cli hooks uninstall

The CLI removes only the hooks it recognizes as its own, the branch-delete hook included. To remove only the branch-delete hook and keep the post-commit hook, run korium-cli hooks uninstall --branch-deletes. If you manually incorporated its lines into another hook manager, remove that entry through the same manager instead; uninstall leaves that file alone and says so. Don’t delete somebody else’s post-commit file.

2. Prepare a self-hosted Mac for GitHub Actions

The current CLI is a macOS application with a local keychain sign-in. This example uses a dedicated, self-hosted Mac, not an ephemeral GitHub-hosted runner. Use a private, trusted repository and a runner group restricted to the intended repository.

Install the CLI and complete login under the same operating-system account that runs the runner. Verify /usr/local/bin/korium-cli status in the runner’s actual execution context. If it cannot access its sign-in there, stop and fix that host setup; don’t export credentials into GitHub secrets.

Label the runner korium after those checks. Protect changes to workflows and the default branch. Do not allow untrusted pull requests to execute on a machine holding Korium credentials. GitHub explains the risk in its self-hosted runner security guidance.

3. Start with a manual, reviewed run

Save this as .github/workflows/korium-index.yml. It indexes the repository’s default branch, which is normally its trunk: the index a search reads when it names no branch. It runs only when a permitted person dispatches it on the default branch; it does not run pull-request code.

name: Index the reviewed default branch
on:
  workflow_dispatch:

permissions:
  contents: read

concurrency:
  group: korium-code-index
  cancel-in-progress: false

jobs:
  index:
    if: github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
    runs-on: [self-hosted, macOS, korium]
    timeout-minutes: 45
    steps:
      - name: Check out the reviewed commit
        # Pinned checkout v4.2.2. Review updates under your team's policy.
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683
        with:
          ref: ${{ github.event.repository.default_branch }}
          fetch-depth: 0
          persist-credentials: false
      - name: Verify the publishing checkout
        env:
          KORIUM_EXPECTED_BRANCH: ${{ github.event.repository.default_branch }}
        shell: bash
        run: |
          set -euo pipefail
          korium_branch=$(git symbolic-ref --quiet --short HEAD)
          test "$korium_branch" = "$KORIUM_EXPECTED_BRANCH"
          test -z "$(git status --porcelain --untracked-files=normal)"
      - name: Check the runner's Korium connection
        run: /usr/local/bin/korium-cli status
      - name: Build and publish the code map
        run: /usr/local/bin/korium-cli index --allow-removals

The full fetch preserves repository history for the root-based identity. The explicit ref and branch check avoid silently publishing from a detached or different checkout. The pinned action is a reviewed example version, not a claim that it is the newest release.

If the runner’s checkout does not record which branch the remote calls its default, korium-cli says so and does not tell Korium which branch is the trunk. Korium then keeps the trunk it has, or, for a repository with none, takes this first index as the trunk.

The CLI makes a bounded publication check here. A green job does not, by itself, prove the new commit answers searches. Complete the verification below before reporting it ready.

Before allowing an automatic trigger, prove the manual run works and decide who can update the default branch’s index. Don’t add pull_request_target or check out an untrusted PR head on this authenticated machine.

4. Verify the result, not just the green job

Read the job’s final publication output, then search for a known symbol at the commit that was checked out. Confirm the returned commit and open the corresponding source span. Even without --no-wait, a zero CLI exit can leave publication unverified.

For a structured check, call code_locate with the repository identity and actual checkout SHA. Inspect the returned index commit, freshness information and symbol location. Do not parse a progress sentence as a stable machine API.

This workflow updates the code map. It does not copy issues, pull requests or review decisions into company memory. If you build that separate integration, give it explicit access and record the source links, author and review status of what it captures.