How it works

#A team is one git repository

Everything the team shares lives in one private repository, and nothing lives anywhere else.

#No server, no account

Membership is repository access. You are an active member when people/<handle>.json exists and your handle is not in team.json’s archived list. Both are required: a departure archives the handle rather than deleting the file.

There is no Terum server and no Terum account. The team’s data sits on your git host, and the rest happens here:

Privacy and network lists every request and how to avoid it.

#The CLI and the app

The desktop app is a window onto the CLI, and every verb works from a terminal without it. The app runs the CLI as a child process with --frames, which speaks JSON, one object per line. Every question a verb would ask in a terminal becomes an ask frame that waits for the app’s answer.

So the app shows what the CLI returns. It has no HTTP client; its webview opens only https://github.com/* and https://discord.gg/* links. The protocol is in the frame protocol.

#How a write reaches the team repo

Every write goes through one function that re-applies your change instead of rebasing it:

1. Fetch, and hard-reset the clone to origin/main.
2. Apply the verb’s change to that fresh tree.
3. Run the write guard on the result.
4. Stage exactly the paths the change touched, and check the staged diff matches them.
5. Commit and push to main.
6. If someone else pushed first, discard the commit and start over, with backoff, until a 30-second deadline.

One writer holds a per-clone lock for the whole loop, so two terminals on one machine queue instead of racing. Publish takes this same path: it pushes to main, and no branch or pull request is created.

The guard is the authorization model, and it is per verb. publish may add files to a version folder that does not exist yet, and may not touch one that does. unpublish is the only verb that may remove a version folder. Every other verb may write your own people file, and team.json only in the shape that verb needs. A write that touches one path it does not own is refused whole.

The same guard runs as a pre-push hook in your clone, so a hand-written git push is checked too. It catches accidents, not abuse: a bypass is possible, and is attributed to whoever pushed.

#What sync does, and does not

$ npx -y terum-skills@latest sync

sync runs git fetch and git reset --hard origin/main on each team clone, under that clone’s lock. Read verbs (ls, search, status) never fetch, so a teammate’s publish reaches you only when something does. The app runs sync in the background at launch and on window focus, at most once a minute.

sync does not place, copy, move or delete skill folders, push, edit a skill you are authoring, or repair a missing or broken clone. One exception: when a GitHub team’s repository answers “not found”, sync looks for where it went and, at a terminal, offers to move you there. Accepting runs team move, which does remove and re-place your placed skills.

#The session hook

Setup offers a Claude Code session-start hook, defaulting to No. With it, every session start runs sync --hook, which fetches your team clones in the background, at most once an hour. It places nothing and edits none of your skill folders, but it does refresh Terum’s own files (the bundled skills, the edit-hook script, its settings entry) when they are outdated.

The hook runs the copy of the CLI that installed it, pinned to that release, never @latest. A newer release reaches it when you re-run setup. Details are in Claude Code integration.

#Why it is built this way

• No server. A server would mean a Terum account, a Terum-held copy of your skills, and an operator to trust. A private repository already does distribution, history, access control and offline reads.
• No container. A skill is a folder Claude Code reads, with no runtime to isolate. Running Claude Code in a container breaks host authentication, host MCP servers, editor and browser extensions, and your global skills and hooks.
• Any git remote. Storage and sync work anywhere git works. Only membership administration needs a collaborator API, so invite and access-revoking team remove are GitHub-only.
• Git-host access is the permission model. Who may read and write the skills is who may read and write the repository.
• Evals run on your machine and budget. No CI job holds an API key, and a receipt records a run someone on the team paid for.