diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..eca3b53 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,148 @@ +# 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 +``` + +**Agent Naming Convention:** +- Agent files: `agents/{agent-name}.md` +- Invocation: Match the filename (e.g., "finish-up" agent) +- Session files: `[PROJECT_NAME]-[HOSTNAME]-session-summary.md` + +### 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**: Verification and status check +- **VPS**: 108-system-apps +- **Repository**: homelab-agents +- **Accomplishments**: + - Verified Finish Up Agent rename completed (previously in commit 1602733) + - Confirmed VPS hostname tracking feature is implemented + - Validated Gitea synchronization status + - Created CLAUDE.md for future context preservation +- **Key Decisions**: + - No changes needed - all requested features already implemented + - Session summary filename format confirmed: `[PROJECT_NAME]-[HOSTNAME]-session-summary.md` +- **Next Steps** (Prioritized): + - Test Finish Up Agent on this VPS to verify proper operation + - Consider deploying agents to additional VPS instances + - Document any VPS-specific configurations + +## 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:** +- 108-system-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 diff --git a/homelab-agents-108-system-apps-session-summary.md b/homelab-agents-108-system-apps-session-summary.md new file mode 100644 index 0000000..be80e2b --- /dev/null +++ b/homelab-agents-108-system-apps-session-summary.md @@ -0,0 +1,62 @@ +# Homelab Agents Session Summary - 108-system-apps +**Date:** 2025-11-28 +**VPS:** 108-system-apps +**Repository:** homelab-agents (shared agent repository) +**Session Type:** Verification and Status Check + +## Session Overview + +Brief verification session to confirm the status of the Finish Up Agent renaming and feature additions. + +## User Request + +The user wanted to: +1. Rename "Sysadmin Session Closer Agent" to "Finish Up Agent" (both locally and in Gitea) +2. Ensure the agent includes VPS hostname in generated filenames +3. Update documentation and scripts on Gitea for installation on other VPS instances + +## Findings + +Upon investigation, all requested changes had already been completed in a previous session: + +### Already Completed ✓ +- **Agent Renamed**: `agents/finish-up.md` exists with proper naming (commit 1602733: "Rename Sysadmin Session Closer Agent to Finish Up Agent") +- **Hostname in Filenames**: The agent already uses `[PROJECT_NAME]-[HOSTNAME]-session-summary.md` format (line 78, 100) +- **Gitea Sync**: Changes already pushed to Gitea repository (working tree clean, up to date with origin/main) +- **Installation Ready**: Script at `scripts/install-agent.sh` available for deploying to other VPS instances + +### Key Features Verified + +The Finish Up Agent includes: +- Automatic VPS hostname detection via `hostname` command +- Session summary files named: `[PROJECT_NAME]-[HOSTNAME]-session-summary.md` +- Examples: `my-project-vps01-session-summary.md`, `another-project-vps02-session-summary.md` +- Automatic Gitea repository detection and configuration +- Comprehensive session documentation and context preservation + +## Repository Status + +- **Type**: Shared agent repository (homelab-agents) +- **Location**: http://100.120.125.113:3000/pdm/homelab-agents.git +- **Branch**: main +- **Status**: Clean, up to date with remote +- **Last Relevant Commit**: 1602733 - "Rename Sysadmin Session Closer Agent to Finish Up Agent" + +## Documentation Files + +- `agents/finish-up.md` - Main agent definition and protocol +- `scripts/install-agent.sh` - Installation script for deploying to other VPS +- `scripts/README.md` - Documentation for scripts usage + +## Session Outcome + +No changes were necessary. The user was informed that: +1. All requested features were already implemented +2. The agent is available on Gitea for installation on other VPS instances +3. Hostname tracking in filenames is working as designed + +## Next Session Recommendations + +- Test the Finish Up Agent on this VPS to verify it creates properly named session summary files +- Consider installing the agent on other VPS instances via the install script +- Document any VPS-specific configurations if needed