Tama documentation

Policy you can inspect,
operate, and recover.

Everything Tama owns: core concepts, every desktop screen, CLI and configuration contracts, release integrity, exact failures, and end-to-end walkthroughs.

Start with the quick start →Open the runbook

Start here

3 topics

What is Tama

What is Tama, and what is the mental model for reading everything else in these docs? Tama is the local control surface for coding-agent policy hooks on one Mac: a sealed catalog of approved hooks, a per-user runtime that enforces them in live agent sessions, and one desktop application that can prove which policy is loaded and recover when a hook blocks necessary work. The whole product is three moving parts — a release that declares, a runtime that enforces, and an operator surface that verifies and overrides.

Quick start

How do you go from nothing to one supervised agent session whose policy state Tama can prove? This page is the one happy path: verify an exact release, open the app, install local enforcement, and watch one session report matching identities. Full prerequisites, every failure, reset, and uninstall live in onboarding.

Onboarding

A new Wisent developer verifies and opens an exact Tama release, signs in, inspects the bundled policy without changing the machine, explicitly installs local enforcement, and sees one supervised agent session reported as kernel-gated with matching hook release identity.

Concepts

8 topics

Hook

What is the atom of Tama policy? A hook: one approved command bound to one or more agent events, with a human record of what it does, why it exists, and what it touches. Hooks are approved and shipped as a set — one hook release — never individually.

Hook release

What exactly is the unit of hook-policy deployment on a machine? A hook release: an immutable, content-addressed directory tree carrying the registry, every approved hook source, the sealed Rust backend, and a manifest whose releaseId is the SHA-256 digest of the tree itself. Nothing smaller deploys — no single hook, no patch — and nothing mutates in place.

Registry

Where is the single declaration of what runs, when, and why? In shared-hooks/registry.json at the release root — one JSON document that both the runtime executes from and the human audits from. Everything the desktop shows about hooks derives from it.

Seal and integrity

What makes a Tama hook release tamper-evident, and which checks actually stand between a modified tree and a running session? One digest definition, computed in one place, enforced at three moments.

Posture

What single answer does Tama give to "is this machine enforcing the policy it claims to enforce"? Posture: the joined comparison of three release identities plus the live enforcement signals, ordered by severity. It is a derived judgment, not a stored state — nothing on disk says "posture"; every element of it is readable independently.

Capability

What authorizes a supervised session to do something its hooks would otherwise refuse? A capability: a bounded, session-bound grant record that the session's runtime holds and Tama can only read. Tama displays capabilities; it never issues, extends, or revokes one — the Session screen says so on the screen itself.

Session-scoped enable

How does Tama change what runs in a live agent session — and why can it only ever make policy stronger there? Through one narrow mutation: enable a hook, or every hook, in exactly one session, applied not by Tama but by that session's own supervisor. There is no per-session disable, by contract (core-contracts).

Emergency disable

When a hook blocks work that genuinely must proceed, what is the recovery — and what does it cost? One confirmed, operator-owned action that bypasses every Tama-managed dispatcher on the machine, records exactly what it moved, and stays visible until a verified re-enable restores everything. It is deliberately the only way to weaken policy: sessions can enable, only operators can disable, and only globally (enforcement-control).

Desktop app

10 topics

Desktop application

The SwiftUI app is the canonical human interface: one window, one sidebar of destinations grouped by the decision the operator came to make, one screen at a time. Authorization removes destinations instead of rewriting them — a signed-out or under-privileged operator sees fewer rows, never dead ones.

Setup and the first-use journey

How does a fresh install become a machine whose setup Tama calls complete? There is no separate setup gate: since the change titled Keep Tama navigation available during setup, an authorized operator gets the full window immediately, and guided first use runs alongside as a quiet journey. The end-to-end operator path is quick-start; every prerequisite and failure is in onboarding.

Posture screen

The headline screen: is this machine enforcing the policy it claims, and what was the last thing policy refused? Posture joins the three release identities with the live enforcement signals and hosts the machine's most destructive action. The underlying judgment is concepts/posture.

Hooks screen

The approved catalog and the per-hook decision that goes with it: what a policy does, why it exists, which events it gates, and whether the live session in front of you has it enabled. Three zones — facets, table, inspector. The catalog itself is read-only here; the sealed registry model is hook-model.

