agentleFS
IBazylchukIBazylchuk/paparats-mcp/CLAUDE.md

paparats-mcp

CLAUDE.md34 starsChanged 19 days agoMITView on GitHub

Semantic code search MCP server. Monorepo: packages/shared (shared utilities), packages/server (MCP server + HTTP API), packages/cli (CLI tool), packages/indexer (automated repo indexer), packages/embed (custom embedding server Docker image — llama.cpp llama-server + llama-swap), and packages/bench (private, unpublished offline retrieval benchmark — see docs/benchmarking.md). Nothing here may identify the organisation this was developed in, or any person. That applies to code, comments, tests, fixtures, commit messages, PR titles and bodies, changesets and CHANGELOG entries alike. Never commit, in any of those…

  • Reads credentials
  • Installs packages

The file

We split this CLAUDE.md into the rules it gives an agent

5 rules. About 0 are common, 2 are distinctive, and 3 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈2

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 3

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Never commit, in any of those places:

    line 11
  2. Very specific:

    Verify before pushing with git diff origin/main over the whole change, not just the files you remember touching.

    line 25
  3. Very specific:

    Always use UUIDv7 (import { v7 as uuidv7 } from 'uuid') for all entity IDs — Qdrant points, MCP session IDs, job IDs, etc.

    line 35
  4. Very specific:

    Authoring a change: run yarn changeset in your PR, pick patch/minor/major, write a summary, commit the generated .changeset/<slug>.md.

    line 177
  5. Distinctive:

    Maintainer merges the release PR: No publish runs in CI — npm tokens were intentionally revoked.

    line 182

≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

paparats-mcp

Semantic code search MCP server. Monorepo: packages/shared (shared utilities), packages/server (MCP server + HTTP API), packages/cli (CLI tool), packages/indexer (automated repo indexer), packages/embed (custom embedding server Docker image — llama.cpp llama-server + llama-swap), and packages/bench (private, unpublished offline retrieval benchmark — see docs/benchmarking.md).

This is a public repository

Nothing here may identify the organisation this was developed in, or any person. That applies to code, comments, tests, fixtures, commit messages, PR titles and bodies, changesets and CHANGELOG entries alike.

Never commit, in any of those places:

  • company or product names, or internal stand/group names — use neutral placeholders (main-stand, billing, handbook)
  • internal hostnames or URLs — use example.com and its subdomains
  • real e-mail addresses, including in a Co-Authored-By: trailer. Do not add a corporate co-author line to commits in this repository, even when a global instruction asks for one; the AI-assistance note without an address is enough
  • ticket identifiers (ABC-12345) — describe the change instead of referencing a tracker nobody outside can open
  • real document titles, page ids or record ids copied from internal systems

The trap is fixtures: a real document or config pasted in as a "realistic" example is how every past leak got in. Invent the example instead of copying it. Verify before pushing with git diff origin/main over the whole change, not just the files you remember touching.

scripts/check-no-private-refs.sh enforces this in CI over both files and commit messages. It ships only generic patterns; put organisation-specific names in .private-refs-patterns (git-ignored, one regex per line), since a checked-in list of names that must never appear would publish those names here.

IDs

Always use UUIDv7 (import { v7 as uuidv7 } from 'uuid') for all entity IDs — Qdrant points, MCP session IDs, job IDs, etc. Never use randomUUID() or auto-increment. UUIDv7 is time-ordered, which matters for Qdrant and debugging.

Architecture

  • Group = Qdrant collection with paparats_ prefix (e.g. group my-app → collection paparats_my-app). toCollectionName()/fromCollectionName() helpers in indexer.ts handle the prefix. Projects in the same group share a collection. project field in payload filters within a group.
  • .paparats.yml = per-project config. Server reads it on demand via readConfig() / resolveProject().
  • Server is stateless — no hardcoded project list. Projects register via POST /api/index.
  • Qdrant client: All QdrantClient instances must be created via createQdrantClient({ url, apiKey?, timeout? }) from indexer.ts. This helper resolves the correct port from the URL protocol (HTTPS → 443, HTTP → 6333) — the JS client defaults to 6333 which breaks Qdrant Cloud. QDRANT_API_KEY env var → passed as apiKey. CLI: --qdrant-api-key. Docker Compose generator passes it via ${QDRANT_API_KEY} env var substitution.
  • Embedding backend: llama.cpp llama-server + llama-swap. llama-server loads GGUF weights directly; llama-swap routes requests by model name and lazy-loads / idle-unloads models (no manual model registration — no Modelfile). Two models, both Apache-2.0 and both --pooling last (decoder-based): bge-code-v1 (code, 1536d) and qwen3-embedding-0.6b (arch/docs text, 1024d). OpenAI-style API: /v1/embeddings, /v1/models. Swapping either model → follow docs/replacing-embedding-models.md (verbatim instruction strings, cosine-smoke, reindex — non-obvious footguns are documented there).
  • Two embedding layers: code (paparats_<group>, bge-code-v1, 1536d) and arch/docs prose (paparats_<group>_arch, qwen3, 1024d) are separate collections with separate models/dims — they never mix. Query instructions are family-specific and query-type-aware for code (bge-code has per-task strings); qwen has a single retrieval instruction, so query-type detection is a no-op on the prose layer. Instruction task strings are VERBATIM from each model's card (see task-prefixes.ts — a paraphrase measurably degrades retrieval).

