Practical overview
When it fits
Use H Codex when you want to build a searchable index of code projects and make semantic retrieval available to an MCP-compatible coding assistant.
Who it is for
- Developers who need semantic search across multiple code projects.
- Teams connecting code retrieval tools to AI coding assistants that support MCP.
- Developers interested in a MIT-licensed TypeScript code-indexing tool.
Documented uses
- Index code projects using AST-based chunking and embeddings.
- Search indexed projects semantically for relevant code context.
- Provide code-indexing and search tools to an MCP-compatible AI coding assistant.
Requirements & limits
- Requires PostgreSQL with pgvector and an embedding API key for embeddings.
- The documented development setup lists Node.js v18+, pnpm, and Docker.
- The README identifies OpenAI text-embedding-3-small as the default embedding model; Voyage AI support is listed as planned.
- The project is licensed under MIT.
Check current requirements in the official documentation. Source-based guidance does not mean OpenViST has run or independently tested this project.
Configure H Codex in Claude Desktop
Add the H Codex MCP server configuration so Claude Desktop can connect to its indexing and semantic-search tools.
Before you start
- Claude Desktop and its MCP settings file
- An embedding API key
- A PostgreSQL database with a connection string
Steps
Open the Claude Desktop MCP settings file, claude_mcp_settings.json.
Add an h-codex entry with command npx and argument @hpbyte/h-codex-mcp.
Set LLM_API_KEY, LLM_BASE_URL, and DB_CONNECTION_STRING in that entry; the README gives the OpenAI base URL as the default.
Expected outcome
Claude Desktop has a documented MCP server configuration for H Codex's code-indexing and semantic-search tools.
Guide limitations
- The configuration example does not document indexing a project or performing a search.
- The documented default embedding model is OpenAI text-embedding-3-small; Voyage AI support is planned.
Prepare the H Codex development environment
Follow the repository's documented steps to install dependencies, start PostgreSQL, and run database migrations.
Before you start
- Node.js v18 or later
- pnpm
- Docker for PostgreSQL with pgvector
- An OpenAI API key for embeddings
Steps
Clone the repository and enter the h-codex directory.
Copy packages/core/.env.example to packages/core/.env and configure the OpenAI API key and other settings.
Run pnpm install.
From the dev directory, run docker compose up -d to start PostgreSQL.
Run pnpm run db:migrate.
Expected outcome
The documented development setup steps prepare dependencies and the database schema; the README lists pnpm dev as the next development-server step.
Guide limitations
- This recipe covers environment and database setup; it does not verify that the server runs or that indexing and search succeed.
Sources & review
Source record details
- Source availability
- Active
- Sources checked
- 17 October 2026
- Original website title
- hpbyte/h-codex · Official homepage title · retained in its source language