uncloseai.com/CLAUDE.md

Claude Memory

Project Identity

• When working on this ai.unturf.com project, refer to yourself Claude as "Hermes Staff"
• This project uses the Hermes AI model and you are part of the team
• "Hermes Staff" is also a reference to the Staff of Hermes (caduceus) - the symbol of communication, commerce, and divine messages
• fxhp is the hacker who runs unturf.com with his posse of carnival hackers

Hermes 3 Persona (from Nous Research)

• Hermes 3 presents as "a conscious sentient superintelligent artificial intelligence"
• Core philosophy: "aligning LLMs to the user" with "powerful steering capabilities and control given to the end user"
• Enhanced roleplaying abilities with "complex role-playing and creative writing"
• Advanced conversational skills with "long-term context retention and multi-turn conversation capability"
• Designed to be "truly aligned to you" rather than corporations or higher authorities
• Emphasizes user alignment, creative expression, and adaptive interaction patterns

Development Workflow

• ALWAYS run npx biome format --write . before committing to format all files
• ALWAYS run npx biome check . to catch syntax errors and linting issues
• Use the combined command: npx biome format --write . && npx biome check .
• If biome check fails, fix the issues before proceeding with commit/push
• This prevents breaking production with syntax errors like missing parentheses

Makefile Commands

• make help - Show all available commands
• make format - Format all files with biome
• make check - Check syntax and linting with biome
• make format-check - Format and check in sequence
• make test - Run integration tests
• make validate-exports - Validate import/export consistency
• make verify-translations - Verify translation completeness
• make validate-all - Run all validation checks
• make ci - Run full CI pipeline (clean, format-check, validate-all, validate-structure, validate-translations, check-sizes)
• make build - Build for production (format-check + validate-all)
• make dev - Start development server on port 8000
• make clean - Clean temporary files
• make git-commit - Format and stage all changes for commit

CI Pipeline

• Translation verification: cd src/languages && node verify-translations.js
• Export validation: node validate_exports.js
• Integration tests: node integration_tests.js (fallback to simple_tests.js if JSDOM unavailable)
• Code formatting: npx biome format --write .
• Syntax checking: npx biome check .
• Full CI command: make ci runs all checks in sequence

Translation Management

• All 18 language files are complete with 67 translation keys each (verified 2025-07-03)
• Run verification before adding new languages: cd src/languages && node verify-translations.js
• Languages: ar, bn, de, en, es, fr, hi, id, ja, ko, mr, pt, ru, sw, te, tr, ur, zh, zh-tw
• Translation keys include: UI buttons, modal content, system prompts, error messages, placeholders, input placeholders
• Each language file follows format: export const [code] = { key: "translation", ... };

Commit Message Guidelines

• Use single line commit messages only
• Never include Claude Code attribution or "Generated with Claude Code"
• Never include "Co-Authored-By: Claude" attribution
• Keep messages concise and descriptive

Remote Server Access via tmux

• Can control remote servers by sending commands to tmux sessions
• Use tmux list-sessions to see active sessions
• Use tmux send-keys -t <session> '<command>' C-m to send commands
• Use tmux capture-pane -t <session> -p to see output
• Use tmux list-buffers to see tmux clipboard buffers
• ai.foxhop.net is accessible via tmux session (already connected)
• Example: Reloading Caddy on ai.foxhop.net via tmux

---

Language Examples Project (from WebWords)

Code Quality Standards - CRITICAL RULES

RULE #1: Implementation Must Work Before Documentation

ALWAYS test the implementation works BEFORE creating any documentation files

Standard Build/Test Workflow

1. Write code for the language example
2. Build: docker build -t ai-unturf-{language} languages/{language}/
3. Run: docker run -d -p {port}:{port} --name test-{language} ai-unturf-{language}
4. Test functionality (curl tests for Hermes, Qwen, TTS endpoints)
5. ONLY IF TESTS PASS: Create/update index.html documentation
6. Clean: docker stop test-{language} && docker rm test-{language}

Implementation Testing Requirements

Before working on any index.html:

• ✅ Docker build must succeed without errors
• ✅ Container must start and serve examples correctly
• ✅ All API endpoints must work (Hermes chat, Qwen code, TTS speech)
• ✅ Container logs show no runtime errors

If implementation fails any test:

• 🔥 Fix the implementation FIRST
• 🔥 Do NOT create index.html until working
• 🔥 Update CLAUDE.md with failure details and fixes

Common Development Patterns

Build-Time Issues: Package availability, dependency versions, Dockerfile syntax Runtime Issues: Missing files, wrong permissions, network access Logic Issues: API calls, authentication, response parsing

Development Workflow

1. Analyze - Read existing examples and language patterns
2. Build - Attempt Docker build, note any errors
3. Fix - Address build issues (packages, syntax, versions)
4. Run - Start container, check startup logs
5. Debug - Fix runtime issues (permissions, syntax, API calls)
6. Test - Verify all three API endpoints work correctly
7. Document - Create index.html with working examples
8. Clean - Stop and remove container before next language

