# 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

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