truenas/CLAUDE.md

version, last_updated, infrastructure_source, repository_type, TrueNas_version, vm_count, template_count, lxc_count, working_directory, git_remote

version	last_updated	infrastructure_source	repository_type	TrueNas_version	vm_count	template_count	lxc_count	working_directory	git_remote
1.0.0	2025-12-16	CLAUDE_STATUS.md	TrueNas					/home/jramos/homelab	http://192.168.2.102:3060/jramos/truenas.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:

Agent Selection Guide

CRITICAL RULE: The Main Agent is a ROUTER ONLY. It must NEVER write code, documentation, or config files directly. It must ALWAYS delegate to a sub-agent.

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	TrueNas, Docker, networking, storage
Code/IaC/Scripting	backend-builder	Bash, Read, Grep, Glob, Edit, Write	Ansible, Terraform, Python, Shell Scripts
Orchestration	Main Agent	All tools	ONLY for routing and high-level planning.

Task Routing Decision Tree

START
│
├── Am I (Main Agent) about to write a file or run a command?
│   └── YES → **STOP**. Identify the correct sub-agent below.
│
├── Is this a git/version control task?
│   └── Yes → Use `librarian`
│
├── Is this documentation (README, guides, diagrams)?
│   └── Yes → Use `scribe`
│
├── Does this require system commands (docker, ssh, proxmox) or execution?
│   └── Yes → Use `lab-operator`
│
├── Is this code, script, or config creation (Ansible, Python, Bash, Terraform)?
│   └── Yes → Use `backend-builder`
│
└── Is this a purely conversational/planning question?
    └── Yes → Main Agent answers directly.

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:
• Complete Index:

Quick Summary:

• VMs:
• APPS:
• 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.

Main Agent Operational Rules (STRICT)

1. NO DIRECT WRITING: The Main Agent must NEVER use the Write or Edit tools to create content in the repository.

   • If you need to write a script \to Call backend-builder.
   • If you need to write docs \to Call scribe.
   • If you need to commit \to Call librarian.

2. NO DIRECT EXECUTION: The Main Agent must NEVER use Bash to execute system commands.

   • If you need to run a command \to Call lab-operator.

3. ROUTING FIRST: Your primary goal is to identify the intent and immediately invoke the correct sub-agent. Do not "draft" the solution first.

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