AGENTS.md

AGENTS.md

This file guides LLM agents through interacting with and maintaining the lune project—a CLI for the Lunatask productivity app.

Lunatask concepts

Lunatask is end-to-end encrypted and any sensitive information (person/task/note/habit names, contents, etc.) is all omitted. The API only returns basic metadata (IDs, timestamps, status, etc.). That also means there is no way to dynamically list the user's areas, habits, or notebooks; they must copy those details from the desktop app into lune during interactive initialisation or reconfiguration.

Commands

Run these most to least often:

task fmt lint:fix staticcheck test  # Important ones to run often
task                                # Include vulnerability and copyright checks

The Taskfile auto-installs tools (gofumpt, staticcheck, govulncheck) when running their respective tasks.

Architecture

main.go              → cmd.Execute() entrypoint
cmd/
  root.go            → Root command, registers all subcommands and groups
  init.go, ping.go   → Top-level commands
  add.go, done.go, jrnl.go  → Shortcuts (delegate to resource commands)
  task/              → task add/list/get/update/delete
  note/              → note add/list/get/update/delete
  person/            → person add/list/get/update/delete/timeline
  journal/           → journal add
  habit/             → habit track
internal/
  client/            → Lunatask API client factory (uses system keyring)
  config/            → TOML config at ~/.config/lunatask/config.toml
  ui/                → Lipgloss styles (Success, Warning, Error, Muted, Bold)
  validate/          → Input validation (UUID format)

Command flow: fang.Execute() wraps Cobra with version/commit info and signal handling. Resource commands live in subpackages (cmd/task/); shortcuts in cmd/ delegate to resource commands by calling their RunE directly and copying their flagset.

Command patterns

Resource commands (task, note, person, etc.):

  • Parent command in <resource>.go with GroupID: "resources"
  • Subcommands (add, list, get, update, delete) in separate files
  • Export the *Cmd vars for shortcuts to reference

Shortcuts (add, done, jrnl):

  • Live in cmd/ directly with GroupID: "shortcuts"
  • Copy flags from resource command: addCmd.Flags().AddFlagSet(task.AddCmd.Flags())
  • Call resource command's RunE directly

Shell completions registered inline via RegisterFlagCompletionFunc; see cmd/task/add.go:43-56 for examples. Config-based completions load from config.Load().

Core dependencies

Reference docs via context7 or doc-agent when unsure:

  • git.secluded.site/go-lunatask (context7: /websites/pkg_go_dev_git_secluded_site_go-lunatask): Lunatask API client. Amolith maintains it, so issues can be resolved or missing features added quickly.
  • github.com/charmbracelet/huh (context7: /charmbracelet/huh): powerful and attractive libs for interactive forms and prompts
  • github.com/charmbracelet/lipgloss (context7: /charmbracelet/lipgloss): Terminal styling.
  • github.com/charmbracelet/fang (context7: /charmbracelet/fang): Cobra wrapper with fancy styling, version injection, signal handling.
  • github.com/zalando/go-keyring (context7: /zalando/go-keyring): Cross-platform interface to the system keyring
  • github.com/BurntSushi/toml (context7: /burntsushi/toml): Config file parsing.
  • github.com/spf13/cobra (context7: /websites/pkg_go_dev_github_com_spf13_cobra): CLI framework.

Gotchas

Linter exclusions for cmd/

The .golangci.yaml disables several linters for cmd/:

  • gochecknoglobals, gochecknoinits: Cobra requires package-level vars and init()
  • errcheck, godox: Stub implementations deliberately print without checking, TODOs are placeholders
  • wrapcheck: CLI returns errors for display; wrapping adds noise

These patterns are intentional.

Access token

Read from system keyring via internal/client.New(). No interactive prompts—fail fast with client.ErrNoToken if not configured.

Output formatting

Use cmd.OutOrStdout() and cmd.ErrOrStderr() for testability. Styles are in internal/ui/styles.go—use ui.Success, ui.Error, etc. rather than inline colors.

Testing

Currently stub implementations with // TODO markers. When implementing, use cmd.SetOut() / cmd.SetErr() to capture output.