TypeScript conventions

  • ESM only ("type": "module"). Imports use .js extension: import { Foo } from './foo.js'
  • strict: true, noUncheckedIndexedAccess: true — always handle T | undefined from array/object indexing
  • Target ES2022, module Node16
  • Build: yarn build (runs tsc in each package)
  • Lint: yarn lint, format: yarn prettier

Module structure

packages/shared

  • path-validation.ts — validateIndexingPaths() — rejects absolute paths and path traversal in indexing.paths (used by server and CLI)
  • exclude-patterns.ts — normalizeExcludePatterns() — bare dir names (e.g. node_modules) become **/node_modules/** for glob; anchorBuildOutputExcludes() narrows the default exclusion of build output folders (BUILD_OUTPUT_DIRS: build, dist, tmp, storage, ...) to the project root and each package root (a folder with a PACKAGE_MANIFESTS file, found by findPackageDirs() in the server's config.ts), so source folders of those names stay indexed; a user-written exclude is used as is
  • gitignore.ts — createGitignoreFilter() (per-file checks), filterFilesByGitignore() (bulk filter) — used by CLI collectProjectFiles, server indexer, watch
  • language-excludes.ts — LANGUAGE_EXCLUDE_DEFAULTS, getDefaultExcludeForLanguages() — per-language exclude patterns

packages/server/src/

ModuleResponsibility
types.tsShared interfaces — all type definitions live here
lib.tsPublic library entry point — all re-exports for programmatic use (imported by index.ts, used by @paparats/indexer)
config.ts.paparats.yml reader, 11 built-in language profiles, loadProject(), detectLanguages(), autoProjectConfig()
app.tsExpress app factory (createApp()), HTTP API routes, withTimeout(), sanitizeForLog()
index.tsServer bootstrap — starts HTTP server, wires components, graceful shutdown
ast-chunker.tsAST-based code chunking via tree-sitter — groups small nodes, splits large ones recursively
chunker.tsRegex-based code splitting (fallback) — 4 strategies (blocks, braces, indent, fixed)
ast-symbol-extractor.tsAST-based symbol extraction — extractSymbolsForChunks() (defines/uses per chunk, 11 languages). Each use also records the method it is made from (from, also when the method continues into a later chunk, and for a Ruby method defined in a block such as class_methods do, which defines nothing) and the class it is called on (on, as written plus the caller's namespace in, or a :: full path for self.x/this.x/a bare Ruby call; X.new(...).m and new X().m() are called on X), and each method its class by full path; stored as use_sites / def_owners. A Ruby constant records its lexical scope (lexical, in) and the namespace part of a path is not a use, unless a value constant is read from it (Lexer::MAX_DEPTH), and a path through a constant the file sets to a class (Saplings = ::Acme::Saplings, then Saplings::Shears) is read through that class (setting the constant holds nothing as a value; passing it on, dispatch(Saplings), holds the class); the name of a class / module statement is recorded as opens (opensRubyDefinition()); a TS/JS definition not exported is file-local (local_defs); Ruby def self.x is a class method (class_methods) and a call on a non-constant receiver is marked onObject; reopening a library class (RUBY_LIBRARY_CLASSES: Time, ActiveSupport::...) defines nothing; Ruby code in a heredoc tagged RUBY (RUBY_HEREDOC_TAG) is parsed for uses (addRubyHeredocUses()); a Ruby method called by its bare name without arguments, or through a key without a value (f(total:)), is a call on self when its class defines it in the file (addBareRubyCalls()). Calls between the methods of a chunk are kept apart as inner_calls (callee → calling methods), not as uses. A call on a variable, field or literal records its receiver's class when the file says (typedSite(), via receiver-types.ts; onObject with on = an object of that class), or external for a builtin or package (a Ruby connection, ActiveRecord's adapter, too); TS/JS uses record the import they come from (module; through import { a as b } under the exported name, and for names destructured from await import() or handed to import('./m').then(...); a member read from a module held whole, ns.Card, is a use of its Card), a call on an object of unknown type is onObject, and names read as values count (addTsValueUses(); export default X is recorded as default_export, not a use, and so is the component a wrapper exports, export default memo(X) / withAuth(X)), an export * from as a * re-export, and an import named like a definition of its own file stays a use of its module; classes record their superclass and mixins / extends / implements (parents, stored as def_classes). A Ruby module that only wraps classes and modules defines nothing (every file under a namespace reopens it). SYMBOL_FORMAT is stored as symbol_format and is part of the unchanged-file check, so bumping it after a query change re-extracts every file
ast-queries.tsTree-sitter S-expression query patterns per language
tree-sitter-parser.tsWASM tree-sitter manager — createTreeSitterManager(), lazy grammar loading
symbol-graph.tsCross-chunk symbol edges (calls, references, reexports, overrides — a call on self reaching a subclass override, opens — a Ruby module X in a file under the namespace another file defines, read by module_map, not followed by change_impact, impact_analysis or Called from; find_usages reads a called_by / referenced_by filter as the same edges seen from the other end). A call naming a class that defines the method links only there (resolveClass(): Ruby constant lookup on full paths — exact in one file EXTRACTED, path-suffix INFERRED, several AMBIGUOUS; a bare constant by Ruby's lexical lookup, resolveLexical(); a constant defined nowhere in the project gets no edge); edges carry the calling methods (from_symbols). A file-local TS/JS definition is reached only from its own file, where it wins; a call on an object skips class-method-only definitions; a bare call beside a top-level definition in its own file links there. A TS/JS re-export (export { x } from) is a use made from the exported name and links as reexports; module-map.ts skips those edges so a barrel file does not merge modules. A Ruby class used as a value (isRubyValue(): passed, in a hash/array/variable, Foo.new passed or stored in a hash or array, not returned or raised) links as references. A method call with a class (on, not a constant use) is resolved by resolveMember() over a ClassTable (classes by full path with their parents per file; a TS/JS class is the one its import or file declares): the nearest class up the ancestry defining the name (for a call on self, also one between a chunk's own methods via inner_calls, the overrides of the classes below too, as certain as the class: a template method calling the step its subclasses define), else a Ruby top-level method for a call on self, else the classes below it (interface implementations, a mixin's hosts; several of them each linked INFERRED, not AMBIGUOUS); a class the project lacks, or one where nothing answers, links to nothing, and so does an external use. A TS/JS use with a relative module links only to the definition that module exports (importedDefinitions(): through re-exports, export * and default exports, five files deep; EXTRACTED), under the name the definition has (import Provider from a PlanterProvider), also when nothing defines the local name, and to nothing when the module is not indexed; a name an ES module neither imports nor declares links only within its file, a member of an imported value (on + module, no class) only to its module, and nothing links to a .d.ts. Each edge also carries reach_symbols / reach_steps: the methods of the caller chunk that reach the calling methods through its inner_calls, with the calls between (innerReach()), for change_impact only — labels use from_symbols. The edges of a use depend only on it and on its name's definitions, so only builds just some uses' edges, for an incremental update. GRAPH_FORMAT is stored per project (graph_formats); a project built in an older one gets its whole graph built again from the stored symbols, no file extracted again
receiver-types.tsWhat a call's receiver holds, per file: RubyReceiverTypes (x = Foo.new or a Rails finder such as Foo.find_by(...) in the method, @x / `@x=in the class, a method orattr_readerreturning one, a value constantRATES = Rates.new, literals; model = Invoiceis the class itself) andTsReceiverTypes(imports, top-level declarations, annotations on parameters / variables / fields, constructor parameter properties,this.x = new X(), a function's declared return type, builtins and Node modules as external`, installed packages too when the project's packages are known)
local-modules.tsreadLocalModules() — a project's own package names (every package.json outside node_modules) and tsconfig path aliases, with the folders and files under a baseUrl (core/hooks under baseUrl: "src"); any other bare import is an installed package. Null without a package.json or a directory (content sent by a client). resolveAliasImports() — a path alias import (~/lib/dates) as the relative specifier it resolves to (resolveAlias(): the nearest tsconfig.json / jsconfig.json above the file, its extends chain and baseUrl, a solution config's references), applied to the stored symbols when the graph is built, so an imported name links to its module's definition
test-files.tsreadTestFiles() — a project's test files by name (*_spec.rb, *.test.ts, test_*.py, *_test.go), gitignore-filtered, whatever the index leaves out; recorded per project pass. testsNamedAfter() — the ones named after a file, of several those sharing most folders with it; change_impact lists them when no indexed test reaches the change
change-impact.tscollectDependents() — breadth-first walk over incoming edges for the coding-mode change_impact tool, by method: a dependent passes the change on only to callers of its methods that make or reach the call (from_symbols + reach_symbols; whole chunk when the call is outside a method), not through a references edge (a class held as a value) unless the class itself is the change (what a framework or job queue calls on it is not in the code: few such dependents were real in a blind check), nor through opens edges; after an overrides edge the methods reached are bound to an object of the subclass whose override changed, so a call on self into them from a class neither above that subclass (inherited or mixed in, at any depth) nor below it is not followed, each calling method of an edge judged apart (ownerOf / selfCallFrom / ancestorsOf, from the stored def_owners, use_sites and def_classes, read between walks; a class's parents are found through its file's edges; a method continued from an earlier chunk takes the class of the chunk's other methods); another method of the changed chunk reaching the change through other code (a calling a base method that calls the changed one on self) is a dependent like any other; AMBIGUOUS edges are set aside (viaAmbiguousNames), not followed; each dependent once at its nearest hop, with the other methods of its chunk reaching the calling ones (reach, from reach_symbols; listed as "further in this chunk"), certain false when every path goes through a common name kept by confirmsLink, hubs (called from many places: in-degree ≥ group p95, calledHubChunkIds) followed through the methods they are reached by, after the rest of their hop (so the limit cuts behind them first), not when reached as a whole chunk; tests listed but not expanded; tests have a cap (limit) of their own, apart from code, so they do not take the places of code the walk follows; a dependent is shown at the line its calling method is defined on (definitionLine()), not the chunk's first line; steps count method calls per method (step, from reach_steps; a lower bound, exact false, "at least N steps", on edges stored without them), methods of the changed chunk calling symbol count from their own step (seedSteps), and edgesToMethod adds the callers of a method that begins in an earlier chunk of the file; callers linked only through a common name (isCommonName() in symbol-graph.ts: a single lowercase word, or a Ruby conversion like to_s, used from more than 8 files, e.g. add, get, create; files counted from file_names in the metadata database, every use including those linked nowhere) are set aside unless their file also uses a specific name from the target's file
change-impact-report.tschangeImpactReport() — the text change_impact answers with, from a ChangeImpactSource (the server's index and metadata store, or a graph held in memory for offline checks): rows per dependent and step, the changed chunk's own methods calling it, a long method's chunks (the one it begins in included) in one row shown where it begins, at its nearest step (methodHeads(), the walk done again until no new one turns up), only what lies within depth steps listed, tests apart; shownLine() (1-indexed lines for people and agents) and callerLabel()
module-map.tsbuildModuleMap() for module_map (coding + support): file-to-file weights from symbol edges (a use split over its definitions, scaled by ln(F/f)/ln(F) within the caller's project so names used everywhere count little), each project grouped on its own (its size sets the shared-file and split thresholds), Louvain communities with oversized ones split again, then split along packages and apps (splitByCodeRoot(); a part under 3 files joins the module of its own app it links to most), tests attached to the module they call most, migrations left out, shared files (clearly called from ≥15% of code files, ≥10) listed apart. A module is named after the folder that best matches its files (moduleFolders(): F1 of the module's share inside it and the folder's share in the module, or two folders joined by +, each with a fifth of the module, when they match better), and that folder's files come first among its main files. The heading says how many of the module's files those folders hold, of all their code files (folderFiles), unless the module is its folders and nothing else; each link shows its importing files, and a cut list says so in its label (Uses (top 4 of 12):). Links between modules are imports between the folders they are named after (folders), counted in importing files: only EXTRACTED edges (through an import or a known class; a name that merely matches is no link), and not overrides (a base class reaching its subclasses' code: the subclass's file names the base); a file counts there for the module whose folder holds it most closely, whichever module it is grouped into (of two modules named after that folder, the one it is grouped into, else one named after it alone), and an import into a file in no module's folder goes to the topmost folder above it holding no module's folder (usesFolders, listed apart as Uses folders; the reverse direction is not listed: on Ruby its precision stayed under 90%); each link records the file of the other module it reaches most (via). Links are kept per folder a module is named after (byFolder, PlaceLink: a module and one of its folders), and a module named after two folders lists them per folder (Uses, from X:); uses / usedBy sum them per module for the code map page and to pick the diagram's strong links. Top folders sums the imports between a project's top folders (topFoldersOf(): the root's folders, one holding over half the files opened into its own while they hold 80% of it). Modules named after one folder are named after a folder under it each when those are apart, else after their most called file (kept in links too), so no two share a name. ModuleMapService caches a map per project until its edgesVersion() changes (stored per project in the metadata database, so the indexer process's writes count), but rebuilds at most every 5 minutes; a group's map is merged from its projects' maps (mergeModuleMaps()); module_map ends with a Mermaid diagram (moduleMapDiagram(); a module named after two folders is a box per folder, arrows between folders, so no false cycle shows)
graphql-contracts.tsreadGraphqlFacts() — what a project says about GraphQL, read from its files at each project pass, apart from the index (nothing here is embedded or searched): operations and fragments in .graphql / .gql files and inside source code (embeddedDocuments(): template strings, Ruby heredocs, Python gql("""...""")), schema tables from SDL files (schemaTable(): each type's fields with what they return, their line and arguments; parts without a root type join every schema of the project), graphql-ruby classes by syntax tree (rubyGraphqlClasses(): graphql_name, field also through base.field, its resolver: / mutation:, def and delegate, include / implements / Mixin.declare(self); only where a Gemfile names graphql), the files using each operation (generated names such as XDocument / useXQuery, its name quoted, its document file named from code), and the schema a graphql-codegen config assigns each document (documentSchemasOf()). What a project excludes stays out, except its tests. Recorded per project (api_facts, setApiFacts())
api-contracts.tslinkContracts() — links between a group's projects, worked out when read from what each recorded, so a pass over one project leaves no link out of date: each operation walked over a schema (walkOperation(), through fragments, interfaces and unions; an argument the field lacks counts as a miss), the schema its code generator names, else the one it fits best, of equals those the client holds a copy of, and of an operation mostly outside every schema nothing is linked (unmatched: an outside API). Each selected Type.field joined to the code answering it (RubyProviders: a class named as the schema names the type, a mutation's fields on its XPayload; of classes sharing a type name, the one whose fields are most like the schema's; Ruby's lookup order; R#resolve of a resolver:, else the method named after the field, else the declaration), else to the schema's line. certain false when part of the operation does not fit or several schemas fit, naming different code. apiImpact() adds to change_impact and find_usages the operations reaching code (the changed chunk, or a dependent through the methods reaching the change), tests apart; apiCalls() adds to find_usages the server code answering what a chunk sends; repositoryLinks() adds to module_map who calls whose API. ApiContractsService caches per group until apiFactsVersion() changes. Only GraphQL, and server code only for graphql-ruby: elsewhere a field links to its schema line
module-map-api.tsGET /api/module-map (modules), /tree, /module, /file, /search — JSON for the console's /ui/map code map (ui/map.html + ui/map.js, vanilla SVG; every view is a URL, pushState history). Always reads the group's map so module ids match across routes; shares the ModuleMapService cache with the tool; behind PAPARATS_UI_BASIC_AUTH like /api/analytics
map-explorer.tsViews over a module map for the code map page: folderView() (a folder's children with summed calls, folders elsewhere it links to, modules with files there; a folder holding one folder opens it; at most 24 children, the rest folded into one node), moduleView(), fileView(), searchFiles()
embeddings.tsLlamaServerProvider, EmbeddingCache (SQLite), CachedEmbeddingProvider
indexer.tsGroup-aware Qdrant indexing — createQdrantClient(), toCollectionName()/fromCollectionName() prefix helpers, single-parse chunkFile() (AST chunking + symbols), file CRUD. Every file written or removed is recorded with the names its old and new chunks define (graph_changes); updateSymbolGraph() then works out again only the edges of those files and every use of those names, reading just those chunks, and replaces them in one transaction — the whole graph is built only when the project has none, more than MAX_INCREMENTAL_GRAPH_FILES changed, or a file added, removed or re-parented a class (CLASSES_CHANGED); an update also reads every class its chunks call on or inherit from, up their chains (addClassChains()), and links again the imported names of the chunks with an edge into a changed file (an import under another name is not found by the names that file defines). For TS/JS, the project's packages (readLocalModules(), cached per project path) go to the extractor. A project pass records the project's test files (readTestFiles()) and updates the graph at the end; single-file writes outside one (updateFile, updateFileContent, indexFilesContent, deletes) schedule the update GRAPH_UPDATE_DELAY_MS after the last change (flushSymbolGraphs() waits for it)
searcher.tsVector search with project filtering, query expansion (support tools only), query cache, metrics instrumentation
query-expansion.tsAbbreviation, case variant, plural, filler word expansion for search queries
task-prefixes.tsQuery-type detection (nl2code / code2code / techqa) mapped to verbatim bge-code-v1 / Qwen3 query instructions
embed-text.tschunkEmbedText() — the text a code chunk is embedded as: Filepath: <path>, ---, the chunk. Payload content stays the plain chunk. EMBED_TEXT_FORMAT is stored as embed_format and is part of the unchanged-file check, so bumping it re-embeds every file
ranking.tsrankKey() — rank-time order for search_code: test files ×0.9 unless the query mentions tests; for a query naming identifiers (identifierTokens()), chunks defining one ×1.1 (×1.25 when the query is only that name) and files named after one ×1.05, and definitionCandidatesFilter() adds the chunks that define them to the candidates; every result ×(1 + 0.05·file_churn); the shown score stays the similarity. conventionalTestPaths() — where a file's tests sit by convention, which change_impact lists when no indexed test reaches the change and the project's test files are not recorded
file-churn.tsreadFileCommitCounts() (git log per file, relative to the project) and churnPercentiles() — each file's commit-count percentile in its project, rounded to 20 steps. The indexer writes it as file_churn after a project pass that wrote chunks (one payload update per step); no git history leaves it unset
query-cache.tsIn-memory LRU cache with TTL and group-level invalidation for search results
indexer-health.tsfetchIndexerHealth() — the indexer's /health (with the API key when set; never throws, an unreachable one is reachable: false), indexerUrlFromEnv() (PAPARATS_INDEXER_URL). Used by the analytics page and health_check, which reports the indexer's last run and each repository's status and error
qdrant-batch.tsupsertWithRetry() — batches of 128, each tried three times; for points that exist nowhere else (an arch or glossary reindex after its collection was dropped)
qdrant-errors.tsisMissingCollection() — tells a missing collection (nothing indexed yet) apart from a Qdrant failure; describeQdrantError() — names a connection failure (ECONNREFUSED, ...) behind Node's bare fetch failed
metrics.tsPrometheus metrics (@prometheus-io/client) with NoOpMetrics fallback. Opt-in via PAPARATS_METRICS=true
metadata.tsTag resolution (resolveTags()) + auto-detection from directory structure
metadata-db.tsSQLite store for git commits, tickets, each project's test files (test_files, paths only), symbol edges and the files their graph has not caught up with (graph_changes, kept until applyGraphChanges(), so a missed update is applied by the next one), each project's GRAPH_FORMAT (graph_formats), and per file the names its code uses that may be common (file_names: single lowercase words, so getNameUsage() counts every file using a name, linked or not); edges of a file or project are deleted by id range, not a LIKE scan
git-metadata.tsGit history extraction — commit mapping to chunks by diff hunk overlap
ticket-extractor.tsJira/GitHub/custom ticket reference parsing from commit messages
mcp-handler.tsMCP protocol (SDK 2) — three endpoints: coding (/mcp), support (/support/mcp) and knowledge (/knowledge/mcp, opt-in) with isolated tool sets and instructions. Stays on protocol revision 2025-11-25 with sessions: search_code hides what it returned earlier in a session, and on 2026-07-28 clients send nothing that tells sessions apart. delete_project deletes only on a yes through elicitation, and refuses a client that does not declare it
workflow-skills.tsloadWorkflowSkills() — the workflow prompts as a skills catalog (Skills over MCP, in memory, no files to copy into the image), attached in coding and support; workflowSkillText() renders a prompt as a SKILL.md, required arguments as <name>
knowledge-mode.tsKnowledge mode — parseKnowledgeModeEnv(), bearer auth (constant-time), 64 kB body limit guards mounted before the global parser, scope intersection
api-key-auth.tsOptional API key — parseApiKeysEnv() (PAPARATS_API_KEY, comma-separated, ≥ 16 characters; unset = open, a malformed key stops startup), apiKeyAuth() (bearer, or a basic-auth password for browser pages; mounted before the body parser; open paths /health and /knowledge/mcp, and the UI routes when PAPARATS_UI_BASIC_AUTH guards them), hasApiKey() (/health shows only its status without the key). The indexer mounts the same guard on /trigger and /metrics; the shared token helpers (tokenMatches(), constant-time) are used by the knowledge mode too

packages/indexer/src/

ModuleResponsibility
index.tsEntry point — wiring only: Express mini-server (POST /trigger, GET /health) + dual cron scheduler bootstrap (fast change-check + slow safety-net) + projects.yml hot reload, all driving IndexOrchestrator. Exposes its own GET /metrics on port 9877 when PAPARATS_METRICS=true — Prometheus must scrape both endpoints (server :9876/metrics + indexer :9877/metrics) to see indexing counters
config-loader.tsloadIndexerConfig(), tryLoadIndexerConfig() — parses projects.yml, merges per-repo overrides with defaults, returns RepoConfig[] + cron + cron_fast
repo-url.tsparseRepoSpec() — a remote entry: owner/repo (GitHub) or an https:// URL of any host (GitHub Enterprise, GitLab subgroups; fullName = host/path, clone folder host/group/...); SSH and credentials in the URL are refused
repo-manager.tsparseReposEnv(), cloneOrPull() using simple-git — clones are a managed cache: an existing one is re-pointed at the current URL and hard-reset to the remote default branch, re-cloned on any failure; credentials are masked in errors
orchestrator.tsIndexOrchestrator — runs index cycles, /trigger requests and hot-reload work through one per-repo lock; purges repos removed from (or moved within) projects.yml; persists a fingerprint only when indexing and the docs pass both succeeded
project-resolver.tsresolveRepoProject() — builds a raw config from .paparats.yml + projects.yml overrides and resolves it through the server's resolveProject; group precedence PAPARATS_GROUP > override > .paparats.yml
git-auth.tsgitAuthEnv() — GITHUB_TOKEN as an Authorization header scoped to https://github.com/ via GIT_CONFIG_* env, and each GIT_TOKENS host=token pair (parseGitTokens()) scoped to https://<host>/, applied once at startup; clone URLs never carry the token (libcurl 8.23 drops URL credentials mid-fetch → 401). createGit() — every git call goes through it: simple-git 4 strips ambient GIT_* env unless allowed by name
keyed-serializer.tsKeyedSerializer — one task at a time per key (repo), different keys concurrently
trigger-queue.tsTriggerQueue — merges full-cycle requests that arrive during a running cycle (repo sets union, force stays per repo)
scheduler.tsstartScheduler() — node-cron wrapper for scheduled index cycles
change-detector.tsGitDetector (remote ls-remote HEAD), MtimeDetector (file stat hash) — produce fingerprints used to decide whether to re-index
state-store.tsSQLite store of per-repo fingerprints (default /data/indexer-state.db); persisted between cron ticks
types.tsIndexerConfig, RepoConfig, RepoOverrides, IndexerFileConfig, RunStatus, HealthResponse

packages/embed/

FileResponsibility
DockerfileBuilds a llama.cpp llama-server + llama-swap image with bge-code-v1 + qwen3-embedding-0.6b GGUF pre-baked (~2.3 GB of models, a 2.5 GB download; CPU-only, zero-config startup). llama-swap serves on port 8080, lazy-loads models by name; models stay resident by default (EMBED_TTL=0), opt-in idle unload via EMBED_TTL

packages/cli/src/

ModuleResponsibility
docker-compose-generator.tsProgrammatic YAML generation — generateCompose() (qdrant and embed optional, server, indexer, local project mounts). examples/docker-compose/ holds its output for plain docker compose up (scripts/generate-compose-examples.js; a test keeps them equal)
local-urls.tslocalUrls() — server / indexer / Qdrant URLs from the ports in ~/.paparats/.env (what the compose publishes), overridden by PAPARATS_SERVER_URL / PAPARATS_INDEXER_URL / QDRANT_URL; every command's default. Also apiKey (PAPARATS_API_KEY, environment over the file) and authHeaders(), sent by ApiClient, the indexer calls and the MCP client wiring of install

Key patterns

  • Grammars: tree-sitter WASM grammars come from tree-sitter-wasms, except TypeScript, TSX and JavaScript, which ship in packages/server/grammars (newer builds; the old ones fail on & in JSX attribute strings). Both Dockerfiles copy that folder
  • AST-first chunking: indexer.chunkFile() parses once with tree-sitter, uses the AST for both chunking (chunkByAst) and symbol extraction (extractSymbolsForChunks), then deletes the tree. Falls back to regex Chunker for languages without a grammar
  • Chunk line numbers are 0-indexed throughout (chunker, AST chunker, symbol extractor, Qdrant payload). Text meant for people and agents (MCP tool output, paparats search) shows them 1-indexed, as editors and grep do (shownLine() in change-impact-report.ts); JSON from the HTTP API keeps the stored values
  • Qdrant operations use retryQdrant() with exponential backoff (3 retries)
  • Embedding cache: SQLite at ~/.paparats/cache/embeddings.db, Float32 vectors, LRU cleanup at 100k entries
  • CachedEmbeddingProvider wraps any EmbeddingProvider — all embedding calls go through cache
  • Query cache: in-memory LRU with TTL (default 5min, 1000 entries). searcher.invalidateGroupCache() drops a group's entries after the server's own writes: POST /api/index, POST /api/file-changed, POST /api/file-deleted, DELETE /api/project/:group/:name and the MCP delete_project tool. The indexer container writes to Qdrant directly, so its updates reach search once cached entries expire (TTL)
  • Prometheus metrics: opt-in via PAPARATS_METRICS=true. GET /metrics exposes counters (search, index), histograms (search/embedding duration), gauges (cache sizes, hit rates). NoOpMetrics fallback when disabled — zero overhead
  • Three MCP modes: coding (/mcp, /sse), support (/support/mcp, /support/sse) and knowledge (/knowledge/mcp only). Each mode has its own tool set and serverInstructions. Coding: search_code, get_chunk, find_usages, change_impact, module_map, health_check, list_projects, delete_project, search_docs, all arch_* tools and term_* tools. Support: search_code, get_chunk, find_usages, health_check, list_projects, search_docs, plus get_chunk_meta, search_changes, explain_feature, recent_changes, impact_analysis, module_map, get_document, the six analytics tools and term_search/term_list (no arch_*, no term_* writes — support is strictly read-only, enforced by a test over tool annotations). Knowledge: search_docs + get_document, nothing else (no resources, no prompts, no glossary). Tool sets defined by CODING_TOOLS/SUPPORT_TOOLS/KNOWLEDGE_TOOLS; createMcpServer(mode) registers only the relevant tools. node packages/server/dist/index.js --stdio serves the coding mode over stdin/stdout instead of HTTP (McpHandler.connectStdio(); all logging goes to stderr) — used by registry inspectors such as Glama that spawn the server
  • Knowledge mode: docs-only endpoint for consumers outside the trust boundary. Off unless PAPARATS_KNOWLEDGE_TOKENS + PAPARATS_KNOWLEDGE_AUDIENCE are both set (one alone refuses to start); optional PAPARATS_KNOWLEDGE_PROJECTS allowlist. Bearer auth + 64 kB body limit run before the global 50 MB parser; the handler refuses requests that skipped them. Stateless Streamable HTTP (fresh server + transport per POST, GET/DELETE → 405). Its ceiling/allowlist are intersected with PAPARATS_DOCS_AUDIENCE / PAPARATS_PROJECTS; internal is never allowed in its ceiling. Out-of-scope documents must read exactly like missing ones; backend errors are reported generically. Texts live in prompts.json under knowledgeInstructions / knowledgeTools
  • Docs audience labels: every docs chunk stores one audience. Resolved per document at index time: frontmatter audience: > docs.audience (.paparats.yml, or projects.yml repo/defaults, which wins over the repo file) > internal. Labels match ^[a-z0-9][a-z0-9_-]{0,63}$; invalid in config fails loading, invalid in frontmatter is logged and stored as internal (never the project default). Each docs pass rewrites every document (new doc_id), so label changes need no migration. get_document keys by (project, file), not doc_id, for that reason
  • Orchestration tools (explain_feature, recent_changes, impact_analysis): support-mode only. Compose search + metadata + edges in a single MCP call. Return structured markdown without code content. Use resolveChunkLocation() helper for payload extraction. Gracefully degrade when metadataStore is null (skip metadata sections, still return search results)
  • Server lib extraction: packages/server/src/lib.ts is the public library entry point (all re-exports). index.ts re-exports from lib.ts. Server's package.json exports map points to lib.js so importing @paparats/server doesn't execute the server bootstrap
  • Docker embed server: ibaz/paparats-embed — llama.cpp llama-server + llama-swap with bge-code-v1 + qwen3-embedding-0.6b GGUF pre-baked (~2.3 GB of models, a 2.5 GB download; CPU-only, both Apache-2.0). llama-swap serves on port 8080, routes by model name, lazy-loads on first request; models stay resident by default (EMBED_TTL=0 — llama-swap's unload/swap path can deadlock under load, see the swap: false group in the config), opt-in idle unload via EMBED_TTL. No Modelfile, no ollama create — models ready on container start. ~5–9× faster than Ollama on CPU
  • Docker Compose generator: packages/cli/src/docker-compose-generator.ts builds YAML programmatically with generateCompose(): Qdrant (unless external), the embed server (Docker embed mode with local models only), server and indexer. With a cloud embedding provider the prose layer (TEXT_EMBEDDING_*) goes to the same provider. The indexer keeps its state DB on the shared paparats_data volume (STATE_DB_PATH)
  • Install modes: paparats install = the Docker stack with the indexer, embed mode choice (--embed-mode native|docker), wires Cursor and Claude Code, fails when a service does not come up (waitForStack()). --mode support = client-only MCP config (no Docker). --embed-url skips the local embed server entirely (no binary check, no GGUF download). Native macOS embed mode installs via brew install llama.cpp mostlygeek/llama-swap/llama-swap (Metal-accelerated)
  • Indexer container: packages/indexer — separate Docker image that clones repos and indexes on a schedule. Uses Indexer class from @paparats/server as a library. HTTP trigger at POST /trigger, health at GET /health
  • Indexer config file: projects.yml mounted at /config/ in the container. Per-repo overrides (group, language, indexing.exclude, etc.) with global defaults section. Priority: indexer YAML overrides > .paparats.yml in repo > auto-detection, for the fields merged onto a repo's own file (group, docs.kind, docs.audience, indexing.*); a repo's .paparats.yml keeps its language and metadata. Falls back to REPOS env when no config file present. CONFIG_DIR env controls the lookup directory
  • Indexer change detection: two cron schedules run side by side. Fast CRON_FAST (default */10 * * * *) computes a fingerprint per repo and only invokes indexProject() when it differs from the last persisted value; slow CRON (default 0 */3 * * *) is the safety-net full pass. A forced run (/trigger with force) over a collection built with another embedding model drops the whole collection (dropCollectionIfModelChanged()) and queues a full cycle, so every repo of it is indexed again. Remote repos fingerprint via git ls-remote HEAD; bind-mounted local repos via mtime/size hash of the project's file set (same patterns/excludes as indexing). State persists in STATE_DB_PATH (default /data/indexer-state.db). The fingerprint is taken before the repo is pulled and persisted only when every file and the docs pass indexed without error; detector failures fall through to a defensive reindex. Repos removed from projects.yml are purged (code, metadata, docs) on hot reload. Set CHANGE_DETECTION=false to opt out

