# Global Executables

**A public cross-ecosystem dataset of executable names, continuously collected from package ecosystems and exposed to AI agents via MCP.**

`global-executables` builds and maintains a machine-readable index of executable names found across software package ecosystems.

It is designed to answer a deceptively simple question:

> **Is this executable name already in use?**

This is especially useful when naming new CLI tools. Searching package names, repositories, or the web is not sufficient because a package name and the executable it installs are not necessarily the same.

Global Executables collects executable-level information, publishes it as structured data on GitHub, and makes the dataset directly accessible to AI agents through MCP.

<!-- mcp-name: io.github.asopitech-labs/global-executables -->

## Quick start: use it from your AI agent

The MCP server is read-only and needs no API key and no local dataset. It fetches
only the files a query needs from the public `dictionary` branch and caches them
in your user cache directory (revalidated with `ETag`; cached files keep working
offline). It requires [uv](https://docs.astral.sh/uv/) (`uvx`) or Docker.

**Claude Desktop** (`claude_desktop_config.json`) and **Cursor** (`~/.cursor/mcp.json`
or a project's `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "global-executables": {
      "command": "uvx",
      "args": ["global-executables", "mcp"]
    }
  }
}
```

**Claude Code**:

```sh
claude mcp add global-executables -- uvx global-executables mcp
```

**VS Code** (`.vscode/mcp.json`):

```json
{
  "servers": {
    "global-executables": {
      "type": "stdio",
      "command": "uvx",
      "args": ["global-executables", "mcp"]
    }
  }
}
```

**Docker** (any client; replace the `command`/`args` above):

```json
{
  "command": "docker",
  "args": ["run", "-i", "--rm", "ghcr.io/asopitech-labs/global-executables-mcp:latest"]
}
```

Then ask, for example, *"Is the command name `envc` already taken?"*. The agent calls
`check_executables`; `found: true` is a collision, while `status: "unknown"` means
"not in the current index", not "free", because some sources are partial.

| Variable | Effect |
|---|---|
| `GLOBAL_EXECUTABLES_DATASET_ROOT` | use a local checkout of the `dictionary` branch instead of HTTPS |
| `GLOBAL_EXECUTABLES_CACHE_DIR` | cache location (default `~/.cache/global-executables`, `~/Library/Caches/global-executables`, or `%LOCALAPPDATA%\global-executables\Cache`) |
| `GLOBAL_EXECUTABLES_OFFLINE=1` | serve only cached files, never touch the network |

`uvx global-executables mcp --help` lists the same options as flags. The package is
published to PyPI from release 1.3.0; see [`docs/MCP.md`](docs/MCP.md) for HTTP transport
and running from a source checkout.

---

## Why Global Executables?

Suppose you are designing a new CLI and considering:

```text
envc
evcr
evpk
envcp
```

Before recommending or adopting one of these names, you want to know whether it is already installed as a command by an existing package.

The relevant relationship is:

```text
executable
    ↓
provider
    ↓
package
    ↓
ecosystem
```

rather than simply:

```text
package name
```

Global Executables creates this missing cross-ecosystem index.

---

## Goals

Global Executables aims to provide:

- a public dataset of real-world executable names;
- cross-ecosystem coverage;
- traceable provenance for every collected executable;
- reproducible dataset generation;
- Git-friendly structured data;
- machine-readable indexes for efficient lookup;
- historical tracking of executable names;
- MCP access for AI agents;
- explicit dataset coverage and freshness information.

The dataset itself is the primary artifact.

The MCP server is an access layer over that public data, not the source of truth.

Try the live [Index Playground](https://asopitech-labs.github.io/global-executables/)
to inspect crawl progress and run read-only `check`, `search`, `similar`,
`coverage`, and `assess` queries directly in a browser. The playground is a
static GitHub Pages client over the public JSON dataset; no query data is sent
to a third-party API.

The program and published data have independent lifecycles. Program source,
schemas, tests, and documentation live on `main`; the generated JSON dictionary
lives on the orphan `dictionary` branch. The stable raw-data base URL is:

```text
https://raw.githubusercontent.com/asopitech-labs/global-executables/dictionary
```

See [the dictionary branch migration note](docs/DICTIONARY_BRANCH.md) for the
branch contract, local setup, and the `main` URL cutover.

Go development follows the
[JetBrains Modern Go Guidelines](https://github.com/JetBrains/go-modern-guidelines).
See the [Go crawler development and build contract](docs/GO_CRAWLER_DEVELOPMENT.md)
for the versioned review, build, test, security, and release workflow.

---

## Architecture

```text
Package ecosystems
        │
        ├── Debian / Ubuntu
        ├── Arch Linux
        ├── Homebrew
        ├── npm
        ├── PyPI
        ├── crates.io
        ├── Go modules
        ├── RubyGems
        ├── Packagist / Composer
        ├── ConanCenter
        ├── vcpkg
        ├── xmake-repo
        └── others
                │
                ▼
          GitHub Actions (`main`)
                │
       collect / normalize
                │
                ▼
  `dictionary` branch dataset
                │
        ┌───────┴────────┐
        │                │
        ▼                ▼
   GitHub / raw        MCP Server
      data                │
                          ▼
                     AI agents
