Skip to content
TCAFTask-Contract AI Development Framework
TCAF 0.3.3

Select an adapter

Choose the TCAF transport that matches the actual host without changing scope, authority or core behavior.

Content: completeWorkflow: verified

An adapter defines how a TCAF Run Envelope reaches an AI host and what direct target access that host can provide.

It does not define the task, expand permissions or replace the Task Contract. The same developer-controlled authorization model applies across every adapter.

Selection order

When adapter selection is automatic, TCAF evaluates sources in this order:

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

The current registry default is generic-cli.

You can record a preference during installation:

python install.py --adapter codex

You can also override the adapter for one operation:

tcaf task --target <project-path> --request <bounded-request> --adapter cline

Use an explicit override when testing or when automatic detection cannot represent the real host. Do not use it to claim capabilities the host does not have.

Codex

Adapter ID:

codex

Current transport:

native

Status:

verified

The Codex adapter supports direct target access and direct editing within the permissions and target surface declared by the run.

Use it when the globally installed Codex integration can bind the active project as the single target and receive the Universal Run Protocol natively.

The public operations remain:

tcaf bootstrap
tcaf adopt
tcaf task
tcaf run

A native integration does not authorize Codex to bypass the review gate, edit unrelated files or perform Git operations automatically.

Cline

Adapter ID:

cline

Current transport:

manual-envelope

Status:

verified-with-limitations

The bounded Cline procedure is verified, but native runner-to-Cline invocation is not yet verified.

Current procedure:

  1. run the relevant tcaf operation outside Cline with --adapter cline;
  2. start a new Cline task;
  3. paste the generated Run Envelope unchanged;
  4. append exactly one transport marker:
TCAF CLINE STEP: INSPECT
TCAF CLINE STEP: WRITE <repository-relative-path>
TCAF CLINE STEP: VALIDATE

INSPECT and VALIDATE are read-only. WRITE authorizes at most one write operation to the named file and one write confirmation in that Cline task.

The marker may narrow the envelope. It may not expand target, scope, permissions or output.

Use a new Cline task for each write and review the actual file before continuing. Terminal commands are not used by default; the agent should report one to three DEVELOPER_RUN commands or manual checks instead.

Generic CLI

Adapter ID:

generic-cli

Current transport:

stdout

Status:

framework-aligned

This adapter prints the Run Envelope for a command-line host or another integration that can consume standard output.

The registry declares direct target access but no direct edit access. The receiving tool must not pretend that output transport alone grants file-writing capability.

Use this adapter when:

  • the host can reliably bind the target;
  • the envelope can be transferred without modification;
  • implementation or checks can be performed through a separately controlled mechanism;
  • the developer can review every consequential transition.

Generic chat

Adapter ID:

generic-chat

Current transport:

host-resource

Status:

framework-aligned

The registry does not assume direct target or edit access.

Generic chat is appropriate only when the host can provide persistent access to the required framework instructions and bind the exact target evidence for the session. An ordinary conversation that relies only on previous chat memory is not sufficient for reliable TCAF execution.

Use generic chat primarily for:

  • analysis based on explicitly supplied evidence;
  • preparing a Task Contract for later execution;
  • reviewing an envelope or result;
  • producing commands and procedures for the developer.

Do not claim direct repository inspection or file modification when the host has not provided those resources.

Adapter selection does not select the model’s authority

Every adapter must preserve:

  • exactly one target;
  • the allowed edit surface;
  • developer review gates;
  • preservation-first behavior;
  • explicit outcome and evidence reporting;
  • separation of implementation from commit, push and other Git operations.

A more capable host can perform more of the authorized work directly. It does not receive a wider authorization boundary.

Verify the active selection

Run:

tcaf doctor

The output reports the adapter selected by automatic resolution.

For machine-readable output:

tcaf doctor --format json

Change adapters deliberately

Changing adapter is appropriate when the actual execution host changes. It should not be used to avoid a limitation by pretending the limitation is absent.

Examples:

  • moving from Cline manual-envelope to Codex native invocation changes transport but not the Task Contract;
  • moving from a direct-edit host to generic chat requires the workflow to return procedures instead of claiming edits;
  • a future native Cline bridge should remain planned or unverified until it passes dedicated acceptance testing.

Read the dedicated Codex and Cline pages before relying on adapter-specific behavior.