Skip to main content

​
Codex setup

Install the npm wrapper and register unch with Codex: 
npm install -g @uchebnick/unch
unch codex install
Then restart Codex. unch codex install does two things:
  • registers the unch MCP server with Codex
  • writes the unch skill to ~/.codex/skills/unch/SKILL.md
The npm postinstall step does not modify Codex automatically. Run unch codex install explicitly when you want the integration.

​
How to use it

After restarting Codex, work in a repository and ask codebase questions normally. The installed skill tells Codex to call unch before broad file reads when semantic code search can help. Codex starts the stdio MCP server for you. You normally do not need to run unch start mcp by hand.

​
Tools

All tools accept an optional directory argument. Codex should pass the absolute path of the active repository so the MCP server operates on the workspace being edited, not on the directory where the server process was launched.

​
workspace_status

Returns the repository root, state directory, selected provider/model, index path, manifest metadata, and whether an index is already present. Agents should call this first.

​
search_code

Searches indexed code symbols with auto, semantic, or lexical mode. Agents should call this before opening many files or running broad grep-style exploration.

​
index_repository

Builds or refreshes the index for the configured workspace. Agents should call this when no index exists, when search reports no active snapshot for the selected provider/model, or when the user explicitly asks to rebuild.

​
create_ci_workflow

Creates .github/workflows/unch-index.yml in the target repository. Agents should call this only when the user asks to set up GitHub Actions-backed remote indexing.

​
bind_remote_ci

Binds the local .semsearch/manifest.json to a GitHub repository or workflow URL. Agents should call this after the workflow exists, or when the user provides a GitHub repository/workflow URL to bind for remote sync.

​
remote_sync_index

Refreshes the local index from the bound remote workflow. Agents should call this before local reindexing when workspace_status reports a remote_ci binding.

​
remote_download_index

Downloads and activates a published index artifact for a specific commit without binding the workspace to ongoing remote sync.

​
What Codex runs

The registered MCP server uses:
  • Name: unch
  • Command: unch-mcp
  • Arguments: none
unch-mcp is a small launcher for unch start mcp.

​
Notes

  • The installed skill passes the active repository directory into unch MCP tool calls.
  • The process reuses the same provider/model/runtime configuration across tool calls.
  • OpenRouter token lookup checks OPENROUTER_API_KEY, then ~/.config/unch/tokens.json, then .semsearch/tokens.json.
  • The MCP server exposes tools only in this release; streamable HTTP is not supported yet.