```

GitHub Actions periodically collects upstream package information, normalizes executable records, regenerates indexes, validates the dataset, and publishes the resulting files.

---

## Data Model

The canonical unit is an **executable name**.

Each executable is represented by a structured file containing its known providers.

Conceptually:

```json
{
  "command": "example",
  "providers": [
    {
      "ecosystem": "example-ecosystem",
      "package": "example-package",
      "version": "1.0.0",
      "repository": "https://example.com/repository",
      "source": "example-source",
      "confidence": "direct"
    }
  ],
  "first_seen": "2026-08-14",
  "last_seen": "2026-08-14"
}
```

A single executable may have multiple providers across multiple ecosystems.

---

## Repository Layout

The `dictionary` branch contains only published artifacts:

```text
dictionary/
├── data/
│   ├── executables/
│   │   ├── en/
│   │   │   ├── envc.json
│   │   │   └── envcp.json
│   │   └── gi/
│   │       └── git.json
│   │
│   ├── indexes/
│   │   ├── prefix/
│   │   ├── length/
│   │   ├── ecosystem/
│   │   └── trigram/
│   │
│   ├── metadata.json
│   └── history.json
└── reports/
    ├── production-crawl.json
    └── production-refresh.json
```

The `main` branch separately keeps `fixtures/`, `schema/`, `src/`, `tools/`,
`tests/`, `docs/`, `playground/`, and `.github/workflows/`; it does not track
the generated paths above. The canonical dataset uses ordinary structured
files rather than requiring a database server.

Derived indexes are reproducible and may be regenerated from the canonical executable records.

---

## Lookup

Exact lookup maps directly to the repository structure.

For example:

```text
envcp
  ↓
prefix: en
  ↓
data/executables/en/envcp.json
```

This allows consumers to retrieve individual records without downloading or querying a centralized database.

Derived indexes support broader queries such as:

- prefix;
- executable length;
- ecosystem;
- similar names.

---

## Data Sources

Collectors are independent for each ecosystem.

Potential sources include:

| Ecosystem | Executable evidence |
|---|---|
| Debian / Ubuntu | package file contents |
| Arch Linux | package files database |
| Homebrew | formula/package contents |
| npm | ecosyste.ms critical population; npm registry `bin` metadata |
| PyPI | distribution entry points / `console_scripts` |
| crates.io | Rust binary targets |
| Go modules | `package main` directories in module archives |
| RubyGems | gemspec `executables` metadata |
| Packagist / Composer | `composer.json` `bin` declarations in Packagist metadata |
| ConanCenter | `bin/` contents of the built package, read from `conanmanifest.txt` |
| vcpkg | `vcpkg_copy_tools(TOOL_NAMES ...)` declarations in `portfile.cmake` |
| xmake-repo | `set_kind("binary")` packages, whose command name is inferred |
| others | ecosystem-specific executable metadata |

C and C++ have no single registry, so three recipe repositories are read instead, and
each contributes the strongest evidence it actually carries. vcpkg names the tools a
port installs, because naming them is what installs them. ConanCenter recipes never
name their executables, so the built package's own file list is read. xmake declares
that a package is a binary but never what the binary is called, so its records are
marked `inferred` and no xmake record should be read as a declaration. None of the
three is `exhaustive`: a vcpkg port can install a command without declaring it, a
ConanCenter recipe nobody has built states nothing about installed files, and an xmake
package can install a command under another name.

The project records how each executable was discovered rather than treating all observations as equally authoritative.

---

## Confidence

Records may carry a confidence level describing how an executable name was established.

For example:

```text
direct
filesystem
inferred
```

**direct** means the executable is explicitly declared by package metadata.

**filesystem** means it was observed in package contents as an installed executable.

**inferred** means it was derived indirectly and should be treated with lower confidence.

Consumers can use this information when deciding whether a potential naming collision is significant.

---

## MCP

Global Executables is intended to be directly usable by AI agents.

The MCP interface provides structured access to the public dataset.

The current read-only tools are:

### `check_executable`

Check one proposed executable name.

```json
{
  "name": "envc"
}
```

### `check_executables`

Check multiple candidates in one request.

```json
{
  "names": [
    "envc",
    "evcr",
    "evpk",
    "envcp"
  ]
}
```

### `get_executable`

Return providers and provenance for a known executable.

### `search_executables`

Search by prefix, length, ecosystem, or other indexed attributes.

### `search_similar_executables`

Find potentially confusing existing names using lexical similarity.

### `get_coverage`

Return dataset sources, freshness, and current coverage.

### `assess_executable` / `assess_executables`

Return optional freshness, activity, popularity, and collision-risk
assessments while preserving the factual existence result and provider
evidence. All lookup, search, and assessment tools accept an optional
multi-axis `scope` filter such as `distribution`, `language`, or `registry`.

---

## Agent Workflow

A naming agent should use Global Executables **before presenting CLI name recommendations**.

Recommended workflow:

```text
Generate candidate names internally
            │
            ▼
     check_executables
            │
            ▼
 Separate `found:true` collisions from `found:false` observations
            │
            ▼
 search_similar_executables for not-found candidates
            │
            ▼
 Remove confusing candidates
            │
            ▼
 Present surviving names