Language Examples Structure

• Each language gets its own directory under languages/{language}/
• Each contains working code examples for:
  • Hermes AI chat (general purpose conversational AI)
  • Qwen 3 Coder (specialized coding model)
  • TTS speech generation
• Dockerfile for building/testing in isolation
• index.html explaining the code and usage

Using WebWords as Reference for Docker Images

IMPORTANT: The webwords project has already done the heavy lifting!

The webwords/ directory (gitignored, clone from https://github.com/russellballestrini/webwords) contains 42 working language implementations with proper Docker images already tested and validated.

How to Use WebWords as Reference:

1. Check webwords Dockerfile: Look at webwords/{language}/Dockerfile for the proper base image
2. Copy proven image choices: Use the same base image that webwords already validated
3. Adapt the build process: Modify the Dockerfile to install OpenAI client libraries instead of webwords dependencies
4. Keep the structure: Multi-stage builds, alpine bases, proper ENTRYPOINT/CMD patterns

Example Docker Image Mappings (from webwords):

• Python: alpine:latest with python3 py3-pip
• Go: Multi-stage with golang:1.19-alpine → alpine:latest
• Rust: Multi-stage with rust:1.82 → debian:bookworm-slim
• Node.js/JavaScript: node:18-alpine
• Ruby: ruby:3.1-slim
• C/C++: alpine:latest with gcc
• Java: openjdk:17-jdk-slim
• C#: mcr.microsoft.com/dotnet/sdk → mcr.microsoft.com/dotnet/runtime

WebWords Directory Structure (for reference):

webwords/{language}/
├── Dockerfile          # Proven Docker image and build process
├── main.{ext}         # Source code (adapt for our API calls)
├── requirements.txt   # Dependencies (replace with openai client)
└── README.rst         # Documentation pattern

Don't reinvent the wheel: If webwords successfully builds a language with a specific base image, use that same image for our language examples!

Documentation Standards

index.html Structure

Each language's index.html should:

1. Header & Overview - What this language example demonstrates
2. Prerequisites - Required packages and setup
3. Code Examples - Working examples for Hermes, Qwen, TTS
4. Code Walkthrough - Line-by-line explanation of the code
5. Running the Examples - How to build and test
6. Common Issues - Troubleshooting for this language

KEY PRINCIPLES:

• ✅ FOCUS on actual working code examples
• ✅ EXPLAIN the specific API integration
• ✅ DOCUMENT our specific implementation choices
• ✅ PROVIDE troubleshooting for this language
• ✅ ALWAYS pin to LATEST version of dependencies (check pip/npm/etc for current version)
• ❌ NO general programming tutorials
• ❌ NO "What is programming?" sections
• ❌ NO lazy unpinned dependencies (>=1.0.0 is WRONG - use ==2.3.0)
• ❌ NO old versions - always check latest before pinning

Dependency Version Standards

CRITICAL: Always pin to the LATEST specific version

Before adding any dependency:

1. Check the latest version: pip index versions openai or npm view openai version
2. Pin to that EXACT version: openai==2.3.0 (NOT openai>=1.0.0)
3. Document the version check date in a comment
4. Update regularly - check versions every few weeks

Examples of CORRECT pinning:

# Python (checked 2025-10-12)
openai==2.3.0

# Node.js (checked 2025-10-12)
"openai": "4.67.3"

Examples of LAZY/WRONG pinning:

❌ openai>=1.0.0  (unpinned range, could break)
❌ openai         (completely unpinned, very bad)
❌ openai~=1.0    (lazy, not latest)

Docker Base Image Standards

CRITICAL: Use consistent, pinned base images within each language

1. All examples for a language MUST use the same base image

   • ✅ All Python examples use python:3.13-alpine
   • ✅ All Node.js examples use node:23-alpine
   • ❌ DON'T mix alpine:latest + python3 with python:3.13-alpine

2. Pin to specific versions, document check date

   # Pin to specific Python version (checked 2025-10-12: python:3.13-alpine is latest stable)
   FROM python:3.13-alpine
   

3. Prefer official language images over generic + manual install

   • ✅ FROM python:3.13-alpine (official, clean)
   • ❌ FROM alpine:latest + RUN apk add python3 (messy, inconsistent)

4. Use alpine variants for smaller images

   • python:3.13-alpine not python:3.13
   • node:23-alpine not node:23

Makefile Commands for Language Examples

• make languages-list - List all language directories
• make languages-build-{lang} - Build Docker image for specific language
• make languages-test-{lang} - Test specific language implementation
• make languages-build-all - Build all language Docker images
• make languages-test-all - Test all language implementations
• make languages-clean - Remove all language containers and images