openagent CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Commands

Backend (Go)

go build                    # build backend binary
go run main.go              # run backend (port 14000)
go test ./...               # run all tests
go test ./object/... -run TestFoo  # run a single test

Frontend (React)

cd web && yarn install
yarn start                  # dev server on port 13001
yarn build                  # production build (output goes to web/build, then copied to static/)
yarn lint:js                # lint JS

Full production build uses build.sh which cross-compiles for linux/amd64, linux/arm64, linux/riscv64.

Backend serves the frontend as embedded static files (embed.go); during development the frontend proxy is configured to hit localhost:14000.

Architecture

Backend (Go / Beego)

Module: github.com/the-open-agent/openagent

The backend is a standard Beego MVC app. Every entity follows the same three-layer pattern:

1. object/<entity>.go — struct definition (xorm tags for DB), and all DB access functions: GetGlobal<Entities>, Get<Entity>Count, GetPagination<Entities>, Get<Entity>, Add<Entity>, Update<Entity>, Delete<Entity>. The primary key is always (Owner string, Name string). Use util.GetId(owner, name) / util.GetOwnerAndNameFromIdWithError(id) for composite key serialization.

2. controllers/<entity>.go — Beego controller methods wired to routes. Standard set: GetGlobal<Entities>, Get<Entities>, Get<Entity>, Add<Entity>, Update<Entity>, Delete<Entity>. Use c.IsAdmin() / c.IsGlobalAdmin() / c.RequireSignedIn() for auth. Paginated list APIs accept p, pageSize, field, value, sortField, sortOrder query params and use pagination.SetPaginator.

3. routers/router.go — beego.Router calls grouped by entity (all routes for the same entity's CRUD kept together). No alphabetical ordering within a group. New entity routes should be inserted next to their entity's existing routes (not appended to the end of the file).