DivaCode/AGENTS.md

AGENTS.md — DivaCode

Quick start

# build
make build                    # go build -o build/divad ./cmd/divad

# run (llama.cpp server must be on :8080)
make run                      # build + run

# verify
make vet                      # go vet ./...
GONOSUMDB=git.db123.ir GONOSUMCHECK=git.db123.ir GOPRIV=git.db123.ir GOPROXY=https://proxy.golang.org,direct go vet ./...

Architecture

cmd/divad/main.go            # entrypoint: wires agent, llama, companion, TUI, API, scheduler
internal/agent/              # core loop: message → memory search → prompt → llama.cpp → save → respond
internal/agent/scheduler.go  # autonomous tick: mood check, diary write, proactive message
internal/companion/          # orchestrates personality, relationship, reflection, mood, prompt builder
  engine.go                  # BuildPrompt: assembles dynamic prompt from all sub-engines
  personality.go             # 5 bounded traits in SQLite (humor, curiosity, playfulness, formality, affection)
  relationship.go            # familiarity, trust, shared topics, inside jokes
  reflection.go              # diary entries, observations
  promptbuilder.go           # generates dynamic system prompt section
  mood.go                    # mood derivation from recent interaction + energy level
internal/memory/             # RAG store + self-memory (promises, strategies, mistakes)
internal/llama/client.go     # llama.cpp HTTP client (POST /completion, POST /embedding, GET /health)
internal/storage/            # SQLite wrapper, auto-creates data/ directory, auto-migrates on startup
internal/log/handler.go      # custom slog: [LEVEL] [TIME] [FILE:LINE] message key=val
internal/tools/              # MCP tool registry + builtins (web_fetch, web_search stub)
internal/channel/            # Bubble Tea TUI + Matrix adapter (stub)
  tui.go                     # chat UI: viewport + input bar, Ctrl+C/Ctrl+Q to quit
internal/config/config.go    # std lib os.Getenv only (no third-party config libs)
pkg/types/types.go            # Message, Role, Mood, ToolCall types
pkg/personality/traits.go     # TraitValue, RelationshipMetrics, DiaryEntry, Observation types

Key constraints

• Module path: git.db123.ir/db123/divacode — private Gitea. Set GOPRIV=git.db123.ir GONOSUMDB=git.db123.ir GONOSUMCHECK=git.db123.ir GODIRECT=git.db123.ir GOPROXY=https://proxy.golang.org,direct for go mod tidy and go build.
• Database: modernc.org/sqlite (pure Go, no CGO). Schema in internal/storage/migrations.go — 15 tables across two schema groups. data/ dir auto-created on startup.
• llama.cpp: required at runtime, connected via HTTP. Default http://localhost:8080. Agent exits if health check fails.
• Logging: [LEVEL] [TIME] [FILE:LINE] message key=val. Set LOG_LEVEL=DEBUG for verbose output.
• HTTP API: std lib net/http, enabled via API_ENABLED=true. Endpoints: POST /v1/chat, POST /v1/conversations, GET /health.
• TUI quirks: Bubble Tea with tea.WithAltScreen(). Keys: enter to send, backspace to edit, Ctrl+C/Ctrl+Q to quit.
• OpenCode permissions: bash commands need approval (ask mode), git push* and rm -rf* are denied.

Conventions (from "The Holy Code Bible")

Context	Rule
exported Go identifiers	PascalCase
unexported Go identifiers	camelCase
Go file names	snake_case (user_handler.go)
Error wrapping	fmt.Errorf("context: %w", err)
Error checking	always check, no silent discards
Config	env vars only via os.Getenv, never caarlos0/env or similar
HTTP API	std lib net/http only, no third-party routers

Project files layout

cmd/divad/main.go          # single entrypoint
internal/                   # all app logic (unexported)
  agent/                    # two files: agent.go, scheduler.go
  channel/                  # two files: tui.go, matrix.go
  companion/                # six files: engine.go + five sub-engines
  config/                   # one file
  llama/                    # one file
  log/                      # one file
  memory/                   # two files
  storage/                  # two files: sqlite.go, migrations.go
  tools/                    # two files: registry.go, builtin.go
pkg/                        # shared types (exported if needed elsewhere)

Docker

docker compose up -d        # starts divacode agent only (llama.cpp runs externally)

Override variables via .env or environment:

LLAMACPP_URL=http://host.docker.internal:8080 docker compose up