Skip to content
TCAFTask-Contract AI Development Framework
TCAF 0.3.3

Run tcaf doctor

Validate the active TCAF runtime and inspect its version, root, adapter and installation state.

Content: completeWorkflow: verified

Run tcaf doctor immediately after installation and whenever the active runtime, adapter selection or framework files may have changed.

tcaf doctor

The command validates the active framework runtime and reports the environment TCAF will use for subsequent operations.

What doctor checks

The current implementation reports:

  • whether framework validation passed;
  • the active framework version;
  • the framework root resolved by the launcher;
  • the adapter selected through automatic adapter resolution;
  • whether the command is running from an installed launcher;
  • the active installed version and the list of available installed versions;
  • validation errors, warnings and issue details.

doctor validates the framework runtime. It does not validate the canonical documentation of a target project.

To validate a project as well, use:

tcaf validate --target <project-path>

Expected text output

A healthy runtime begins with:

PASS
Errors: 0  Warnings: 0

A failure begins with FAIL and lists each issue with its level, code, message and relevant path when available.

The command exits with a non-zero status when framework validation fails, so it can also be used by scripts or CI checks.

JSON output

For machine-readable diagnostics, run:

tcaf doctor --format json

The JSON result includes the same framework, adapter, installation and issue data without the human-oriented text formatting.

Use JSON output when another tool must inspect the result. Use normal text output for direct developer verification.

How the adapter is selected

doctor requests automatic adapter resolution. The registry evaluates adapter inputs in this order:

  1. an adapter ID supplied by the host integration;
  2. the TCAF_ADAPTER environment variable;
  3. environment detection;
  4. the registry default.

The reported adapter is therefore the adapter TCAF would currently choose without an explicit per-command override.

Read Select an adapter if the result is unexpected.

Common failure categories

The tcaf command is not found

The launcher directory is probably not on PATH, or the shell session was opened before the PATH configuration changed.

Confirm the installer’s command location and start a new terminal after updating the shell configuration.

The framework root is unexpected

The launcher may point to a different installation home or active version than the one you intended to use.

Inspect:

tcaf version
tcaf versions

Then activate the intended installed version explicitly if necessary.

Validation reports missing or inconsistent files

Do not bypass the result by continuing with a task. The active runtime may be incomplete, manually modified or inconsistent with its registries and manifests.

Reinstall the intended release deliberately, using --replace only when you understand which installed version is being replaced.

The adapter is not the one you expected

Check for:

  • an adapter selected by the host integration;
  • a TCAF_ADAPTER environment variable;
  • environment variables used by adapter detection;
  • the adapter recorded during installation;
  • an explicit --adapter override on the operation you intend to run.

Do not change the adapter merely to make the diagnostic look familiar. Choose the adapter that matches the actual host and verified transport.

What doctor does not prove

A PASS result confirms that the current framework runtime is internally valid. It does not prove that:

  • a particular target project has adopted TCAF correctly;
  • a model will follow every instruction;
  • a tool adapter has access to the intended target;
  • project-specific commands will pass;
  • every workflow is verified for the current model and host combination.

Those guarantees require target validation, bounded execution, evidence and developer review.

After installation:

tcaf doctor
tcaf version
tcaf validate

Before work on an existing project:

tcaf validate --target <project-path>

If target validation fails because the project has not yet adopted TCAF, use the adoption workflow rather than creating project documents manually from memory.