Session screen

What is one supervised agent session actually allowed to do right now? The capability document, the tool grants, the loaded release, the liveness contract, and every recent decision — for the one session selected in the rail. This is also the only screen that mutates a session, and both of its mutations point in the enabling direction (concepts/session-enable).

Violations screen

Findings in the repository under repair, and the one irreversible verb. Scan is read-only and replays the release's real pre-write hook; Repair hands the working tree to one headless external agent behind a confirmed dialog and trusts only the final rescan. The engine is the sealed CLI's find-violations / clean (cli), reached through the loopback backend's streaming endpoints.

Justifications screen

The register of recorded exceptions, and whether each one still holds. Justification-gated hooks (type: requires_justification) demand a recorded human reason in a local registry file instead of blocking outright (hook-model); this screen reads those registries and judges every record against its requirement. Nothing here is red unless a registry cannot be read at all: an incomplete record is amber — evidence to finish, not an outage to fix.

Coverage screen

Which runtime carries which hook, as the registry declares it. The screen answers "is Codex actually covered on this machine" without a terminal — and is explicit that these are declared mappings, not live execution evidence, because the data says so in every row: the rail footer reads Evidence / Registry-declared mappings, not live execution, and each provider's own evidence sentence — captured live from the sealed release — is Registry-declared mappings; not live execution evidence.

Install plan screen

Where an install would write, scope by scope, and the MCP snippet that goes with it — so an operator approving a privileged install can see which files it would touch first. The plan is read-only: the screen states target paths and performs none of the changes. The command behind it is the sealed CLI's install-plan (cli), served as a plain GET of /v1/install-plan on the loopback backend.

Settings screen

The local installation and the build behind it: install the runtime, register the privileged backend, and — the screen's one destructive owner — deactivate everything. Installation is a decision an operator makes once; it lives here rather than beside the posture verdicts.

Reference

15 topics

Architecture

What does Tama own, what does it deliberately not own, and how does a policy decision travel from a sealed release to a refused tool call? This page is the structural map; per-noun depth lives in concepts/ and the operational contracts in core-contracts.

Core contracts

Initial state: any app launch, including no account or installed runtime. Input: signed app resources and an explicit choice to inspect. Success: decoded catalog, validation result, hook count, checksum, and build identity are visible without starting session monitoring. Failure: the UI reports an incomplete/corrupt bundle and does not mutate local policy.

CLI

This page documents the sealed Rust CLI the desktop release bundles at Tama.app/Contents/Resources/hooks-release/bin/tama-cli, built and signed by Scripts/build-app.sh from the same hook source tree as the release itself, so the binary the app runs is the one the build sealed. Its usage line reads tama <command>. Runnable, commented examples for the public outcomes live in ../examples/; the contract behind each command is in core-contracts.

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.

Enforcement control

Tama has exactly two enforcement mutations, and they point in opposite directions on purpose. Enabling is narrow: one hook, or all hooks, in one live session, applied by that session's own supervisor. Disabling is global: one confirmed emergency action that bypasses every managed dispatcher on the machine and leaves durable evidence until re-enable succeeds. There is no per-session disable — agent-session controls never weaken policy, and disabling enforcement remains an operator-owned action outside the session (core-contracts).

Hook model

What exactly is a hook, and where is it declared? A hook is one approved policy command bound to one or more agent events, described by a registry that ships sealed inside every release. This page is the registry model; sealing and installation are in hook-releases, and the runtime controls are in enforcement-control.

Adaptive enforcement

Tama observes hook outcomes, learns only from structurally complete runs and causally identified owner corrections, and may automatically weaken only an etiquette hook from enforce to warn. It never disables a hook and never edits hook source.

Hook management

Tama stores hook source and structured configuration, exposes the CLI and MCP catalogue, and carries the runtime paths that enforce approved policy. The repository is never runtime state: logs, transcripts, credentials, shell profiles, local settings, caches, and machine-specific state stay outside it.

Hook releases

How does an approved hook tree become the runtime a session loads, and how does Tama know nobody changed it in between? Through one identity: a hook release is a directory whose name and manifest are the SHA-256 digest of its own contents, checked when it is sealed, checked before it is installed, and checked again after it lands. Hook policy evolves separately from the desktop app, so the two have separate identities — the product version policy is in releases.

