tea/README.md

tea — Claude Code plugin for the Gitea CLI

A Claude Code plugin that gives Claude a reference for the tea CLI and enforces a hard rule: every tea command runs under the login the operator chose, never one Claude picked.

What it ships

Piece	What it does
/tea:login skill	Prompts you to pick a Gitea login and pins it to the project
/tea:use skill	Tea CLI reference — loads command docs on demand
tea-guard hook	PreToolUse hook that blocks or rewrites every tea invocation

Prerequisites

• Claude Code — CLI, desktop app, or IDE extension
• Python 3 — required by the tea-guard hook (python3 must be on $PATH)
• tea — Gitea's official CLI. Install with brew install tea (macOS) or from gitea.com/gitea/tea/releases
• At least one login configured: tea logins add (interactive — run it in a terminal, not via Claude)

Installation

This is a Claude Code plugin — install it through the plugin marketplace, not by hand-editing settings.json.

1. Register this repo as a marketplace:

   /plugin marketplace add https://git.noodles.cam/claude-skills/tea.git
   

   Already have a local clone? Point at the directory instead:

   /plugin marketplace add /path/to/tea
   

2. Install the plugin:

   /plugin install tea@tea
   

The skills (/tea:login, /tea:use) and the tea-guard hook load immediately. Use /plugin to enable, disable, or update it later.

The marketplace registration is written to extraKnownMarketplaces and the plugin to enabledPlugins in your settings automatically — you don't edit those by hand. There is no top-level "plugins" settings key; if you've added one from older instructions, remove it.

First use

Run /tea:login once per project. Claude will list your available Gitea logins and ask you to pick one. The choice is written to .claude/settings.local.json and takes effect immediately — no restart needed.

/tea:login

After that, use /tea:use to look up commands, or just ask Claude to do something with Gitea and it will load the reference automatically.

How the login guard works

Every tea invocation Claude writes must carry the literal placeholder --login "$GITEA_LOGIN". The tea-guard hook intercepts the Bash call before it runs, looks up the pinned login from .claude/settings.local.json, and rewrites the command to use it.

Claude is blocked from:

• running tea without --login at all
• naming a login itself (e.g. --login myaccount)
• using any variable other than $GITEA_LOGIN

This prevents silent fallback to the machine's default login (often a personal account) when working in a project that belongs to a different identity.

tea logins list and tea --version / --help are exempt — they don't touch Gitea data.

Project layout

.claude-plugin/
  plugin.json                plugin manifest
  marketplace.json           marketplace catalog (makes `/plugin install` work)
hooks/
  hooks.json                 registers the PreToolUse hook
  tea-guard.sh               the guard (Python 3, no deps)
skills/
  login/SKILL.md             /tea:login skill
  use/SKILL.md               /tea:use skill
  use/references/tea/        tea CLI reference docs