Project Code Intelligence

Repository intelligence and change-safety evidence for coding agents.

Project Code Intelligence (PCI) indexes Git repositories and gives coding agents structured evidence for research, refactoring, maintenance, and security work. Agents can search by concept or identifier, inspect candidate relationships, estimate a change's blast radius, find repeated implementation shapes, and query static-analysis findings before they edit code.

PCI is not an autonomous reviewer and its graph is not a compiler-grade call graph. It narrows discovery and supplies evidence; the agent still verifies important conclusions in source.

What It Helps With

Research and orientation

• Search exact identifiers, filenames, configuration keys, and known strings.

• Search by behavior when the relevant names are unknown.

• Inspect repository languages, file roles, snapshots, parser coverage, and index freshness.

• Fetch bounded records with paths, line ranges, metadata, and source snippets.

• Work across several repositories through named collections and repo filters.

Safer changes

• Find candidate callers, callees, references, tests, and module-level wiring.

• Check blast-radius evidence before removing, renaming, or changing a symbol.

• Surface entry-point, orphan, and test-coverage signals.

• Inject nearby evidence into supported coding agents when definitions are added or removed.

Maintenance and redundancy

• Find groups of functions that repeat a call-shape motif.

• Rank redundancy candidates by similarity, estimated abstraction cost, and likely net value.

• Run a repository audit for stale indexes, duplicate names, redundancy candidates, and static findings.

Security and static analysis

• Ingest SARIF reports alongside source records.

• Search normalized findings by tool, rule, level, baseline state, or path.

• Fetch diagnostics, code flows, and run metadata without making an agent parse raw SARIF artifacts.

Related MCP server: codebase-memory-mcp

How It Works

pci index parses repository files into bounded records, extracts metadata and candidate relationships, and stores snapshots in Postgres/pgvector. Semantic embeddings are optional: lexical search and most structural evidence remain available with --no-embed.

pci mcp exposes the index through a local stdio MCP server. Coding agents use its filter-oriented tools to discover likely-relevant code, then read and verify the live source before acting.

The default local architecture is:

• Postgres/pgvector: Docker or Podman Compose.

• Linux embedding services: Podman Quadlet units managed by user systemd.

• Apple Silicon embeddings: a native MLX service.

• Agent integration: a stdio MCP server, with optional edit-evidence hooks.

Remote Postgres and OpenAI-compatible embedding endpoints are supported when that tradeoff is intentional.

Quick Start

Install the CLI from a checkout:

uv tool install /path/to/project-code-intelligence
export PATH="$HOME/.local/bin:$PATH"

Start the bundled database and the best available local embedding backend:

pci doctor --start
pci doctor

Index a Git repository:

cd /path/to/repo
pci index .

Install MCP configuration for your coding agent:

pci mcp install --target codex

Supported targets include claude, codex, opencode, pi, vscode, copilot, cline, and zed. See docs/MCP_SETUP.md for client-specific setup, project scoping, and credential handling.

For lexical search without embeddings:

pci doctor --start-db
pci index --no-embed .

Core Agent Tools

Run pci audit for a whole-tree evidence report.

Evidence, Not Verdicts

PCI deliberately distinguishes stronger indexed facts from approximate and heuristic evidence.

• Candidate relationship edges are not type-checked call-graph facts.

• Blast radius cannot prove that a change is safe.

• Redundancy scores cannot decide whether two functions should share an abstraction.

• Static findings retain the limitations of their originating analyzer.

• An index can be stale after uncommitted or newly committed changes.

• Semantic retrieval can miss relevant code or return plausible neighbors.

Verify important callers and findings in live source. Use direct file reads for known paths and small bounded questions; PCI is most useful when the location, name, or impact is not yet known.

Installation

Python CLI

Install for the current user with uv:

uv tool install /path/to/project-code-intelligence

For an editable development install:

cd /path/to/project-code-intelligence
python -m venv .venv
. .venv/bin/activate
python -m pip install -e .

Nix

On NixOS or another Linux host with flakes enabled:

nix build
nix run . -- doctor --skip-db --embedding skip
nix develop

Install persistently into the user profile:

nix profile install .#project-code-intelligence

The Nix closure contains the CLI, MCP server, Python dependencies, and bundled Compose and Quadlet assets. Heavy Linux embedding runtimes remain in Podman containers rather than becoming host-native Nix dependencies.

Local database

Start only the bundled Postgres/pgvector database:

pci doctor --start-db

The installed Compose file is materialized into a user cache. To use a custom copy instead:

export PCI_COMPOSE_FILE=/path/to/docker-compose.yml
pci doctor --start-db

Local embedding service

The CLI includes the service templates; there is no separate PCI embedding package. On Linux, install Podman and ensure systemctl --user works, then run:

pci doctor
pci doctor --start-embedding

PCI detects available hardware, materializes only the selected backend under ~/.config/containers/systemd/, reloads user systemd, and starts it. Stale PCI units for other embedding backends are stopped and removed. Images and default models download on first use.

Choose a backend explicitly when desired:

# Apple Silicon GPU (MLX)
pci doctor --start-embedding --embedding-backend apple

# AMD GPU
pci doctor --start-embedding --embedding-backend rocm

