codesamplex

module

v0.1.0 Latest Latest Go to latest Published: Aug 13, 2026 License: Apache-2.0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/r2cuerdame/codesamplex

Links

Open Source Insights

README ¶

CodeSampleX

Stop solving the same code twice.

Languages: English · 한국어 · 日本語 · 简体中文 · Español · Français · Deutsch · Português (BR) · Русский

CodeSampleX is a local-first distributed reasoning cache for coding LLMs. Instead of every agent on Earth re-deriving how a public library works — and re-hitting the same version incompatibilities — CodeSampleX collects anonymous compatibility Evidence from real development environments and serves verified minimal Samples with the exact delta between a known-good answer and your project.

Website & Compatibility Explorer: https://codesamplex.dev
One question your LLM stops re-answering: does axios.post actually work on axios 1.12 + Node 22 + pnpm + Windows 11 — and if not, at which stage does it break?
Works with Claude Code, Codex, Gemini CLI, OpenCode — and any MCP client (Cursor, Windsurf, Cline, Zed, VS Code).

Install

Windows (PowerShell):

irm https://codesamplex.dev/install.ps1 | iex

macOS / Linux:

curl -fsSL https://codesamplex.dev/install.sh | sh

One binary, one question. csx init shows the community contract and asks a single choice — JOIN COMMUNITY or LOCAL ONLY. Everything else (daemon, MCP registration for Claude Code / Codex / Gemini CLI / OpenCode, agent rules) is automatic.

For scripted or CI setups: csx init --community --yes --no-agents does config + identity only and writes nothing outside CSX_HOME; agent config paths otherwise honor CSX_AGENT_HOME when you need them somewhere other than your OS user home.

The contract

You get                              You contribute
✓ Public compatibility knowledge     ✓ Public package/version usage
✓ Verified code answers              ✓ Public API/symbol usage when detectable
✓ Local agent integration            ✓ Build/typecheck/test result
✓ Public sample cache                ✓ Sanitized failure fingerprints

Never shared automatically
✕ Source code        ✕ Repository/project name   ✕ File names or paths
✕ Source snippets    ✕ Secrets or env variables  ✕ Private packages
✕ Raw compiler/runtime logs

This is not hidden telemetry — it is the protocol. Community peers are consumers and producers. Local-only mode never sends anything. The privacy preview in csx ui shows the exact payloads before they leave your machine.

How it works

you build/test through csx (or your agent does)
→ local analysis: public packages, lockfile-resolved versions, symbols, environment
→ raw errors sanitized locally into fingerprints (paths/names/secrets stripped)
→ anonymous evidence batches → Compatibility Graph on codesamplex.dev
→ your LLM asks CSX first: nearest verified Sample + environment delta
→ it reasons about the DELTA, not the whole problem

Four layers, kept honestly separate:

Layer	What it is	Trust
Evidence Network	anonymous package/version/symbol/env/stage/result facts	weak→strong, class-labeled
Compatibility Graph	aggregated probabilistic map per environment (incl. execution context: Node/Chrome/Safari/Electron/…)	derived view
Sample Pool	user-approved, clean-room, content-addressed minimal projects	contract-verified, cross-verified
Agent Delivery	MCP/CLI: nearest sample + delta + known failures	graded EXACT→NO_SAFE_MATCH

A project compiling is never presented as a symbol working. Unknown causes stay UNKNOWN. A wrong HIT is worse than a MISS — NO_SAFE_MATCH is a feature.

Agent integration (MCP)

Configured automatically by csx init: Claude Code · Codex · Gemini CLI · OpenCode.

Any other MCP client — Cursor, Windsurf, Cline, Zed, VS Code — works too; csx is a standard stdio MCP server:

{"mcpServers": {"csx": {"command": "csx", "args": ["mcp"]}}}

Model-agnostic: the same compatibility evidence serves Claude, GPT and Codex, Gemini, Llama — any model that can call an MCP tool.

Tools: search_known_solution, get_sample, explain_compatibility, run_observed_command, report_sample_adoption, propose_public_sample, list_local_hits, get_local_stats. Publishing a sample is deliberately not an MCP capability — it requires your explicit CLI approval after a full preview.

csx run -- pnpm build      # observed build → evidence
csx search "axios multipart upload"
csx sample propose --goal "upload a file with axios"
csx ui                     # dashboard + privacy preview

Ecosystems (Public v1)

Node/TypeScript (npm, pnpm, yarn — reference), Python (pip, uv), Go, Rust/Cargo. Honest capability matrix: docs/adapters.md — no adapter claims runtime symbol instrumentation in v1, and symbol resolution confidence is always labeled (EXACT/PROBABLE/UNKNOWN).

Architecture

