DayMug

Imported from DayMug/DayMug (AGENTS.md). Install upstream with npx skills add DayMug/DayMug. Copyright stays with the author.

AGENTS.md

Thin index for coding agents and contributors. Per-topic detail lives in docs/ — load on demand.

Project

DayMug is a multi-user web chat interface for code-CLI agents. A Go backend (Gin + SQLite, single static binary) spawns and supervises agent child processes; a Vue 3 SPA drives them over WebSockets. Each conversation is keyed by a persistent session id and bound to one backend for its lifetime.

Two provider families ship today — Anthropic Claude (claude, claude-compatible) and OpenAI Codex (codex, openai-compatible) — each run over a structured transport (Claude Agent SDK / Codex app-server) or the CLI, all implementing agent.Backend (backend/internal/agent/). Shared runtime collaborators (backends, pool, sandbox, dispatcher, …) live in service.Runtime, assembled once in handler/runtime.go; per-conversation provider routing is service.BackendRegistry.For; per-account credentials and concurrency in service.Pool. Product context: FEATURES.md, README.md.

Layout: backend/ (Go), frontend/ (Vue 3 + TS + Vite + Tailwind + shadcn-vue, pnpm), docs/ (deep dives).

Installing frontend dependencies

Run pnpm install from frontend/, never from the repo root:

cd frontend && pnpm install

pnpm is usually a corepack shim that picks its version from the nearest package.json. Outside frontend/ there is none, so pnpm install --dir frontend runs corepack's bundled pnpm 7, which cannot read lockfileVersion: 9 and would re-resolve every dependency into a rewritten lockfile. engines.pnpm rejects that pnpm, and frontend/.npmrc sets frozen-lockfile=true so no plain install can mutate the lockfile. Adding a dependency goes through pnpm add (it ignores the flag) or an explicit pnpm install --no-frozen-lockfile.

Verification commands

Inner loop while iterating: ./scripts/test.sh fast (repo root) runs the backend suite and the fast frontend projects in parallel. Before reporting completion or opening a pull request, run the full per-layer pipelines below.

Backend (from backend/):

go build ./...
go test ./...
golangci-lint run

Frontend (from frontend/):

pnpm build               # vue-tsc + production build
pnpm test                # Vitest
pnpm lint                # ESLint --fix
pnpm api-contract:check  # TS interfaces vs the Go contract snapshot

.github/workflows/ci.yml runs the same pipelines on every pull request, every push to main (merges included) and every release tag.

A failure that looks like a tooling bug but isn't:

• pnpm api-contract:check is the frontend half of the anti-drift pair. It reads backend/internal/store/contract.golden.json (written by the Go snapshot test) and compares the JSON field names and optionality the Go structs emit against the hand-written TS interfaces — never types, because the frontend narrows them on purpose. When you intentionally change a Go response struct, regenerate the golden and update the matching TS interface; doing only the first just moves the failure from the Go test to the TS check.

  cd backend && go test ./internal/store -run TestAPIContractSnapshot -update-contract

Workflow rules

• Verify the touched layer(s) after every change — backend → backend pipeline, frontend → frontend pipeline, full-stack → both. Don't report completion until green.
• Write a test alongside the change. Go: foo_test.go next to foo.go, same package (stdlib testing + httptest). Frontend: Foo.test.ts next to Foo.vue (vitest + @vue/test-utils + happy-dom). One behaviour per test; table-driven in Go when inputs naturally vary.
• On failure: read the error, fix the root cause, re-run the full pipeline. Never suppress, skip, or comment out a failing check.
• Only commit when the pipeline is green. Messages describe what + why, not how.
• Releases are cut by maintainers (tag pushes publish a GitHub Release and move the self-upgrade pointer); see RELEASING.md. Don't push tags.

Code style

• Go: tabs, gofmt/goimports with local prefix github.com/DayMug/DayMug. Module: github.com/DayMug/DayMug/backend.
• Frontend: 2-space indent, ESLint + Prettier, strict TypeScript (noUnusedLocals, noUnusedParameters).
• Comments explain why, not what. Don't restate what well-named identifiers say.
• Tests must not depend on the host filesystem outside t.TempDir() or on network endpoints other than httptest.Server.

Detail docs — read on demand

Start from docs/README.md (it indexes everything below); load a row only when the task touches that area.

Impact analysis

• Before changing an exported or cross-package symbol (function signature, struct field, route, WebSocket message), find every caller and update them in the same change. The compiler catches Go call sites; JSON field names, route strings, and frontend consumers it does not.
• Before committing a multi-file change, read git diff --stat main...HEAD and confirm nothing outside the intended scope moved.
• Renames are find-and-replace plus a full build of both layers — there is no rename tooling here.