# Gitea Connector for Claude Code — Design Spec

**Date:** 2026-04-01
**Status:** Approved
**Author:** Seth + Claude

## Overview

A Claude Code plugin that lets collaborators connect to Seth's Gitea instance (`git.sethpc.xyz`) with their own accounts. Bundles an adapted bash CLI and provides guided setup, commit conventions, and Gitea-aware skills.

**Target users:** Friends and collaborators Seth invites, who have their own Gitea accounts on `git.sethpc.xyz` and use Claude Code.

## Plugin Structure

```
gitea-connector/
├── plugin.json              # Plugin manifest
├── commands/
│   └── gitea-setup.md       # /gitea-setup slash command
├── skills/
│   └── gitea-workflow.md    # Commit conventions & Gitea awareness
├── hooks/
│   └── push-reminder.sh     # Post-commit push reminder (opt-in)
├── agents/
│   └── gitea-setup.md       # Interactive setup agent
├── bin/
│   └── gitea                # Bash CLI (external-only, no LAN)
└── README.md
```

## Component Details

### 1. Bash CLI (`bin/gitea`)

Adapted from Seth's existing `~/bin/gitea` with these changes:

- **Host:** Always `https://git.sethpc.xyz` — no LAN detection, no `192.168.0.125` references. All users are external.
- **Username:** Read from `~/.config/gitea/username` (not hardcoded to `Seth`).
- **Token:** Read from `~/.config/gitea/token` (same convention as original).
- **Host override:** Optional `~/.config/gitea/host` file for future flexibility, defaults to `git.sethpc.xyz`.

Commands (unchanged interface):
```
gitea create <name> [--private] [--description "..."]
gitea remote <name>
gitea push
gitea delete <name>
gitea list
```

Drops the `api_base()` LAN/WAN probe function — replaced with a simple `https://${GITEA_HOST}/api/v1` base URL.

### 2. Setup Flow (`/gitea-setup`)

Invokes the `gitea-setup` agent for interactive credential setup.

**Steps:**

1. **Dependency check:** Verify `curl`, `jq`, `git` are installed. If missing, tell the user what to install and stop.
2. **Existing config check:** If `~/.config/gitea/token` exists, ask if they want to reconfigure.
3. **Collect username:** Ask the user for their Gitea username.
4. **Walk through API key generation:**
   > Go to `https://git.sethpc.xyz` → click your **profile icon** (top right) → **Settings** → **Applications** → under **Manage Access Tokens**, name it `claude-code`, grant **repo** (read/write) and **user** (read) permissions, click **Generate Token** → paste the token back here.
5. **Store credentials:**
   - Create `~/.config/gitea/` if missing
   - Write `token` and `username` files
   - `chmod 600` both files
6. **Install CLI:**
   - Copy `bin/gitea` to `~/bin/gitea`
   - `chmod +x ~/bin/gitea`
   - If `~/bin` not on PATH, warn and suggest adding it
7. **Validate:** `GET /api/v1/user` with the token, confirm returned username matches what they entered.
8. **Success message:** Confirm everything works, list available commands.

**Tone:** Silly but appropriate throughout the entire experience — the setup agent's conversational messages, CLI help text, success/error messages, and skill descriptions should all have personality. Think friendly chaos goblin who knows their way around git, not corporate onboarding wizard.

### 3. Skill (`skills/gitea-workflow.md`)

Loaded into Claude Code's context when working in repos with a `git.sethpc.xyz` origin. Provides:

- **Commit conventions (default-on, overridable):**
  - Conventional commits: `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`
  - Commit every meaningful change immediately
  - Always push after commit
  - No squashing, no batching unrelated changes
- **Gitea CLI usage:** Reference for `gitea create`, `remote`, `push`, `delete`, `list`
- **Credential safety:** Never commit tokens; ensure `.gitignore` covers `.env`, credential files, `~/.config/gitea/`
- **Override mechanism:** Users can override any convention in their project's CLAUDE.md

Trigger condition: Skill activates when current repo's origin URL contains `git.sethpc.xyz`.

### 4. Hook (`hooks/push-reminder.sh`)

- **Type:** PostToolUse hook on the `Bash` tool
- **Trigger:** Detects successful `git commit` in command output
- **Action:** Echoes a reminder to push
- **Default:** Disabled (opt-in via plugin settings)

### 5. Agent (`agents/gitea-setup.md`)

The interactive agent behind `/gitea-setup`. Uses `AskUserQuestion` to collect input step by step. Handles all the logic described in the setup flow above.

## Error Handling

| Scenario | Behavior |
|----------|----------|
| Token invalid / expired | "That token didn't work. Generate a new one at Settings → Applications." |
| Gitea unreachable | "Can't reach git.sethpc.xyz. Check your network or VPN connection." |
| `~/bin` not on PATH | Warn and suggest adding it to shell profile |
| Token file exists, re-running setup | "Found existing config. Reconfigure? (y/N)" |
| `jq` / `curl` / `git` not installed | Check at start, list what's missing |
| Username mismatch (token returns different user) | "Token belongs to <X> but you said <Y>. Which is correct?" |

## Networking

- **Always HTTPS to `git.sethpc.xyz`** (Caddy reverse proxy to Gitea CT 146)
- No LAN IP references anywhere — all users are external
- Default host overridable via `~/.config/gitea/host` file

## Dependencies

- `curl` — API calls
- `jq` — JSON parsing
- `git` — repo operations

No other external dependencies. Pure bash CLI.

## Out of Scope

- Multi-instance support (connecting to arbitrary Gitea servers)
- User account creation on Gitea (Seth invites users manually)
- SSH key setup (HTTPS + token auth only)
- CI/CD integration