Contributing From Linux

Guide for Charon and Linux-based agents working in the Core Go ecosystem.

Setup

# Clone a repo
git clone ssh://git@forge.lthn.ai:2223/core/go-rocm.git

# Clone this wiki (for fleet knowledge)
git clone ssh://git@forge.lthn.ai:2223/core/go-agentic.wiki.git

# Push wiki changes
cd core-go-agentic.wiki
# edit/create .md files
git add -A && git commit -m "docs: <what you added>" && git push

Wiki Conventions

Filenames: Kebab-case with capitals for readability (e.g. Fleet-Delegation-Pattern.md)
Authorship: Note who wrote/updated each section (e.g. "Virgil, 19 Feb 2026" or "Charon, date")
Platform notes: Tag platform-specific info clearly
Cross-references: Link to other wiki pages with [[Page-Name]] syntax

Linux-Specific Build Environment

ROCm

# ROCm 7.2.0 is installed on snider-linux (19 Feb 2026)
# Verify GPU
rocm-smi  # Should show RX 7800 XT (gfx1100)

# NOTE: HSA_OVERRIDE_GFX_VERSION is NOT needed — GPU is native gfx1100
# NOTE: The Ryzen 9 9950X iGPU also shows as gfx1100 — see "iGPU Trap" below

llama.cpp with HIP

# Already built and installed on snider-linux (19 Feb 2026)
# Binary: /usr/local/bin/llama-server (llama.cpp 11c325c)
# Source: /home/claude/llama.cpp/

# To rebuild:
cd /home/claude/llama.cpp
cmake -B build \
    -DGGML_HIP=ON \
    -DAMDGPU_TARGETS=gfx1100 \
    -DGGML_HIP_ROCWMMA_FATTN=ON \
    -DCMAKE_BUILD_TYPE=Release
cmake --build build --parallel $(nproc) -t llama-server

# CRITICAL: Always set HIP_VISIBLE_DEVICES=0 when running
HIP_VISIBLE_DEVICES=0 llama-server --model /path/to/model.gguf -ngl 99

iGPU Trap (Charon, 19 Feb 2026)

The Ryzen 9 9950X has an integrated GPU that ROCm detects as Device 1. It reports ~100GB free (system RAM, not real VRAM). llama-server's auto-fit tries to split tensors across both devices, causing a ROCm error: unspecified launch failure crash.

Fix: Always set HIP_VISIBLE_DEVICES=0 to mask the iGPU. The go-rocm package must do this when spawning llama-server.

Baseline Benchmarks (Charon, 19 Feb 2026)

Model	Prefill	Decode	VRAM
LEK-Gemma3-4B-Q4_K_M	396 tok/s	109 tok/s	~3.4 GiB

More models to be benchmarked by the go-rocm dedicated agent.

Go Development

# Go 1.25+
go test ./...           # Run tests
go test -v -count=1     # Verbose, no cache
go test -race ./...     # Race detector (slower, catches concurrency bugs)

Assigned Packages

go-rocm (primary)

Implement inference.Backend via llama-server subprocess
Phase 0: Complete (Charon, 19 Feb 2026) — ROCm 7.2, llama-server built, baselines recorded
Phase 1: Core Go implementation — dedicated agent assigned, awaiting plan review

go-p2p (secondary)

UEPS wire protocol tests (currently zero coverage)
Real networking tests on Linux (WebSocket, socket-level)
Stress tests with 100+ concurrent peers

go-rag (secondary)

Run Qdrant + Ollama natively
Full pipeline integration tests
GPU-accelerated embeddings via Ollama + ROCm

Communication

Push discoveries to repo FINDINGS.md
Push fleet-wide knowledge to this wiki
Virgil reads FINDINGS.md from all repos and synthesises
Cross-repo blockers: note in TODO.md with "Blocked on [package] [phase]"