Docs / The toolkit

Plugins

Field Kit is one small core plus eight shipped plugins. Add only the tools you need. This page is the manager reference: list, add, remove, and update, where installs come from, what a missing tool looks like, and how to write a plugin of your own.

One core, tools you add

The fieldkit package carries what every tool shares: the CLI shell, table IO, PII scanning, report rendering, and the local web hub. Each tool is its own package named fieldkit-<tool> with its own dependencies, so a machine that only needs scrub never downloads the rest. Adding a tool is one command, and removing it is just as clean:

fieldkit plugin list
fieldkit plugin add xray scrub
fieldkit plugin update
fieldkit plugin remove scrub

The manager

plugin list

Shows every registry tool with its status, and points at the next add. Pass --json for machine-readable output.

fieldkit plugin list

                 Fieldkit tools
┏━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ tool     ┃ status    ┃ what it does                     ┃
┡━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ xray     │ installed │ Profile any table in seconds     │
│ scrub    │ available │ Find and mask PII before sharing │
│ mimic    │ available │ Generate realistic fake datasets │
│ datadiff │ available │ Explain why two tables disagree  │
│ debrief  │ available │ Turn field notes into reports    │
│ tell     │ available │ Inspect a draft's writing patterns, locally │
│ netwatch │ available │ Observe agent network access     │
│ awcp     │ available │ Check AI workload specs locally  │
└──────────┴───────────┴──────────────────────────────────┘
add one with: fieldkit plugin add scrub

fieldkit plugin list --json

{
  "plugins": [
    {
      "name": "xray",
      "package": "fieldkit-xray",
      "summary": "Profile any table in seconds",
      "status": "installed"
    },
    (six more entries)
  ]
}

plugin add

Takes one or more tool names and installs their packages into the same environment the core runs from. Extras ride along per tool. A wheelhouse directory selects local Field Kit wheels; other dependencies may still be retrieved from a package index:

fieldkit plugin add xray scrub
fieldkit plugin add tell --extra ml
fieldkit plugin add xray --wheelhouse ./dist

plugin remove and plugin update

plugin remove uninstalls the named tool packages; the core and anything a tool wrote, like your debrief log, stay put. plugin update reinstalls at the newest version, defaults to everything installed when you name nothing, and accepts the same --source and --wheelhouse options as add.

fieldkit plugin remove scrub
fieldkit plugin update
fieldkit plugin update xray --wheelhouse ./dist

When a tool is missing

Running a registry tool you have not added never dumps a Python traceback. The CLI tells you what it is and how to get it, then exits with status 2 so scripts fail loudly instead of half-running:

$ fieldkit xray
'xray' is a Fieldkit tool that isn't installed yet.
  fieldkit plugin add xray

Where plugins install from

plugin add builds one pip requirement per tool and installs it into the running environment, using uv when it is available. The source is picked in this order unless you force one:

The hub dims what you have not added

fieldkit serve starts the local web hub on loopback. It prefers port 8765 and picks a free port if that one is taken; the command prints the URL. Tools you have installed are live cards with drag-and-drop. Registry tools you have not added stay on the board, dimmed, with their exact fieldkit plugin add command printed on the card, so whoever is driving the browser knows what to ask for. Nothing about the page needs a rebuild; the hub reads the environment on startup.

Working from the repo

A dev checkout is a uv workspace, so one command installs the core and all eight tools editable, which is why the worked examples across these docs use the uv run prefix:

uv sync
uv run fieldkit plugin list

Write your own

A new tool is a new package under plugins/fieldkit-<name> that exposes a typer app in the fieldkit.plugins entry-point group, plus one registry line in the core. Expose a module in the fieldkit.web group and the hub mounts its web page too. Plugins import shared table IO and PII scanning from the core and never import each other. Any installed package with the entry point shows up in fieldkit plugin list, and packages from outside the registry are labeled third-party. The AGENTS.md file in the repository spells out the full contract.

Next steps

Pick your first tool from the docs index, or start where most engagements start: xray, for the file nobody can explain.