Skip to main content
A team’s collection policy is the one place that decides what Terma collects for that team. An organization admin sets it in Terma, and every member’s terma CLI fetches it and applies it on their own machine, before anything is sent. There is nothing to configure per repository and nothing to commit. Each team has its own policy. A session follows the policy of the team the developer chose when they ran terma setup, so two developers on different teams, working in the same repository, each follow their own team’s policy.

​
Where to find it

Open Team settings → Data collection. Everyone in the organization can read the policy there. Only organization admins see Edit, and saving replaces the whole policy at once. A new team starts with no policy, and a team with no policy collects nothing. The panel says “No policy yet. An organization admin can set one up.” Members who run terma setup before then are signed in and wired up, but nothing is recorded until the policy exists. terma doctor reports this as “no team collection policy on this machine, so nothing is recorded”.

​
The settings

A policy has three parts.

​
Repositories: where members send from

Choose one: Use Every session when the team’s machines are dedicated to its work. Use a list when people also work on personal or other teams’ code on the same machine.

​
Commits: stamp commits with the agent session

With Stamp commits with the agent session on, the first agent session in a collected repository installs two git hooks, prepare-commit-msg and post-commit, in that repository’s own .git/hooks. Commits of files an agent edited then carry Agent-Session-Id and Agent-Tool trailers, so they link to the session that wrote them. Any hook already there keeps running first. See Attribution for how a commit is matched to a session. Turning stamping off stops terma adding hooks to more repositories. It doesn’t remove hooks it already added.

​
Never sent: redacted before it leaves a machine

The relay on each member’s machine removes this content before anything is forwarded, so it never reaches Terma. Session structure, tokens, cost, models, tools used, and timings are still collected. See Privacy and data.

​
Writing the repository list

Each entry is a repository written as host/owner/name, for example github.com/acme/api. A longer path names a GitLab subgroup, for example gitlab.com/acme/platform/api. You can add entries three ways:
  • Type it as host/owner/name.
  • Paste a clone URL. https://github.com/acme/api.git and git@github.com:acme/api.git both become github.com/acme/api.
  • Add from GitHub. With GitHub connected to your organization, pick repositories from the ones the Terma GitHub App can see.
An entry must have a host (containing a ., or localhost) and at least an owner and a name. It must not include a scheme, a port, a user, or a trailing .git. Entries are unique ignoring case, and a list holds up to 500 of them.

​
How a session is matched

When an agent session starts, terma reads the origin remote of the git working copy it runs in and compares it with the list, ignoring case:
  • The URL is normalised first. HTTPS, SSH, git:// and git@host:path forms all match, the host loses any port or credentials, and the path loses .git and a trailing slash.
  • Subdirectories and worktrees count. A session in a subdirectory of a listed repository is collected, and so is one in a linked worktree, which reads origin from its main repository.
  • Some sessions never match a list: a folder outside git, a repository with no origin, an origin that is a local path, and a fork whose origin is your own copy (github.com/you/api does not match github.com/acme/api).
  • SSH host aliases don’t match. git@github-work:acme/api has the host github-work. Point origin at the real host and choose your key with core.sshCommand instead.
A session that isn’t collected is dropped on the developer’s machine: its telemetry never leaves. To check a repository, run terma doctor inside it. It shows the origin terma sees and whether your team collects it.

​
How changes reach every machine

Each member’s terma fetches the policy with their own sign-in and keeps a copy on the machine, which its hooks and relay read. It fetches a fresh copy whenever it delivers what the hooks queued, which happens after an agent session ends or a commit is made, at most once a minute. terma setup and terma doctor fetch it too. So a change you save reaches each member’s machine at their next session end or commit, with nothing for them to run. A member who wants it at once can run terma doctor.
  • Tightening applies to what’s queued. Events already waiting on a machine are sent under the current policy. An event from a repository you removed doesn’t leave, and one queued before you turned on Don’t send prompts leaves without its prompts.
  • Widening applies from then on. Adding a repository collects sessions there from the change onwards, not earlier work.
  • A machine that can’t reach Terma keeps the last policy it fetched for up to a week. After that it collects nothing until it can fetch the policy again, and terma doctor reports “the collection policy has not been refreshed for over a week”.

Team settings

Where the policy is edited, alongside team API keys and principals.

Privacy and data

What leaves a machine, what stays, and how credentials are stored.