# NVIDIA GPU
pci doctor --start-embedding --embedding-backend cuda

# Portable CPU fallback
pci doctor --start-embedding --embedding-backend fastembed

# AMD Ryzen AI NPU (experimental)
pci doctor --start-embedding --embedding-backend lemonade

Available selectors are auto, fastembed, lemonade, rocm, cuda, and apple. PCI rejects a requested backend when its required hardware or runtime is unavailable. apple runs natively rather than through Quadlet: it is supervised by a launchd agent and needs no container engine, pci embed apple starts it directly, and it also starts on demand from the first index run or semantic query, so on Apple Silicon no start command is required at all. The agent releases the model after PCI_APPLE_EMBED_IDLE_SECONDS without requests and the next demand brings it back.

To start the database and an explicit backend together:

pci doctor --start --embedding-backend rocm

Containerized backends publish an OpenAI-compatible endpoint at http://127.0.0.1:18081/v1/embeddings by default. Run one local backend at a time because they share this endpoint.

Stop embedding services without touching the database:

pci doctor --stop-embedding

Remove generated local services, caches, and the bundled database volume:

pci doctor --clean

--clean is destructive and prompts before removing data.

Remote embeddings

Start only the database, then configure a trusted OpenAI-compatible provider:

pci doctor --start-db
export PCI_ALLOW_REMOTE_EMBEDDING=1
export PCI_EMBEDDING_ENDPOINT=https://api.openai.com/v1/embeddings
export PCI_EMBEDDING_ENDPOINT_MODEL=text-embedding-3-small
export OPENAI_API_KEY=...
pci doctor

Remote endpoints receive source-derived text. Enable them only when that is acceptable for the repositories being indexed.

Indexing Repositories

Index one repository:

pci index /path/to/repo

Index several repositories as a workspace:

cd /path/to/workspace
pci index service-api web-ui shared-lib

PCI infers collection and repository names from the paths. MCP clients filter by these logical names rather than absolute filesystem paths. Indexing is incremental: unchanged files are reused when compatible snapshots exist.

SARIF reports found under indexed repository paths are ingested automatically. Reset and rebuild one repository with:

pci index --reset /path/to/repo

Use pci status to inspect indexing runs and pci index --help for parser, embedding, collection, and database options.

MCP and Agent Hooks

Create project-scoped read-only database credentials and print an MCP config:

pci index --init-db --mcp-config codex .

Install or remove MCP configuration without reindexing:

pci mcp install --target codex
pci mcp install --target codex --uninstall

Generated client configuration contains no database password. Credentials are stored under the user's PCI configuration directory with mode 0600. Pi uses a project-local .pi/extensions/ MCP bridge. Cline requires --config-path because its settings file is user-scoped.

Optional hooks can remind an agent to use the index and inject evidence near edits that add or remove definitions:

pci hook install --target codex

Hook support and installation details vary by client. Hooks are an aid, not an enforcement or correctness mechanism. See docs/MCP_SETUP.md and docs/SYSTEM_PROMPT.md.

Privacy and Security

The local default keeps source-derived records and embeddings on the machine. That does not make every artifact safe to publish.

Do not commit or distribute database dumps, restore artifacts, SARIF output, embedding caches, model files, vector indexes, generated data from private repositories, or local MCP credential files. They can contain source snippets, paths, symbols, findings, metadata, and embeddings derived from source.

Collections organize repositories but are not a security boundary. Use separate databases or database users when repositories require stronger isolation. Project-scoped MCP credentials restrict normal access, but they do not replace host and database security.

When PCI Is a Good Fit

PCI tends to help when:

• the repository or workspace is large or unfamiliar;

• identifiers are unknown at the start of a task;

• generated files make broad reads expensive or noisy;

• a refactor needs caller, test, and wiring evidence;

• maintenance work needs repeated-pattern discovery;

• static findings need to be correlated with source;

• several repositories must be searched through one interface.

It may add little value for a small familiar repository, a known file and line range, or a question answered by one bounded rg or file read. The goal is not to replace standard developer tools; it is to improve the uncertain discovery and change-planning steps around them.

Token and cost reduction can be a useful side effect, but PCI does not promise it. Measure whether the index improves real sessions using docs/EVALUATING_VALUE.md and the session retrospective prompt.

Development

The MCP server uses stdio; Docker Compose is for the local database, not for hosting the MCP process. Run the full development gate with:

nix develop
make check

For ingest, database, or MCP behavior changes, also run:

docker compose up -d pgvector
make integration-smoke

See CONTRIBUTING.md and AGENTS.md for project conventions and publication safeguards.

Documentation

• docs/MCP_SETUP.md — MCP clients, scopes, credentials, and security model

• docs/PUBLIC_API.md — CLI, environment, MCP, and Python compatibility surfaces

• docs/EVALUATING_VALUE.md — evaluating PCI on real coding sessions

• docs/SYSTEM_PROMPT.md — agent instructions for using PCI

• docs/SYSTEM_PROMPT_RATIONALE.md — prompt-design rationale

• docs/SESSION_RETROSPECTIVE_PROMPT.md — end-of-session evaluation prompt

• .env.example — environment configuration reference

• CONTRIBUTING.md — development workflow

License

MIT. See LICENSE.