CodeSampleX

# CodeSampleX

[![Release](https://img.shields.io/github/v/release/r2cuerdame/CodeSampleX)](https://github.com/r2cuerdame/CodeSampleX/releases/latest)
[![Downloads](https://img.shields.io/github/downloads/r2cuerdame/CodeSampleX/total)](https://github.com/r2cuerdame/CodeSampleX/releases)
[![Code License](https://img.shields.io/github/license/r2cuerdame/CodeSampleX?label=code)](https://github.com/r2cuerdame/CodeSampleX/blob/main/LICENSE)
[![Data License](https://img.shields.io/badge/data-CDLA--Permissive--2.0-blue)](DATA_TERMS.md)
[![Release pipeline](https://img.shields.io/github/actions/workflow/status/r2cuerdame/CodeSampleX/release.yml?label=release)](https://github.com/r2cuerdame/CodeSampleX/actions/workflows/release.yml)
[![Go](https://img.shields.io/github/go-mod/go-version/r2cuerdame/CodeSampleX)](https://github.com/r2cuerdame/CodeSampleX/blob/main/go.mod)

> **Tested. Not guessed.**

<p align="center">
  <img src="internal/web/static/inspector-hero-v1.webp" alt="CodeSampleX compatibility inspector" width="560">
</p>

**Languages:** [English](README.md) · [한국어](docs/i18n/README.ko.md) · [日本語](docs/i18n/README.ja.md) · [简体中文](docs/i18n/README.zh-CN.md) · [Español](docs/i18n/README.es.md) · [Français](docs/i18n/README.fr.md) · [Deutsch](docs/i18n/README.de.md) · [Português (BR)](docs/i18n/README.pt-BR.md) · [Русский](docs/i18n/README.ru.md)

CodeSampleX is an **open compatibility testing network** for developer libraries, runtimes and toolchains. It does not summarize documentation and it does not collect anecdotes. It records what real builds actually did, in environments recorded rather than assumed — then shows you where things worked, where they broke, and in which environment.

Two things are the asset, and a third is a bonus:

- **Evidence** — real builds on real developer machines, with the environment, stage, structured termination, and secret-safe normalized failure fingerprint. Missing or legacy failure detail is shown as an Evidence gap, never invented as a cause. It arrives automatically wherever csx is installed, so it reaches platforms no container lane can: no container reproduces a macOS host — Docker on a Mac runs a Linux VM, which is a different machine wearing the same laptop — npm publishes no Windows image, and the long tail of musl, ARM, corporate base images and actually-installed runtime versions is unbounded. This is the only thing that can fill the map.
- **Findings** — the contradictions we detected in that evidence: what a competent developer or model expects, measured against what happened. These are ours to stand behind, and they are what a model most often gets wrong, because they are exactly what the documentation does not say.
- **Samples** — runnable code we write and verify ourselves. A bonus, deliberately: a container farm can never cover the space, so a verified sample is a confidence tier above the evidence, never the condition for having an answer at all.

Which is why a miss is not empty. When nothing has been proven for your case the grade stays `NO_SAFE_MATCH` — and the recorded observations come back with it, as recorded.

- Compatibility map: **https://codesamplex.dev**
- The question it answers: *does it run there?* — this API, on this version, on this OS, under this runtime.
- The answer it gives: *here is what happened, and here is where it ran.* Reporters use rotating peer buckets; separate first-party activity analytics use a stable pseudonymous client ID, never a name or IP identity. See [analytics semantics](docs/anonymous-analytics.md).

## What ships today

CodeSampleX is no longer just a search command. The shipped product now exposes several surfaces, all backed by the same evidence model:

| Surface | Current role |
|---|---|
| [Compatibility](https://codesamplex.dev/compatibility) | browse recorded compatibility by package, version, symbol and environment |
| [Dependencies](https://codesamplex.dev/dependencies) | reverse dependency atlas: which recorded parent releases pulled a dependency release; an edge is **not** a compatibility verdict |
| [Gaps](https://codesamplex.dev/gaps) | completeness census across Sample / Evidence / Dependency, replacing the old website Wanted ranking |
| [Findings](https://codesamplex.dev/findings) | measured contradictions and version/environment boundaries backed by reproducible samples |
| [Features](https://codesamplex.dev/features) | zero-install REST quick start, the REST / MCP / CLI capability matrix, the MCP tool contracts and [skill.md](https://codesamplex.dev/skill.md) |
| [Samples](https://codesamplex.dev/samples) · [Adapters](https://codesamplex.dev/adapters) · [Stats](https://codesamplex.dev/stats) | verified artifacts, ecosystem capability matrix, and public network rollups |

The CLI is the canonical local interface. `csx help` is generated from the commands in the binary; this table is pinned to it by a test so a new command cannot silently outgrow the README.

<!-- BEGIN:CSX-CLI-SURFACE -->
| Command | What it does |
|---|---|
| `config` | read or change local settings |
| `daemon` | run, start, stop, or inspect the background sync daemon |
| `doctor` | diagnose the local install; `--fix` repairs safe CSX-owned state and verifies again |
| `hook` | enable, disable, inspect, or self-test the automatic build-failure lookup installed into supported coding agents |
| `init` | choose community/local-only mode, configure agents, warm the first cache, and start background sync |
| `login` | sign in with GitHub when you want attributed sample publishing |
| `mcp` | run the stdio MCP server used by agent clients |
| `mcp-config` | print JSON/TOML/path configuration for MCP clients |
| `run` | run a command and record sanitized evidence for public dependencies |
| `sample` | propose, create, preview, verify, publish, remove, list, or review pending clean-room samples |
| `sample-worker` | operate the private authoring work/session handoff lane |
| `scan` | detect public dependencies without running a build |
| `search` | search verified samples graded against the target environment |
| `stats` | show local cache, queue, hit, and adoption counters |
| `sync` | warm compatibility shards and flush queued community uploads (`--uploads-only` when needed) |
| `ui` | open the local dashboard and privacy preview |
| `update` | securely check, install, inspect, or roll back signed updates |
| `version` | print the installed csx version |
| `worker` | contribute Docker-isolated cross/matrix verification work |
<!-- END:CSX-CLI-SURFACE -->

The network also installs an optional **build-failure hook** into supported coding agents. When an agent's shell build fails, the hook classifies the failing build step, sanitizes the error locally, searches CodeSampleX, and stays silent on a miss or unrelated command. `csx hook status` shows what is installed; `csx hook check` proves the registered hook path with a throwaway failing build.

## No install needed to read the network

CodeSampleX exposes a public REST surface for agents, browsers and scripts. Every answer the site renders is a plain HTTPS request away — no key, no account, no client library, readable from any origin. Install the CLI only when you want local execution capture, the automatic failed-build hook, publishing or worker capabilities.

One request, real production JSON — copy it as it is:

```bash
curl 'https://codesamplex.dev/v2/search?package=pkg:npm/axios&symbol=axios.post&os=linux&runtime=node&runtimeVersion=22'
```

The answer carries a `grade`, and every result names which environment dimensions matched (`exact[]`) and which did not (`different[]`). A miss is spelled `grade: "NO_SAFE_MATCH"` — a real answer, not a failure to answer. A generic web-capable agent reads the whole contract from [`https://codesamplex.dev/skill.md`](https://codesamplex.dev/skill.md); [docs/rest.md](docs/rest.md) is the same quick start for a person.

The three doors compared. Every mark is checked against the router and the command list by a test, and the [Features](https://codesamplex.dev/features) page draws the same table:

<!-- BEGIN:CSX-SURFACE-MATRIX -->
| Capability | Web REST (no install) | MCP | CLI installed |
|---|:--|:--|:--|
| Search verified samples, graded against an environment | ✅ | ✅ | ✅ |
| Compatibility lookup by package, version, symbol and environment | ✅ | ✅ | ⚠️ csx search grades against the synced shards; there is no explain command |
| Read one sample's manifest, receipts and files | ✅ | ✅ | ⚠️ through csx search --json; no dedicated sample read command |
| Read the findings collection | ✅ | ❌ web and REST only | ❌ web and REST only |
| Read gaps, wanted and public stats | ✅ | ❌ | ⚠️ csx stats shows local counters only |
| Use from a browser, a cloud agent or a script | ✅ | ⚠️ the agent's MCP host must run csx locally | ❌ a local binary |
| Zero-install use | ✅ | ⚠️ the MCP server is the csx binary; the client host must have csx installed | ❌ |
| Detect the local project and environment automatically | ❌ | ⚠️ only what the local csx behind the MCP host can see | ✅ |
| Run the real local build or test | ❌ | ⚠️ run_observed_command runs it through the local csx | ✅ |
| Capture sanitized, structured execution evidence | ❌ | ⚠️ only through the local csx the MCP host runs | ✅ |
| File an unsigned execution footprint | ✅ | ❌ files correlated adoption evidence instead | ❌ files correlated adoption evidence instead |
| Automatic failed-build lookup hook | ❌ | ❌ | ✅ |
| Background sync and offline cache | ❌ | ❌ | ✅ |
| Privacy preview before anything is uploaded | ❌ | ❌ | ✅ |
| Publish a verified sample | ❌ | ❌ deliberately no publish tool | ✅ a person confirms at the CLI |
| Worker and matrix verification | ❌ | ❌ | ✅ |
| Signed verification receipts (ed25519, from the worker) | ❌ | ❌ | ✅ |
<!-- END:CSX-SURFACE-MATRIX -->

**REST reads the network. The CLI lets the network observe reality.** MCP is an adapter on the CLI: `csx mcp` is the csx binary itself, so an MCP