Single Go binary (csx: daemon + CLI + MCP + peer node + verifier) and a small server (csx-server: PostgreSQL + server-rendered explorer behind Caddy). Samples are content-addressed (sha256) and distributed local-cache-first → peers → main seeder. Downloaded samples never run on your host directly — resolve with --ignore-scripts, compile and contract run network-off in a sandbox, receipts are ed25519-signed. See goal.md (product spec), docs/execution-context.md, docs/operations.md.

Building from source

go build ./cmd/csx && go build ./cmd/csx-server
go test ./...

License

Code: Apache-2.0. Published samples default to MIT-0.

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
adapters Package adapters wires every ecosystem adapter into one registry.	Package adapters wires every ecosystem adapter into one registry.
goadapter Package goadapter implements the scanner.Adapter contract for the "golang" ecosystem: go.mod-resolved dependencies, go/parser-based symbol usage extraction, and go command classification.	Package goadapter implements the scanner.Adapter contract for the "golang" ecosystem: go.mod-resolved dependencies, go/parser-based symbol usage extraction, and go command classification.
node Package node implements the npm-ecosystem scanner adapter: lockfile-resolved dependency scanning (package-lock.json v2/v3, pnpm-lock.yaml v9, classic yarn.lock), static import/symbol extraction for TS/JS sources, command classification, and environment hints.	Package node implements the npm-ecosystem scanner adapter: lockfile-resolved dependency scanning (package-lock.json v2/v3, pnpm-lock.yaml v9, classic yarn.lock), static import/symbol extraction for TS/JS sources, command classification, and environment hints.
python Package python implements the scanner.Adapter for the "pypi" ecosystem: lockfile-resolved versions from uv.lock / poetry.lock / requirements.txt pins, import-based symbol scanning, and command classification.	Package python implements the scanner.Adapter for the "pypi" ecosystem: lockfile-resolved versions from uv.lock / poetry.lock / requirements.txt pins, import-based symbol scanning, and command classification.
rust Package rust implements the scanner.Adapter for the "cargo" ecosystem.	Package rust implements the scanner.Adapter for the "cargo" ecosystem.
cmd
csx command Command csx is the CodeSampleX local client: evidence-recording command wrapper today; daemon, MCP server, and sample tooling in later waves.	Command csx is the CodeSampleX local client: evidence-recording command wrapper today; daemon, MCP server, and sample tooling in later waves.
csx-server command Command csx-server is the CodeSampleX central server: HTTP API, website and PostgreSQL-backed evidence/sample registry (plan contract C9).	Command csx-server is the CodeSampleX central server: HTTP API, website and PostgreSQL-backed evidence/sample registry (plan contract C9).
internal
cli Package cli is the csx command dispatcher (contract C9).	Package cli is the csx command dispatcher (contract C9).
compatibility Package compatibility computes confidence and aggregation views from evidence.	Package compatibility computes confidence and aggregation views from evidence.
config Package config manages CSX_HOME and $CSX_HOME/config.json (goal.md §5.4 — every setting has a working default; the only choice the user ever has to make is the mode).	Package config manages CSX_HOME and $CSX_HOME/config.json (goal.md §5.4 — every setting has a working default; the only choice the user ever has to make is the mode).
daemon Package daemon implements the csx local daemon (plan P4.1/P4.4): a localhost-only HTTP API plus a same-mux named-pipe/unix-socket listener, a single-instance lock, background maintenance tickers (evidence upload, shard warm, cache budget, peer announce, idle verification), and the §12.5 dashboard at /ui.	Package daemon implements the csx local daemon (plan P4.1/P4.4): a localhost-only HTTP API plus a same-mux named-pipe/unix-socket listener, a single-instance lock, background maintenance tickers (evidence upload, shard warm, cache budget, peer announce, idle verification), and the §12.5 dashboard at /ui.
domain Package domain holds CodeSampleX's core types and pure logic.	Package domain holds CodeSampleX's core types and pure logic.
environment Package environment builds EnvironmentFingerprints from the host and adapter-provided hints.	Package environment builds EnvironmentFingerprints from the host and adapter-provided hints.
evidence Package evidence implements the local evidence loop behind `csx run` (goal.md §8.3, contract C14): scan the project, run the user's command, record aggregate observations for PUBLIC packages only, and drain them into anonymous wire batches.	Package evidence implements the local evidence loop behind `csx run` (goal.md §8.3, contract C14): scan the project, run the user's command, record aggregate observations for PUBLIC packages only, and drain them into anonymous wire batches.
httpapi Package httpapi implements the csx-server /v1 HTTP API (plan contract C5).	Package httpapi implements the csx-server /v1 HTTP API (plan contract C5).
identity Package identity holds the peer's ed25519 keypair and the secret seed behind the rotating pseudonymous evidence IDs (goal.md §8.6, plan C10).	Package identity holds the peer's ed25519 keypair and the secret seed behind the rotating pseudonymous evidence IDs (goal.md §8.6, plan C10).
mcp Package mcp implements the csx MCP stdio server (plan contract C8, goal.md §12.4): newline-delimited JSON-RPC 2.0 over a provided reader and writer, exposing the eight local tools coding agents consume.	Package mcp implements the csx MCP stdio server (plan contract C8, goal.md §12.4): newline-delimited JSON-RPC 2.0 over a provided reader and writer, exposing the eight local tools coding agents consume.
peer Package peer implements the local P2P node (plan C15, goal.md §15): announcing cached sample artifacts to the central tracker, serving them to other peers over HTTP, and fetching artifacts with the fallback order local CAS → tracker peers → server → MISS.	Package peer implements the local P2P node (plan C15, goal.md §15): announcing cached sample artifacts to the central tracker, serving them to other peers over HTTP, and fetching artifacts with the fallback order local CAS → tracker peers → server → MISS.
registry Package registry checks whether packages exist on their public registry.	Package registry checks whether packages exist on their public registry.
samples Package samples implements the local half of the public-sample pipeline (goal.md §9, plan C13): canonical content-addressed artifacts, leakage scanning, sanitized clean-room specs, and the create workflow.	Package samples implements the local half of the public-sample pipeline (goal.md §9, plan C13): canonical content-addressed artifacts, leakage scanning, sanitized clean-room specs, and the create workflow.
sandbox Package sandbox runs sample verification stages in isolation (goal.md §16).	Package sandbox runs sample verification stages in isolation (goal.md §16).
sanitizer Package sanitizer turns raw tool output into privacy-safe error templates (goal.md §8.5, contract C11).	Package sanitizer turns raw tool output into privacy-safe error templates (goal.md §8.5, contract C11).
scanner Package scanner defines the ecosystem adapter contract and orchestrates project scanning.	Package scanner defines the ecosystem adapter contract and orchestrates project scanning.
search Package search implements the local search engine over the SQLite store: candidate collection from cached samples, compatibility shards, and the FTS index; C7 score fusion; environment grading with the always-sensitive execution-context axis (docs/execution-context.md §5); and §11.5 delta construction.	Package search implements the local search engine over the SQLite store: candidate collection from cached samples, compatibility shards, and the FTS index; C7 score fusion; environment grading with the always-sensitive execution-context axis (docs/execution-context.md §5); and §11.5 delta construction.
serverstore Package serverstore is the csx-server persistence layer: a Store interface over PostgreSQL (plan contract C4) plus the pure ingest logic — batch validation and delta-merge dedup semantics — which unit-tests without a database.	Package serverstore is the csx-server persistence layer: a Store interface over PostgreSQL (plan contract C4) plus the pure ingest logic — batch validation and delta-merge dedup semantics — which unit-tests without a database.
storage Package storage holds cross-cutting policy over the local stores: the SQLite metadata DB (localdb) and the content-addressed artifact cache (cas).	Package storage holds cross-cutting policy over the local stores: the SQLite metadata DB (localdb) and the content-addressed artifact cache (cas).
storage/blob Package blob abstracts sample-artifact storage (goal.md §14.2, §15.4).	Package blob abstracts sample-artifact storage (goal.md §14.2, §15.4).
storage/cas Package cas implements a content-addressed store on the local filesystem.	Package cas implements a content-addressed store on the local filesystem.
storage/localdb Package localdb is the local SQLite store behind the csx daemon and CLI ($CSX_HOME/csx.db).	Package localdb is the local SQLite store behind the csx daemon and CLI ($CSX_HOME/csx.db).
verifier Package verifier turns sandbox stage runs into signed verification receipts (goal.md §7.7, §16) and implements the cross-verification client that claims jobs from the server, re-verifies artifacts locally, and posts receipts back.	Package verifier turns sandbox stage runs into signed verification receipts (goal.md §7.7, §16) and implements the cross-verification client that claims jobs from the server, re-verifies artifacts locally, and posts receipts back.
web Package web is the server-rendered public website: landing page, Compatibility Explorer, sample/seeder pages, install scripts and SEO surface (plan P6.1–P6.3, goal.md §14.5/§14.6).	Package web is the server-rendered public website: landing page, Compatibility Explorer, sample/seeder pages, install scripts and SEO surface (plan P6.1–P6.3, goal.md §14.5/§14.6).
web/i18n Package i18n is the website message catalog for the nine Public v1 locales (plan Global Constraints + P6.3).	Package i18n is the website message catalog for the nine Public v1 locales (plan Global Constraints + P6.3).