homelab-agents/CLAUDE.md

# AI Context File - Homelab Agents

**Repository**: homelab-agents (shared agent repository)
**Gitea Location**: http://100.120.125.113:3000/pdm/homelab-agents.git
**Purpose**: Centralized repository of Claude Code agents for VPS homelab automation
**User**: pdm

## Project Overview

This is a shared repository containing Claude Code agents that can be deployed across multiple VPS instances in the homelab environment. Agents help automate common system administration tasks, session management, and project workflow.

## Current Development Phase

- [x] Initial repository setup
- [x] Finish Up Agent created and deployed
- [x] Agent renamed from "Sysadmin Session Closer" to "Finish Up"
- [x] VPS hostname tracking added to filenames
- [x] Installation scripts created
- [ ] Agent testing across multiple VPS instances
- [ ] Additional specialized agents as needed

**Current Phase**: Maintenance and deployment
**Completion**: ~70%

## Key Decisions & Context

### Project Goals & Requirements

**Primary Objectives:**
- Create reusable Claude Code agents for homelab automation
- Enable consistent session management across multiple VPS instances
- Automate git workflows with Gitea integration
- Preserve session context for seamless work resumption

**Must-Have Features:**
- Session summary generation with comprehensive context
- Automatic git commit and push to Gitea repositories
- VPS hostname tracking in documentation files
- Easy agent installation on new VPS instances

### Architecture & Design

**Repository Structure:**
```
.homelab-agents/
├── agents/
│   ├── finish-up.md          # Main session closure agent
│   └── README.md             # Agent documentation
├── scripts/
│   ├── install-agent.sh      # Deploy agent to VPS
│   ├── bootstrap-agents.sh   # Initial setup script
│   └── init-project.sh       # New project initialization
├── session-logs/             # Historical session documentation
└── templates/                # Project templates
```

**File Naming Convention:**
- **ALL new files:** `{hostname}-{description}.md` (e.g., `sys-apps-git-quick-reference.md`)
- Agent files: `agents/{agent-name}.md` (no hostname prefix for shared agents)
- Session files: `{hostname}-session-summary.md`
- Documentation files: `{hostname}-{topic}.md`

**Important:** Always run `hostname` command to get the current VPS hostname. Never hardcode it.

### Technical Decisions

**Gitea Integration:**
- Base URL: http://100.120.125.113:3000
- Organization: pdm
- Repository auto-detection based on current working directory
- Support for both shared repo (homelab-agents) and project-specific repos

**Hostname Tracking:**
- Uses `hostname` command to identify VPS
- Embedded in session summary filenames
- Helps track which VPS was used for each work session

**Agent Installation:**
- Centralized in this repository
- Scripts pull agents to VPS ~/.homelab-agents directory
- Consistent deployment across all VPS instances

### Implementation Notes

**Finish Up Agent Features:**
- Comprehensive session summary generation
- Automatic README.md and CLAUDE.md updates
- Git workflow automation (commit + push)
- Repository type detection (shared vs project-specific)
- VPS hostname in all generated filenames
- Optional Gitea repository auto-creation with API token

**Installation Process:**
1. Clone homelab-agents to VPS: `git clone http://100.120.125.113:3000/pdm/homelab-agents.git ~/.homelab-agents`
2. Run bootstrap script: `~/.homelab-agents/scripts/bootstrap-agents.sh`
3. Agents become available in Claude Code

### Gitea Integration

**Repository Pattern:**
- Shared agents: `http://100.120.125.113:3000/pdm/homelab-agents.git`
- VPS projects: `http://100.120.125.113:3000/pdm/{project-name}.git`

**Authentication:**
- SSH keys configured for git operations
- Optional API token for automatic repository creation

## Session History

### Session 2025-11-28
- **Phase**: Documentation cleanup and naming convention updates
- **VPS**: sys-apps (renamed from 108-system-apps)
- **Repository**: homelab-agents
- **Accomplishments**:
  - Created WORKFLOW.md with simple agent workflow guide
  - Consolidated documentation (deleted QUICK-START.md, renamed HOW-TO-GUIDE.md → GIT-REFERENCE.md)
  - Simplified session summary filename format: `{hostname}-session-summary.md` (removed redundant project name)
  - Updated VPS hostname from 108-system-apps to sys-apps, renamed all related files
  - Created sys-apps-git-quick-reference.md for git basics
  - Established file naming convention: ALL new files prefixed with `{hostname}-`
  - Made hostname detection dynamic (`hostname` command) to work across all VPS instances
- **Key Decisions**:
  - File naming convention added to CLAUDE.md for automatic enforcement
  - Session summaries overwrite (no timestamp) - CLAUDE.md has high-level history
  - ~/.homelab-agents stays in home root (infrastructure/tooling, not a project)
  - Documentation structure: README (overview), WORKFLOW (simple guide), GIT-REFERENCE (detailed commands)
- **Next Steps** (Prioritized):
  - Test finish-up agent on real project (not homelab-agents)
  - Deploy agents to additional VPS instances
  - Consider additional specialized agents for common tasks

## Notes for Future Sessions

**When Working in homelab-agents:**
- This is a SHARED repository - changes affect all VPS instances
- Always test agents before pushing to Gitea
- Use descriptive commit messages indicating agent changes
- Mark commits with "[homelab-agents]" prefix

**When Installing on New VPS:**
1. Clone this repository to `~/.homelab-agents`
2. Run `scripts/bootstrap-agents.sh`
3. Configure SSH keys for Gitea (see VPS-SSH-KEY-SETUP.md)
4. Optional: Set GITEA_API_TOKEN for auto-repo creation

**VPS Instances Using This Repository:**
- sys-apps (current)
- [Add other VPS hostnames as they're configured]

## Quick Reference

**Repository URL**: http://100.120.125.113:3000/pdm/homelab-agents.git
**Clone Command**: `git clone http://100.120.125.113:3000/pdm/homelab-agents.git ~/.homelab-agents`
**Gitea Web UI**: http://100.120.125.113:3000/pdm/homelab-agents
**Branch**: main
**Owner**: pdm