Reference

Configuration

Tama has no required environment variables and no free-form settings file for a supported installation: setup choices are explicit actions in the app, and everything durable lives in known files with known schemas. This page maps that surface — where state lives, which environment variables the bundled scripts and runtime honor, and the few user-defaults keys the app itself keeps. Build- and release-time variables (signing identities, provisioning profiles, channels) are maintainer-only and tabled in operations.

#State Tama owns

Everything under ~/Library/Application Support/Tama:

Path	Content
`policy-bundles/index.json`	Imported inactive bundle identities: source path and digest, retained files and hashes (`ai.wisent.tama.policy-bundles.v1`)
`policy-bundles/bundles/<source-key>/`	Editable byte-for-byte policy files adopted from one source; never an active runtime by import alone
`hooks-runtime/releases/<release-id>/`	Content-addressed installed hook releases
`hooks-runtime/current`	Symlink to the active release, replaced atomically
`hooks-runtime/installed.json`	Installed identity: release id, checksum, versions, managed files, pinned Node (`ai.wisent.tama.installed-hook-release.v1`)
`hook-emergency-state.json`	Durable disabled flag (`ai.wisent.tama.hook-emergency-state.v1`)
`emergency-backup/manifest.json`	What emergency disable moved and emptied, recorded once
`emergency-backup/claude-settings.json`, `codex-hooks.json`	Original provider configs, restored on re-enable
`session-control/*.session.json`	Supervisor-owned live session records (`ai.wisent.tama.session-control.v2`)
`session-control/.override.json`, `.request.json`, `*.response.json`	Session overrides and the private request/response exchange

Never repair installed.json, current, or the emergency manifest by hand as a normal procedure. Policy bundle files are intentionally editable, but a locally changed imported file causes the next replacement to conflict rather than overwrite it (operations).

#Managed per-user files

Installation writes hook entrypoints only to documented per-user locations: ~/.shared-hooks for the structured registry and OMP adapter, ~/.claude/hooks and ~/.claude/settings.json, ~/.codex/hooks and ~/.codex/hooks.json, ~/.local/bin/tama-agent, the user-global Git dispatchers, and approved project .githooks entrypoints. Existing Git hooks are preserved as <name>.before-tama. The OMP adapter is registered through omp config set extensions.

#Script and runtime environment variables

Honored by the bundled installer (tama hooks install-release), the emergency switch (emergency_disable_hooks), and the generated launchers:

Variable	Read by	Purpose
`TAMA_HOME`	emergency switch	Target home directory; `$HOME` when it is not set
`TAMA_EMERGENCY_ACTION`	emergency switch	`disable` (when it is not set) or `enable`
`TAMA_HOOK_RELEASE_ROOT`	emergency switch	Release root; the `hooks-release` beside the script, else the one in `.build/Tama.app`
`TAMA_HOOK_INSTALLER`	emergency switch	Installer path; the release's own `bin/tama` when it is not set
`TAMA_OMP`	installer	The `omp` executable used to register the OMP adapter
`AGENT_HOOK_REGISTRY`	every Tama program and the OMP adapter	Registry path; `~/.shared-hooks/registry.json` when it is not set
`TAMA_CLEAN_DISABLED`	`tama violations clean`, `tama request violations/clean`	`1` disables the cleanup command entirely
`TAMA_HOOK_SOURCE_REVISION`, `TAMA_HOOK_SOURCE_DIRTY`	`tama hooks seal`	The source identity the build expects; a tree that differs is refused

Debug-only seams (TAMA_HOOK_ROOT for the catalog root, TAMA_TEST_IDENTITY for UI tests) are compiled out of distributed builds (operations).

#Application defaults

The app stores minimal preferences in user defaults for bundle id ai.wisent.tama.desktop:

tama.hasCompletedSetup — recorded only by the successful setup handoff; delete it to repeat guided setup without changing enforcement state (onboarding);
the first-use journey's progress, stored under the tama.onboarding.v1 namespace; the journey's transport reads its token from the TAMA_STADO_INTEGRATION_TOKEN environment key, and a bundled journey definition is the fallback.

Authentication state is not configuration: the Wisent session lives in the macOS Keychain through Wisent Auth, and Tama does not duplicate it in preferences (integrations).