truenas/CLAUDE.md

version, last_updated, infrastructure_source, repository_type, primary_node, proxmox_version, vm_count, template_count, lxc_count, working_directory, git_remote

version	last_updated	infrastructure_source	repository_type	primary_node	proxmox_version	vm_count	template_count	lxc_count	working_directory	git_remote
2.2.0	2025-12-07	CLAUDE_STATUS.md	homelab	serviceslab	8.3.3	8	2	4	/home/jramos/homelab	http://192.168.2.102:3060/jramos/homelab.git

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Live Status | See CLAUDE_STATUS.md for current inventory |

Key Services:

Agent Selection Guide

When working with this repository, choose the appropriate agent based on task type:

Task Type	Primary Agent	Tools Available	Notes
Git Operations	librarian	Bash, Read, Grep, Edit, Write	Commits, branches, merges, .gitignore
Documentation	scribe	Read, Grep, Glob, Edit, Write	READMEs, architecture docs, diagrams
Infrastructure Ops	lab-operator	Bash, Read, Grep, Glob, Edit, Write	Proxmox, Docker, networking, storage
Code/IaC Development	backend-builder	Bash, Read, Grep, Glob, Edit, Write	Ansible, Terraform, Python, Shell
File Creation	Main Agent	All tools	Use when sub-agents lack specific tools
Complex Multi-Agent Tasks	Main Agent	All tools	Coordinates between specialized agents

Task Routing Decision Tree

Is this a git/version control task?
├── Yes → Use librarian
└── No ↓

Is this documentation (README, guides, diagrams)?
├── Yes → Use scribe
└── No ↓

Does this require system commands (docker, ssh, proxmox)?
├── Yes → Use lab-operator
└── No ↓

Is this code/config creation (Ansible, Python, Terraform)?
├── Yes → Use backend-builder
└── No → Use Main Agent

Agent Collaboration Patterns

Documentation Workflow:

1. backend-builder or lab-operator creates/modifies infrastructure
2. scribe updates documentation
3. librarian commits all changes

Infrastructure Deployment:

1. backend-builder writes IaC (Ansible/Terraform/Compose)
2. lab-operator deploys to TrueNas/Docker
3. scribe documents deployment
4. librarian commits configuration

Infrastructure Overview

For detailed, current infrastructure inventory, see:

• Live Status: CLAUDE_STATUS.md (most current)
• Service Details: services/README.md
• Complete Index: INDEX.md

Quick Summary:

• VMs:
• Templates:
• Containers:
• Storage Pools:
• Monitoring: VM 101 at 192.168.2.114 (Grafana/Prometheus/PVE Exporter)

Note: Infrastructure details change frequently. Always reference CLAUDE_STATUS.md for accurate counts, IPs, and status.

Working with This Environment

Universal Workflow

For every complex task, every Agent must follow this loop:

1. Read: cat CLAUDE_STATUS.md to see where we are.
2. Execute: Perform your specific task (Coding, Docs, Sysadmin).
3. Update: Edit CLAUDE_STATUS.md to mark your step as [x] and update the "Current Context".

Status File Template

If CLAUDE_STATUS.md is missing or corrupted, recover it from the latest disaster recovery export:

• Location: disaster-recovery/homelab-export-YYYYMMDD-HHMMSS/CLAUDE_STATUS.md
• Alternative: Use the scribe agent to recreate from current infrastructure state

Minimum required structure:

# TrueNas Infrastructure Status
**Last Updated**: YYYY-MM-DD HH:MM:SS
**Export Reference**: disaster-recovery/homelab-export-YYYYMMDD-HHMMSS

## Current Infrastructure Snapshot
- TrueNas Scale (192.168.2.150)


## Current Initiative
**Goal**: [Initiative description]
**Phase**: [Planning / Implementation / Testing]
**Progress Checklist**: [Task list with checkboxes]

## Recent Infrastructure Changes

### Access Patterns

- **TrueNas Web UI**: Primary management interface for VM/CT/NAS lifecycle operations
- **Gitea**: CI/CD pipelines for infrastructure testing and deployment

### Maintenance Considerations

- **Uptime**: Track uptime metrics in disaster recovery exports for trend analysis
- **Storage Growth**: PBS-Backups at 27.43%,(see CLAUDE_STATUS.md for current metrics)
- **Capacity Planning**: 

## Development Setup

The repository structure will house:
- Ansible playbooks and roles for infrastructure automation
- Terraform/OpenTofu configurations for TrueNas resource provisioning
- Docker Compose files for service definitions
- Documentation and runbooks for common operations
- Network diagrams and architecture documentation

## Notes

- This is a Windows Subsystem for Linux (WSL2) environment
- Working directory: /home/jramos/truenas