```

Rejected candidates do not need to be surfaced to the user.

The purpose of the service is to make collision checking part of the agent's normal reasoning workflow rather than a manual follow-up task.

---

## Result Semantics

Absence from the dataset does **not** prove that an executable name has never been used.

Results therefore distinguish the factual observation from confidence in
absence:

```text
collision
clear_in_index
unknown
```

For example:

```json
{
  "name": "evpk",
  "found": false,
  "status": "unknown",
  "absence": {
    "status": "not_found_in_current_index",
    "confidence": "insufficient_coverage",
    "searched_sources": [
      "arch",
      "crates",
      "debian",
      "go",
      "homebrew",
      "npm",
      "pypi",
      "ubuntu"
    ]
  },
  "coverage_scope": "unknown",
  "checked_sources": [
    "arch",
    "crates",
    "debian",
    "go",
    "homebrew",
    "npm",
    "pypi",
    "ubuntu"
  ],
  "coverage": {
    "arch": {
      "status": "success",
      "coverage_kind": "exhaustive",
      "records": 1647
    },
    "npm": {
      "status": "success",
      "coverage_kind": "exhaustive",
      "scope": "ecosyste.ms critical npm population covering 80% of downloads or dependent repositories",
      "records": 127
    }
  },
  "snapshot": "2026-08-15"
}
```

`found:false` means that the name was not found in the current index. `unknown`
means the available coverage is insufficient to make an exhaustive absence
claim; it does not mean that the query was unavailable. `clear_in_index` is
returned only when the queried snapshot is explicitly exhaustive.

The `coverage` object reports the per-source collection status, coverage kind,
and record count. The example shows two representative sources; the live
response includes all sources in the snapshot (and may also include each
source's input path).

It does not mean that the name is legally or globally guaranteed to be available.

---

## Coverage and Freshness

Dataset metadata records:

- generation timestamp;
- snapshot identifier;
- number of indexed executables;
- enabled collectors;
- freshness of each upstream source;
- collector status.

This information is available both as structured data and through MCP.

Agents can therefore evaluate the strength of a lookup result instead of treating the index as complete by assumption.

---

## GitHub as the Source of Truth

Global Executables deliberately keeps its canonical data in the repository's
orphan `dictionary` branch.

This provides:

- transparent provenance;
- reviewable changes;
- reproducible generation;
- historical tracking;
- forks and mirrors;
- direct raw-file access;
- independence from the availability of the MCP service.

If the hosted MCP endpoint disappears, the dataset remains usable.

A third party can build another MCP server, search engine, CLI, or analysis tool directly from the repository.

---

## Automation

GitHub Actions maintains the dataset.

The general pipeline is:

```text
scheduled / manual trigger
          │
          ▼
     run collectors
          │
          ▼
       normalize
          │
          ▼
        merge
          │
          ▼
 generate executable files
          │
          ▼
    generate indexes
          │
          ▼
       validate
          │
          ▼
        publish
