lobehub/AGENTS.md

LobeHub Development Guidelines

This document serves as a comprehensive guide for all team members when developing LobeHub.

Project Description

You are developing an open-source, modern-design AI Agent Workspace: LobeHub (previously LobeChat).

Tech Stack

• Frontend: Next.js 16, React 19, TypeScript
• UI Components: Ant Design, @lobehub/ui, antd-style
• State Management: Zustand, SWR
• Database: PostgreSQL, PGLite, Drizzle ORM
• Testing: Vitest, Testing Library
• Package Manager: pnpm (monorepo structure)

Directory Structure

lobehub/
├── apps/desktop/           # Electron desktop app
├── packages/               # Shared packages (@lobechat/*)
│   ├── database/           # Database schemas, models, repositories
│   ├── agent-runtime/      # Agent runtime
│   └── ...
├── src/
│   ├── app/                # Next.js app router
│   ├── spa/                # SPA entry points (entry.*.tsx) and router config
│   ├── routes/             # SPA page components (roots)
│   ├── features/           # Business components by domain
│   ├── store/              # Zustand stores
│   ├── services/           # Client services
│   ├── server/             # Server services and routers
│   └── ...
├── .agents/skills/         # AI development skills
└── e2e/                    # E2E tests (Cucumber + Playwright)

Development Workflow

Git Workflow

• Branch strategy: canary is the development branch (cloud production); main is the release branch (periodically cherry-picks from canary)
• New branches should be created from canary; PRs should target canary
• Use rebase for git pull
• Git commit messages should prefix with gitmoji
• Git branch name format: feat/feature-name
• Use .github/PULL_REQUEST_TEMPLATE.md for PR descriptions

Package Management

• Use pnpm as the primary package manager
• Use bun to run npm scripts
• Use bunx to run executable npm packages

Code Style Guidelines

TypeScript

• Prefer interfaces over types for object shapes

Testing Strategy

# Web tests
bunx vitest run --silent='passed-only' '[file-path-pattern]'

# Package tests (e.g., database)
cd packages/[package-name] && bunx vitest run --silent='passed-only' '[file-path-pattern]'

Important Notes:

• Wrap file paths in single quotes to avoid shell expansion
• Never run bun run test - this runs all tests and takes ~10 minutes

Type Checking

• Use bun run type-check to check for type errors

i18n

• Keys: Add to src/locales/default/namespace.ts
• Dev: Translate locales/zh-CN/namespace.json locale file only for preview
• DON'T run pnpm i18n, let CI auto handle it

SPA Routes and Features

• src/routes/ holds only page segments (_layout/index.tsx, index.tsx, [id]/index.tsx). Keep route files thin — import from @/features/* and compose, no business logic.
• src/features/ holds business components by domain (e.g. Pages, PageEditor, Home). Layout pieces, hooks, and domain UI go here.
• See the spa-routes skill for the full convention and file-division rules.

Skills (Auto-loaded)

All AI development skills are available in .agents/skills/ directory and auto-loaded by Claude Code when relevant.

IMPORTANT: When reviewing PRs or code diffs, ALWAYS read .agents/skills/code-review/SKILL.md first.