Install TCAF

TCAF is installed once per computer as a versioned runtime. It is not copied into every project and it should not be added as a second workspace root beside the software you are developing.

This separation keeps framework instructions independent from project evidence and prevents framework files from being mistaken for target code.

Prerequisites

Before installing, verify that you have:

• Python 3 available as python or an equivalent command for your environment;
• a local copy of the TCAF release repository;
• permission to write to the user-level installation and binary directories;
• the intended adapter choice, or permission to let TCAF select automatically.

From the root of the TCAF release, run:

python install.py

The installer validates the release before copying it. An invalid release is not installed.

Select an adapter during installation

Automatic selection is the default:

python install.py --adapter auto

You can record a specific adapter as the active preference:

python install.py --adapter codex
python install.py --adapter cline
python install.py --adapter generic-cli
python install.py --adapter generic-chat

The adapter does not change the framework’s core authorization model. It changes how the Run Envelope reaches the host tool and what direct access that host can provide.

At version 0.3.3, native Codex transport and Cline through the documented manual-envelope procedure are the verified paths. Generic adapters are represented by the framework but have not yet received the same acceptance coverage.

Read Select an adapter before choosing a non-default value.

Default installation locations

Unless you override them, the installer uses user-level paths.

On Linux and other Unix-like systems:

Runtime home: ~/.local/share/tcaf
Command:      ~/.local/bin/tcaf

If XDG_DATA_HOME is set, the runtime home is placed under that directory instead.

On macOS:

Runtime home: ~/Library/Application Support/tcaf
Command:      ~/.local/bin/tcaf

On Windows, TCAF uses the user-local application data directory and the user Python scripts directory.

You can override the locations explicitly:

python install.py --home <runtime-home> --bin-dir <command-directory>

Expected installer output

A successful installation reports:

• the installed TCAF version;
• the active versioned runtime path;
• the generated tcaf launcher path;
• any required PATH action;
• tcaf doctor as the next check.

For example, the runtime is stored under a version-specific directory rather than replacing the entire installation home:

<runtime-home>/versions/0.3.3

This permits multiple installed versions and explicit activation.

Add the command directory to PATH when required

If the installer reports a PATH action, add its command directory to your shell configuration and start a new terminal session.

On a typical Linux installation the directory is:

export PATH="$HOME/.local/bin:$PATH"

Persist the change in the shell configuration appropriate to your environment rather than relying only on the current terminal.

Confirm that the launcher is visible:

tcaf version

Verify the installation

Run:

tcaf doctor

A valid installation should report PASS and identify the framework version, runtime root, selected adapter and installation state.

Continue to Run tcaf doctor for interpretation and troubleshooting.

Reinstalling the same version

The installer refuses to overwrite an already installed version by default.

Use --replace only for an intentional reinstall of the same version:

python install.py --replace

Do not use --replace merely to hide an unexplained installation problem. Inspect the current active version and run tcaf doctor first.

Install once, initialize each project separately

Installation prepares the runtime on the computer. It does not adopt or bootstrap any project.

For each project, choose one initial workflow:

tcaf bootstrap --target <new-target> --request <starting-request>
tcaf adopt --target <existing-project>

After that, normal development proceeds through bounded tasks.

Safety boundary

The installed framework should remain outside the target repository. Do not:

• copy the framework modules into ordinary application directories;
• add the framework repository as a second editor workspace root;
• commit the installed runtime into a project;
• treat framework templates as current project evidence without adoption or bootstrap.

The project contains its own canonical evidence. The installed runtime supplies the operating rules that interpret it.