Integration contracts

Integrations extend Tama's local policy-control core. They do not own product state, and an unavailable optional integration must not prevent catalog inspection or emergency recovery.

Tama operational model

| Resource | Authority | Writer | Retention and removal | |---|---|---|---| | Signed Tama.app | Published release artifact | Release operator | Replace only through an explicit upgrade; remove with the app | | Bundled catalog | Signed app bundle | Release build | Immutable for the life of that app version | | Installed hook release | ~/Library/Application Support/Tama/hooks-runtime/releases/<release-id> | Tama installer | Retained while referenced by current or installed.json; remove during uninstall | | Current hook release | hooks-runtime/current symlink | Tama installer transaction | Atomically replaced; previous ID recorded in installed.json | | Emergency state | hook-emergency-state.json and emergency-backup/ | Emergency controller | Removed only after successful re-enable or explicit uninstall | | Session records | session-control/*.session.json | Agent supervisor | Stale records are ignored and removed; directory mode 0700 | | Session overrides | session-control/*.override.json | Agent supervisor after a validated Tama request | Atomic files, mode 0600; removed during reset/uninstall | | Session-control requests | session-control/*.request.json and matching response | Tama and agent supervisor | Private, single-use exchange; both sides remove completed or abandoned files | | Wisent session | macOS Keychain | Wisent Auth | Removed by sign-out or Keychain administration | | Privileged daemon and filter preferences | macOS ServiceManagement and NetworkExtension | Explicit setup action | Removed by the uninstall procedure |

Release and versioning

Tama uses Semantic Versioning. The exact signed Git tag v<SemVer> is the sole canonical version for a distributable desktop release. Release scripts derive the app, Network Extension, artifact, provenance, and release-note version from that tag. Untagged development builds retain source metadata but are never supported or published.

Runbook

Something refused — which sentence are you holding, what does it mean, and what do you check next? Every heading below is an exact string from this repository's sources or a state you can reproduce; each entry says where the sentence comes from, what it is really telling you, and the first read-only command to run. Attribution tooling is in scripts; the executed evidence for the integrity entries is in the two walkthroughs.

Scripts reference

Every executable under Scripts/, with its arguments, environment, output, and exit behavior. Three of them ship inside the app bundle and run on operator machines (install_hook_release.py, emergency_disable_hooks, and the sealed release they act on); the rest are maintainer tools that run only in a checkout. The sealed CLI itself is documented in cli; the integrity model these scripts implement is concepts/seal.

Testing and qualification contract

The testing stage is incomplete. The repository has four deterministic Swift tests, but no supported preview, current clean-device onboarding evidence, canonical-example execution record, signed release build result, upgrade/rollback pair, or controlled credentialed/device/destructive suite. No test or validation command was executed while creating this document.

Walkthroughs

3 topics

Walkthrough: inspect runtime status

What is installed, what is loaded, and what would an emergency re-enable hit? Three read-only answers: the sessions the runtime is supervising right now, the integrity of every installed release tree, and the second integrity gate an install would pass through. Every command below was executed on 2026-08-24 against the release sealed as 35204a12… and a scratch home (TAMA_HOME/--home overrides), so nothing operator-owned was touched; outputs are pasted verbatim with the home abbreviated to ~ and scratch directories to $H. The desktop shows the same facts on Posture and Session.

Walkthrough: verify a hook release seal

Can you prove, byte for byte, that a hook release is exactly what was sealed — and when it is not, name the file that changed? This walkthrough does both, read-only, against a real sealed release. Every command below was executed against the release built by Scripts/build-app.sh on 2026-08-24; outputs are pasted verbatim, with the home directory abbreviated to ~ and temp directories to $TMP. The identity model is concepts/seal; the scripts are in scripts.

Examples

Runnable, commented shell scripts, one bounded CLI outcome each. Every script states whether it reads or mutates before its first command; mutation scripts require explicit environment inputs before they act. The command surface is documented in docs/cli.md; the two integrity scripts are executed end-to-end with pasted output in the walkthroughs.

Project

2 topics

Security policy

Report vulnerabilities through the private GitHub Security Advisory channel for wisent-ai/tama-desktop.

Changelog

All user-visible changes follow the categories required by docs/releases.md. A published section maps to the canonical immutable signed Git tag with the same semantic version.