```

Collectors should contain the actual collection logic independently of GitHub Actions so they can also be executed and tested locally.

`act` may be used during development to run compatible GitHub Actions workflows locally.

---

## What Global Executables Is Not

Global Executables is not:

- a trademark search service;
- a brand-name availability service;
- a package registry;
- a package manager;
- a vulnerability database;
- a software catalog;
- proof that an unused name is legally available.

It answers a narrower question:

> **What executable names are known to be used across the software ecosystems covered by the dataset?**

Trademark, company-name, domain, repository-name, and broader web searches remain separate checks.

---

## Potential Uses

Beyond CLI naming, the dataset can support:

- automated CLI naming assistants;
- repository CI policies;
- package publishing checks;
- ecosystem collision analysis;
- executable discovery;
- historical studies of CLI ecosystems;
- IDE and developer-tool integrations;
- AI-agent preflight checks.

---

## Project Principle

**Public data first. MCP second.**

The value of Global Executables is not tied to a particular server implementation.

The durable asset is the openly available, reproducible, cross-ecosystem executable-name dataset.

MCP makes that dataset immediately useful to agents.

## Current implementation

The schemas, deterministic builder, production OS index collector, derived
prefix/length/ecosystem/trigram and logical-scope indexes, collector parsers,
read-only local/HTTP MCP server, assessment API, bounded fixture freshness
scenarios, and CI checks are implemented in this repository. Coverage is measured
against each declared source population. npm is exhaustive for the finite ecosyste.ms
critical population; the all-registry npm long tail is tracked separately. See
[`docs/DATA_MODEL.md`](docs/DATA_MODEL.md) for exact naming, sharding, alias, and
history rules and [`docs/OPERATIONS.md`](docs/OPERATIONS.md) for reproducible
commands, freshness-state scenarios, and honest measured coverage limitations.

For zero-setup use, see [Quick start](#quick-start-use-it-from-your-ai-agent). To
query a pinned snapshot without network access, install the program, materialize
the published branch in a separate worktree, and point the server at it:

```sh
python -m pip install -e .
git fetch origin dictionary
git worktree add .dictionary origin/dictionary
global-executables-mcp --root . --dataset-root .dictionary
```

Use `--transport streamable-http` for remote access. Both modes expose
`check_executable`, `check_executables`, `get_executable`,
`search_executables`, `search_similar_executables`, `get_coverage`,
`assess_executable`, and `assess_executables`; neither
mode exposes writes. Data is reusable under the repository license by reading
the canonical JSON directly from the `dictionary` branch, without running MCP.
See [`docs/MCP.md`](docs/MCP.md) for local client configuration, the remote
endpoint, resources, health visibility, and the survivor-only agent workflow.

The manual fixture workflow exercises a bounded incremental freshness scan. It
rotates through immutable test partitions, persists a cursor and last successful
observations on the `freshness-data` branch, and publishes a machine-readable test
report. It is not production freshness or a full dataset refresh. Coverage is
snapshot-specific and reported by `get_coverage`. The
published snapshot contains production OS/Homebrew coverage, exhaustive bounded
registry populations, and partial PyPI/Go coverage; it is **not** full global ecosystem
coverage, so consumers must preserve
`clear_in_index`/`unknown` semantics and the accompanying coverage caveat.

Registry artifact inspection is separately resumable. CI refreshes the finite npm
critical catalog and crawls it to 100% daily, while dedicated local containers advance
PyPI and Go module cursors and publish checkpoints to `artifact-data`; these local
containers are temporary completion boosters and stop at 100%. After a source reaches
100%, a six-hour GitHub Actions matrix cycles through every indexed package with a
persisted refresh cursor. Successful results replace stale package observations,
including commands removed by a newer release. CI also performs
one daily crates.io dump change check and downloads the dump only when it changed.
The CI refresher dispatches a dictionary rebuild only when normalized observations
changed and redeploys Pages whenever it publishes crawl progress. Go modules, npm, PyPI, RubyGems, and Packagist use the transactional Go runtime;
their bbolt state commits cursor, retry verdicts, and observations together. CI
regenerates npm's bounded population; PyPI, RubyGems, and Packagist reuse sampled
catalogs, while Go extends its index. A source is promoted to `exhaustive` only after
its declared catalog and required artifact inspections complete successfully.

Successful collection does not by itself permit a negative collision claim.
Every valid query returns a factual `found` observation. Fixture, smoke, and
partial snapshots return insufficient absence confidence for absent names;
`clear_in_index` requires metadata explicitly marking the complete queried
snapshot exhaustive. Derived search indexes are integrity-pinned in metadata
and are used directly by prefix, length, ecosystem, and similarity queries.

For a clean-checkout setup, client configuration, expected responses, and
verification steps, see [`docs/SETUP.md`](docs/SETUP.md).

Issue completion and release evidence follow [`docs/RELEASE.md`](docs/RELEASE.md);
implementation claims alone do not close work.