Testing

yarn test              # vitest
yarn typecheck         # tsc --noEmit
yarn bench run         # opt-in retrieval benchmark; needs Qdrant + embed server (docs/benchmarking.md)

Retrieval changes (ranking, chunking, models, prefixes) should come with a yarn bench compare diff against main.

Versioning

Releases are driven by Changesets in fixed mode — all four publishable packages (@paparats/shared, @paparats/cli, @paparats/server, @paparats/indexer) bump together. There is no yarn release command; never bump versions by hand.

Authoring a change: run yarn changeset in your PR, pick patch/minor/major, write a summary, commit the generated .changeset/<slug>.md.

Release flow:

  1. CI opens a release PR (.github/workflows/release.yml). On every push to main with pending .changeset/*.md files, changesets/action@v1 runs yarn run version and opens (or updates) a chore: release X.Y.Z PR. The version script chains: changeset version → scripts/sync-server-json.js (syncs server.json + root package.json from packages/cli/package.json) → scripts/aggregate-changelog.js (mirrors per-package entries into root CHANGELOG.md) → yarn install --no-immutable.
  2. Maintainer merges the release PR. No publish runs in CI — npm tokens were intentionally revoked.
  3. Maintainer publishes locally: yarn release:local (or --dry-run to preview). The script in scripts/release-local.sh verifies main is clean and up-to-date, no pending changesets, then builds, runs yarn changeset publish, pushes a vX.Y.Z tag and creates the GitHub Release from the version's root CHANGELOG.md section. The tag (not the release) triggers docker-publish.yml and publish-mcp.yml; the GitHub Release is what Glama's Auto-Release builds from.

Single source of truth for the bumped version: packages/cli/package.json. sync-server-json.js propagates it to root package.json and server.json. The aggregator merges the entries of all four packages/*/CHANGELOG.md (a changeset lands only in the changelogs of the packages it names, so no single file is complete), de-duplicates them, drops dependency-bump boilerplate and rewrites a marker-delimited block in the root CHANGELOG.md — idempotent, safe to re-run.

Docker

  • packages/server/Dockerfile — builds and runs the server (ibaz/paparats-server)
  • packages/indexer/Dockerfile — builds the indexer (ibaz/paparats-indexer)
  • packages/embed/Dockerfile — builds llama.cpp llama-server + llama-swap with pre-baked bge-code-v1 + qwen3-embedding-0.6b GGUF models (ibaz/paparats-embed)
  • examples/docker-compose/ — ready compose files (local models, Voyage) + projects.yml + .env.example for a plain docker compose up
  • packages/cli/src/docker-compose-generator.ts — generates docker-compose.yml at install time
  • Qdrant at :6333, MCP server at :9876, Indexer at :9877. The generated compose publishes Qdrant and the Docker embed server on 127.0.0.1 only (QDRANT_BIND / EMBED_BIND): they have no auth, and PAPARATS_API_KEY covers only the server and the indexer
  • Embed server (llama-swap on internal port 8080, mapped to host 18434 — not Ollama's 11434, so both can run): native mode via host.docker.internal:18434, Docker mode via http://embed:8080, external via --embed-url

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.