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

• Initial repository setup
• Finish Up Agent created and deployed
• Agent renamed from "Sysadmin Session Closer" to "Finish Up"
• VPS hostname tracking added to filenames
• 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