Skip to content

agent.md

Latest commit

 

History

History
82 lines (58 loc) · 2.87 KB

agent.md

File metadata and controls

82 lines (58 loc) · 2.87 KB
Raw

bpr

Better Beeper CLI for Agents

Stack

  • Go 1.24; one dependency — the Beeper SDK github.com/beeper/desktop-api-go/v5, isolated in internal/beeper
  • CLI: hand-rolled dispatch in internal/cli, stdlib flag per subcommand
  • Tooling: go vet, gofmt, go test

Commands

Use just as the task runner:

  • just check — run all checks (just-fmt-check + loc-check + dir-check + fmt-check + lint + test)
  • just lint — go vet ./...
  • just fmt — format with gofmt
  • just fmt-check — fail if any file is unformatted
  • just test — go test ./...
  • just smoke — live smoke test against Beeper Desktop (needs BEEPER_ACCESS_TOKEN)
  • just run -- <args> — run the CLI
  • just build — go build ./...
  • just build-release — stripped release binary into bin/
  • just loc-check — check file lengths (thresholds in .quality.json)
  • just dir-check — check files per directory (thresholds in .quality.json)
  • just just-fmt-check — verify Justfile formatting
  • just update-scaffold — pull updates from the cookiecutter template

Project Structure

main.go              # thin entry: builds the registry, calls cli.Main
internal/cli/        # dispatch, global flags, help, error→exit
internal/command/    # one package per verb-group (chats, messages, count, open, pick, send, takeout, accounts, contacts, doctor, config, upgrade, agent, watch, auth, meta)
internal/beeper/     # SDK adapter (only SDK importer) + beepertest fake
internal/...         # domain, ids, render, primer, apperr, settings, authcache (see CLAUDE.md)
go.mod / Justfile    # module config / task runner

Conventions

  • Stdlib-first; add dependencies only with a reason (go get + go mod tidy)
  • main stays thin; logic lives in functions returning error
  • Keep functions small (5-10 lines target, 20 max)
  • Prefer explicit, readable code over cleverness
  • Handle errors at boundaries; let unexpected errors surface (no silent _)

Agent

Verify Loop

Run after every change: just check

Runs: just-fmt-check + loc-check + dir-check + fmt-check + lint + test.

Step-by-step alternative:

  1. just fmt
  2. just lint
  3. just test

Auto-fixable

  • gofmt -w . — format all Go files
  • go mod tidy — sync go.mod/go.sum with imports

Common Tasks

  • Add a global flag: parse in internal/cli/globals.go, add to Globals, thread through Deps
  • Add a subcommand flag: a flag.NewFlagSet inside the command's run<Sub> (e.g. chats stale --days, auth login --ttl)
  • Add a dependency: go get <module> then go mod tidy
  • Add a package: new dir with package <name>, import via module path

Testing

  • Test files: *_test.go next to the code, func TestXxx(t *testing.T)
  • Run a single test: go test -run TestName ./...

Boundaries

  • Do not deploy, publish, or push
  • Do not add dependencies or edit go.mod's module path without asking