transmission-manager/AGENTS.md

Transmission Manager - Agent Guide

First Rule

Always read project-context.md before making code or documentation changes. If a change alters project purpose, architecture, APIs, file roles, workflows, constraints, or implementation patterns, update project-context.md in the same change.

Quick Summary

Transmission Manager is a lightweight single-binary Go web app for managing and viewing torrents in a Transmission RPC client. It serves a dark-mode vanilla HTML/CSS/JS SPA and proxies Transmission RPC calls through a minimal Go backend.

Stack

• Backend: Go 1.24, standard library only.
• Frontend: Vanilla HTML, CSS, and JavaScript. No framework or build step.
• Static assets: embedded with Go embed from web/.
• Runtime port: 8080.
• Container: multi-stage Docker build from golang:1.24-alpine to alpine:latest.

Current Files

• project-context.md - canonical project context and implementation rules for agents.
• main.go - HTTP server, embedded static file serving, environment-driven Transmission RPC client, connection warning page, API routes.
• web/index.html - SPA shell and toolbar controls.
• web/app.js - frontend state, polling, in-place rendering, sorting, pause/resume actions.
• web/styles.css - dark-only UI theme and responsive layout.
• go.mod - module transmission-manager, Go 1.24.
• Dockerfile - production container build.

Core API Surface

• GET / serves a Transmission connection warning page when setup fails; otherwise it serves the embedded frontend.
• GET /api/torrents returns Transmission torrent data.
• GET /api/stats returns global session stats.
• POST /api/torrents/{id}/pause maps to Transmission torrent-stop.
• POST /api/torrents/{id}/resume maps to queue-respecting Transmission torrent-start.

Implementation Guidelines

• Keep the backend stdlib-only. Do not add Gin, Fiber, Chi, Gorilla, or other Go web frameworks.
• Keep the frontend dependency-free. Do not add React, Vue, Svelte, bundlers, package managers, or transpilers.
• Preserve the single-binary model: static frontend files should remain embedded via embed.
• Format display numbers in the frontend unless there is a clear backend reason.
• Preserve in-place frontend updates during polling. Do not replace the whole torrent list on each refresh.
• Keep polling lightweight and avoid overlapping refresh requests.
• Keep UI dark-only, modern, compact, responsive, and based on CSS variables.

Transmission RPC Notes

• Default RPC URL: http://192.168.20.22:3210/transmission/rpc.
• Override the RPC URL with TRANSMISSION_URL.
• Optional HTTP Basic Auth credentials come from TRANSMISSION_RPC_USERNAME and TRANSMISSION_RPC_PASSWORD; unset, empty, or literal null values mean no credential value.
• Handle the Transmission session-ID handshake:
  1. POST to the RPC URL.
  2. If the response is 409, read X-Transmission-Session-Id.
  3. Retry the same request with that header.
  4. Cache the session ID behind a mutex.
• "Peers at 100%" means count peers[] entries where progress === 1.0.
• doneDate is a Unix timestamp; 0 means unfinished.

Do Not

• Do not add authentication unless explicitly requested.
• Do not add CI/CD or GitHub Actions.
• Do not create a GitHub repository.
• Do not vendor dependencies.
• Do not add broad tests or infrastructure for small changes; keep verification proportional.