# 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](https://gitea.com/gitea/tea/releases)
- At least one login configured: `tea logins add` (interactive — run it in a terminal, not via Claude)

## Installation

Clone this repo into your Claude Code plugins directory:

```bash
git clone <repo-url> ~/.claude/plugins/tea
```

Then add it to your project's `.claude/settings.json`:

```json
{
  "plugins": ["~/.claude/plugins/tea"]
}
```

Or to your global settings (`~/.claude/settings.json`) to enable it everywhere.

## 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
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
```