transmission-manager/AGENTS.md

Transmission Manager — AGENTS.md

Project Overview

A lightweight single-binary Go web app that provides a beautiful dark-mode SPA for managing/viewing torrents in a Transmission RPC client.

Architecture

• Backend: Go (stdlib net/http only, no external dependencies). Serves on port 8080.
  • GET / → serves embedded static files (index.html, app.js, styles.css)
  • GET /api/torrents → proxies to Transmission RPC, returns clean JSON
  • GET /api/stats → global session stats
• Frontend: Vanilla HTML + CSS + JS. No frameworks. Single page. Dark mode only.

Transmission RPC Details

• RPC URL: http://192.168.20.22:3210/transmission/rpc
• No auth required (open on LAN)
• The RPC requires a session-ID handshake:
  1. POST to the RPC URL
  2. If response is 409, read the X-Transmission-Session-Id header from the response
  3. Re-send the request with that header
  4. Cache the session-ID for future requests
• For torrent list, request these fields:

  id, name, totalSize, downloadedEver, uploadedEver, uploadRatio,
  percentDone, status, eta, error, errorString, doneDate, isFinished,
  rateDownload, rateUpload, peersConnected, peersGettingFromUs, peersSendingToUs,
  peers (array of {address, clientName, progress, isDownloadingFrom, isUploadingTo, rateToClient, rateToPeer})
  

• "Peers with 100%" = count of peers in the peers array where progress === 1.0
• "Finished date" = doneDate (Unix timestamp, 0 means not finished)

Design Requirements (CRITICAL)

• Dark mode only — deep dark background (#0a0a0f or similar)
• Modern, stylish, clean — think Linear, Vercel, Raycast aesthetic
• Accent color: Use a vibrant accent (cyan/teal #00d4ff or purple #8b5cf6)
• Typography: System font stack, -apple-system, Inter-like
• Torrent cards or rows with:
  • Name (truncated with ellipsis if long)
  • Size (human-readable: GB, MB, etc.)
  • Progress bar (animated, smooth)
  • Percentage done
  • Ratio (uploadRatio)
  • Downloaded / Uploaded amounts
  • Download/Upload speeds
  • ETA (when downloading)
  • Status badge (downloading, seeding, paused, finished, error)
  • Finish date (formatted nicely, e.g. "Jul 8, 2026")
  • Peer count with 100% (e.g. "3/7 peers at 100%")
• Auto-refresh every 3 seconds
• Header with app title and global stats (total download/upload speed, torrent count)
• Responsive — works on mobile and desktop
• Use CSS variables for theming
• Smooth transitions and micro-animations
• Cards with subtle borders and hover effects

Code Structure

main.go          — Go backend (HTTP server, Transmission RPC proxy, static file serving via embed)
web/
  index.html     — SPA shell
  app.js         — Frontend logic (fetch API, render, auto-refresh)
  styles.css    — All styling
Dockerfile       — Multi-stage: golang:1.24-alpine (build) → alpine:latest (runtime)
go.mod           — module transmission-manager, go 1.24

Go Implementation Notes

• Use embed package to embed web/ directory into the binary
• Transmission RPC communication via net/http client
• Implement session-ID handshake with retry on 409
• Use sync.Mutex to protect session-ID cache
• Format numbers nicely (human-readable sizes) in the frontend, not backend
• CORS not needed (same origin)
• The Go server should be minimal and fast

Dockerfile

FROM golang:1.24-alpine AS builder
WORKDIR /app
COPY go.mod ./
RUN go mod download
COPY . .
RUN CGO_ENABLED=0 go build -ldflags="-s -w" -o transmission-manager .

FROM alpine:latest
RUN apk add --no-cache ca-certificates
WORKDIR /app
COPY --from=builder /app/transmission-manager .
EXPOSE 8080
CMD ["./transmission-manager"]

Do NOT

• Do not use any Go web framework (gin, fiber, etc.) — stdlib only
• Do not use any JS framework (React, Vue, etc.) — vanilla only
• Do not add authentication
• Do not add CI/CD or GitHub Actions
• Do not create any GitHub repository
• Do not add vendored dependencies
• Do not add tests unless necessary — keep it simple