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 2026-04-12
- **Phase**: Emacs/iPad integration fixes
- **VPS**: home-apps
- **Repository**: homelab-agents
- **Accomplishments**:
  - Fixed Emacs init error in `flashcard-config.el` (mismatched parenthesis causing void-variable crash)
  - Fixed cross-platform load paths in `flashcard-config.el` and `task-config.el` (Mac vs VM paths)
  - Added `~/.emacs.d/secrets.el` symlink
  - Fixed ELPA package visibility by adding `~/emacs_config/elpa` to `package-directory-list` on Linux
  - Added `mermaid-mode` package alongside existing `ob-mermaid`
  - Fixed Puppeteer/Chromium sandbox error for mermaid rendering on Linux VM
  - Investigated and confirmed Notion credentials path resolves correctly
  - Set up `.netrc` on home-apps for Gitea authentication (both public domain and internal IP)
  - Bootstrapped home-apps into the homelab-agents workflow
- **Key Decisions**:
  - Conditional `darwin`/Linux load paths keep one config file working on both platforms
  - Puppeteer config file acts as a feature flag — presence enables `--no-sandbox`, absence is safe
  - `.netrc` requires two entries when scripts use internal IP for git operations
- **Next Steps** (Prioritized):
  - Test mermaid rendering end-to-end on iPad (compile + Babel blocks)
  - Verify Notion Tasks opens cleanly
  - Install `mermaid-mode` on Mac via `M-x package-install`

### Session 2025-11-30
- **Phase**: NetBox DHCP pool configuration automation
- **VPS**: sys-apps
- **Repository**: homelab-agents
- **Accomplishments**:
  - Created sys-apps-netbox-dhcp-setup.py to create IP Ranges for DHCP pools via NetBox API
  - Created sys-apps-netbox-reserve-dhcp-ips.py to reserve individual IPs .100-.150 as "Reserved" status
  - Configured 5 VLANs with DHCP pool reservations (255 IPs total)
  - Established DHCP pool standard: .100-.150 (51 IPs per /24 subnet)
  - Resolved NetBox showing DHCP pool IPs as "available" for static assignment
- **Key Decisions**:
  - Two-step approach: IP Ranges (logical grouping) + Individual IPs (actual reservation)
  - Status "Reserved" is correct for DHCP pools (allocated to DHCP, not assigned to device)
  - Scripts placed in ~/.homelab-agents (infrastructure tools, reusable across VPS)
  - API token authentication via environment variable or command-line argument
- **Next Steps** (Prioritized):
  - Document NetBox token management and rotation policy
  - Create "dhcp-pool" tag in NetBox UI for easier filtering
  - Consider automation for new VLAN creation

### 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
- home-apps (bootstrapped 2026-04-12)

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