Extensions

Extensions let anyone ship a pack of TOML rules without forking tok0. They’re plain git repositories with .toml rule files at the top level. tok0 clones them into ~/.config/tok0/extensions/<name> and treats their rules as user-global with a third trust class.

Install

tok0 extensions install https://github.com/user/my-tok0-rules

The first time you install a given URL, tok0:

1. Clones the repo into ~/.config/tok0/extensions/<derived-name>.
2. Pins it to a specific commit hash.
3. Validates that every .toml is a parseable rule with at least one assertion.
4. Prompts you to trust the extension (Y/n).
5. Loads its rules on next dispatch.

If you decline trust, the clone stays on disk but the rules are inert. Re-trust later with tok0 extensions trust <name>.

Listing & inspecting

tok0 extensions list

Output:

NAME                  COMMIT     RULES   TRUSTED
acme-internal-tools   a1b2c3d    14      yes
foo-toolchain         9f8e7d6    23      no

tok0 extensions show acme-internal-tools

Prints the resolved rule files, their commit hashes, and any active overrides.

Updating

Extensions are version-pinned for safety. Update explicitly:

tok0 extensions update                    # all
tok0 extensions update acme-internal-tools

tok0 will fetch the latest commit, re-run validation, and re-prompt for trust only if the rule files changed. If only README/docs changed, the trust grant carries over.

Removing

tok0 extensions remove acme-internal-tools

Deletes the on-disk clone, invalidates any cached rules.

Building an extension

An extension repo is structured like:

my-tok0-rules/
├── README.md
├── LICENSE
├── tok0-extension.toml      # required manifest
├── rules/
│   ├── acme-cli.toml
│   ├── internal-build.toml
│   └── deploy-tool.toml
└── fixtures/
    ├── acme-cli.raw
    └── ...

tok0-extension.toml is the manifest:

[extension]
name = "acme-internal-tools"
description = "tok0 rules for ACME's internal build & deploy CLIs."
version = "1.0.0"
homepage = "https://github.com/acme/tok0-rules"
license = "MIT"

[compatibility]
# Minimum tok0 version required for this extension's rule schema.
tok0 = ">=0.4.0"

Every .toml under rules/ follows the standard TOML rule schema. Fixtures under fixtures/ are referenced by [[assertions]] blocks for CI on the extension’s own repo.

Trust levels recap

tok0 has three trust levels, each more restrictive:

1. Built-in rules (embedded in the binary) — no trust required. Vetted in CI.
2. User-global rules at ~/.config/tok0/filters/ — no trust prompt. You wrote them.
3. Extensions at ~/.config/tok0/extensions/ — trust-prompted on install + on update if rules changed.
4. Project-local rules at .tok0/filters/ — trust-prompted per project (tok0 trust .).

This is the same threat-model VS Code uses for workspace settings — see Trust & safety for the rationale.

Discovering extensions

There is no centralized registry yet. Discovery is via:

• The community-maintained list at EXTENSIONS.md.
• Searching GitHub for the tok0-extension topic.

We deliberately do not ship a “marketplace” — every extension you install runs against your shell output, and the trust burden is real.