README
¶
ProjectLens
Local-first codebase intelligence for AI coding agents.
ProjectLens indexes your Go code, database schemas, git history, package summaries, embeddings, and captured project knowledge into Postgres, then serves it over MCP. Claude, Codex, Cursor, and any other MCP-capable agent can ask grounded questions about the repo instead of re-reading files and rebuilding context every session.
Source stays on your machine. Agents talk to the ProjectLens MCP server, and the server answers from a local index. Public alpha ships no remote provider integrations — embeddings run on a local Ollama endpoint and package summarization is disabled by default.
Install
| Binary | Install |
|---|---|
| CLI | go install github.com/hman-pro/projectlens/cmd/projectlens@latest |
| MCP server | go install github.com/hman-pro/projectlens/cmd/projectlens-mcp@latest |
| TUI | go install github.com/hman-pro/projectlens/cmd/projectlens-tui@latest |
The quick start below uses a local clone plus make build to get all three binaries consistently.
Quick start
Requires Ollama, Postgres-capable Docker, and Go 1.26+.
ollama pull qwen3-embedding:0.6b
cp .env.example .env
cd docker && docker compose up -d
cd ..
make migrate
make index-all REPO=.
make build-projectlens-mcp
./bin/projectlens-mcp
Summarization is disabled by default. To enable it, edit configs/index.yaml:
summarization:
enabled: true
provider: ollama
model: qwen3-coder:30b
endpoint: http://localhost:11434
This downloads ~19 GB and requires a strong machine.
Start Here
| Need | Read |
|---|---|
| Set it up quickly | Quick start |
| Wire an agent into a target repo | docs/AGENT_SETUP.md |
| Understand the architecture | docs/architecture.md |
| Run CLI, TUI, Docker, reports, or troubleshooting | docs/operations.md |
| Work on ProjectLens internals | CLAUDE.md, then docs/internals.md |
Why it exists
AI assistants forget. Every new chat starts cold, so the agent has to grep, re-open files, infer call paths, and guess which conventions matter. On a large monorepo, that is slow, expensive, and easy to get wrong.
ProjectLens does the reading once and keeps the result queryable:
- Find symbols, packages, callers, callees, and interface implementations.
- Trace which Go code reads or writes a database table.
- Search code semantically when the exact symbol name is unknown.
- Check index freshness before trusting an answer.
- Look up recent git history and files that tend to change together.
- Capture durable lessons during a session and surface them later.
Status
Public alpha. APIs and on-disk schemas may break between tagged releases.
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
projectlens
command
|
|
|
projectlens-mcp
command
|
|
|
projectlens-tui
command
|
|
|
internal
|
|
|
chunks
Package chunks creates embeddable text chunks from parsed symbols.
|
Package chunks creates embeddable text chunks from parsed symbols. |
|
embeddings
Package embeddings provides a pipeline for converting text chunks into vector embeddings via a local Ollama embedding model.
|
Package embeddings provides a pipeline for converting text chunks into vector embeddings via a local Ollama embedding model. |
|
graph
Package graph builds call graphs from type-checked Go packages and extracts dependency edges using SSA and CHA analysis.
|
Package graph builds call graphs from type-checked Go packages and extracts dependency edges using SSA and CHA analysis. |
|
indexer
Package indexer orchestrates the full indexing pipeline: census, parsing, chunking, graph building, summarization, and embedding.
|
Package indexer orchestrates the full indexing pipeline: census, parsing, chunking, graph building, summarization, and embedding. |
|
indexstate
Package indexstate holds read-only, MCP-server-free types and helpers for inspecting ProjectLens's indexed state.
|
Package indexstate holds read-only, MCP-server-free types and helpers for inspecting ProjectLens's indexed state. |
|
logger
Package logger provides a shared structured logger for the ProjectLens pipeline.
|
Package logger provides a shared structured logger for the ProjectLens pipeline. |
|
mcpserver
Package mcpserver exposes ProjectLens's retrieval capabilities via the Model Context Protocol (MCP) over Streamable HTTP.
|
Package mcpserver exposes ProjectLens's retrieval capabilities via the Model Context Protocol (MCP) over Streamable HTTP. |
|
parser
Package parser extracts symbols from Go source files using go/packages for type-checked parsing.
|
Package parser extracts symbols from Go source files using go/packages for type-checked parsing. |
|
providers/identity
Package identity defines the ProviderIdentity type used to identify which vendor and model handled a specific role (embedding or summarization).
|
Package identity defines the ProviderIdentity type used to identify which vendor and model handled a specific role (embedding or summarization). |
|
providers/ollama
Package ollama provides an embedding client that talks to a local Ollama instance, satisfying the embeddings.Embedder interface.
|
Package ollama provides an embedding client that talks to a local Ollama instance, satisfying the embeddings.Embedder interface. |
|
rerank
Package rerank applies scoring adjustments and sorting to retrieval results.
|
Package rerank applies scoring adjustments and sorting to retrieval results. |
|
storage/writelock
Package writelock provides cross-process serialization for the projectlens indexer.
|
Package writelock provides cross-process serialization for the projectlens indexer. |
|
summaries
Package summaries provides heuristic and LLM-based file summary generation.
|
Package summaries provides heuristic and LLM-based file summary generation. |
|
tui/components/confirmmodal
Package confirmmodal renders a centered yes/no or typed-phrase confirmation modal.
|
Package confirmmodal renders a centered yes/no or typed-phrase confirmation modal. |
|
tui/components/errormodal
Package errormodal renders a centered, blocking error dialog.
|
Package errormodal renders a centered, blocking error dialog. |
|
tui/components/jobdrawer
Package jobdrawer renders the bottom-of-screen strip that streams the currently-running job's tail and surfaces completion status.
|
Package jobdrawer renders the bottom-of-screen strip that streams the currently-running job's tail and surfaces completion status. |
|
tui/jobs
Package jobs runs single-slot subprocess invocations of projectlens from inside the TUI.
|
Package jobs runs single-slot subprocess invocations of projectlens from inside the TUI. |
Click to show internal directories.
Click to hide internal directories.