chatwoot/AGENTS.md

Chatwoot Development Guidelines

Build / Test / Lint

• Setup: bundle install && pnpm install
• Run Dev: pnpm dev or overmind start -f ./Procfile.dev
• Lint JS/Vue: pnpm eslint / pnpm eslint:fix
• Lint Ruby: bundle exec rubocop -a
• Test JS: pnpm test or pnpm test:watch
• Test Ruby: bundle exec rspec spec/path/to/file_spec.rb
• Single Test: bundle exec rspec spec/path/to/file_spec.rb:LINE_NUMBER
• Run Project: overmind start -f Procfile.dev

Code Style

• Ruby: Follow RuboCop rules (150 character max line length)
• Vue/JS: Use ESLint (Airbnb base + Vue 3 recommended)
• Vue Components: Use PascalCase
• Events: Use camelCase
• I18n: No bare strings in templates; use i18n
• Error Handling: Use custom exceptions (lib/custom_exceptions/)
• Models: Validate presence/uniqueness, add proper indexes
• Type Safety: Use PropTypes in Vue, strong params in Rails
• Naming: Use clear, descriptive names with consistent casing
• Vue API: Always use Composition API with <script setup> at the top

Styling

• Tailwind Only:
  • Do not write custom CSS
  • Do not use scoped CSS
  • Do not use inline styles
  • Always use Tailwind utility classes
• Colors: Refer to tailwind.config.js for color definitions

General Guidelines

• MVP focus: Least code change, happy-path only
• No unnecessary defensive programming
• Break down complex tasks into small, testable units
• Iterate after confirmation
• Avoid writing specs unless explicitly asked
• Remove dead/unreachable/unused code
• Don’t write multiple versions or backups for the same logic — pick the best approach and implement it
• Don't reference Claude in commit messages

Project-Specific

• Translations:
  • Only update en.yml and en.json
  • Other languages are handled by the community
  • Backend i18n → en.yml, Frontend i18n → en.json
• Frontend:
  • Use components-next/ for message bubbles (the rest is being deprecated)

Ruby Best Practices

• Use compact module/class definitions; avoid nested styles

Enterprise Edition Notes

• Chatwoot has an Enterprise overlay under enterprise/ that extends/overrides OSS code.
• When you add or modify core functionality, always check for corresponding files in enterprise/ and keep behavior compatible.
• Follow the Enterprise development practices documented here:
  • https://chatwoot.help/hc/handbook/articles/developing-enterprise-edition-features-38

Practical checklist for any change impacting core logic or public APIs

• Search for related files in both trees before editing (e.g., rg -n "FooService|ControllerName|ModelName" app enterprise).
• If adding new endpoints, services, or models, consider whether Enterprise needs:
  • An override (e.g., enterprise/app/...), or
  • An extension point (e.g., prepend_mod_with, hooks, configuration) to avoid hard forks.
• Avoid hardcoding instance- or plan-specific behavior in OSS; prefer configuration, feature flags, or extension points consumed by Enterprise.
• Keep request/response contracts stable across OSS and Enterprise; update both sets of routes/controllers when introducing new APIs.
• When renaming/moving shared code, mirror the change in enterprise/ to prevent drift.
• Tests: Add Enterprise-specific specs under spec/enterprise, mirroring OSS spec layout where applicable.