freya/AGENTS.md

AGENTS.md

Project

FREYA is an AI-powered personal assistant that aggregates data from various sources into a contextual feed. Monorepo with packages/ (shared libraries) and apps/ (applications).

Commands

• Install: bun install
• Test: bun test (run in the specific package directory)
• Lint: bun run lint
• Format: bun run format
• Type check: bun tsc --noEmit

Use Bun exclusively. Do not use npm or yarn.

Code Style

• File names: kebab-case (data-source.ts)
• Prefer function declarations over arrow functions
• Never use any - use unknown and narrow types
• Enums: use const objects with corresponding types:

  const Priority = {
  	Low: "Low",
  	High: "High",
  } as const
  type Priority = (typeof Priority)[keyof typeof Priority]
  

• File organization: types first, then primary functions, then helpers

Before Committing

1. Format: bun run format
2. Test the modified package: cd packages/<package> && bun test
3. Fix all type errors related to your changes

Git

• Branch: feat/<task>, fix/<task>, ci/<task>, etc.
• Commits: conventional commit format, title <= 50 chars

Nix

Use the Nix dev shell for project commands by default.

• Run repo tooling through nix develop -c, e.g. nix develop -c bun test.
• Use Bun exclusively inside the Nix shell.
• Do not use host bun, node, tsc, or package binaries for project tasks unless explicitly checking host behavior.
• Simple inspection commands like rg, sed, ls, and git status may run outside Nix.
• While flake.nix is untracked, use nix develop path:. -c <command>.