git.sethpc.xyz-connector/docs/superpowers/specs/2026-04-01-gitea-connector-design.md

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 but you said . 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