Contributing

Bestie is early. The best contributions are focused, tested, and easy to review.

Before you start

1. Read the README for current status and scope.
2. Read the security and privacy rules before touching secrets, logs, memory, Telegram, MCP, or tool execution.
3. Check existing issues and discussions to avoid duplicate work.
4. For larger changes, open an issue or discussion before writing a big PR.

Local setup

npm ci
npm run build
npm test

Run the CLI locally:

bestie --help
bestie onboard
bestie doctor
bestie chat

Pull request expectations

A good PR should:

• Solve one clear problem.
• Include tests for behavior changes.
• Update docs when user-facing behavior or config changes.
• Keep secrets out of code, logs, screenshots, fixtures, and test output.
• Avoid unrelated formatting churn.
• Explain validation in the PR description.

Architecture guidelines

• Keep CLI command files thin; put reusable behavior in runtime services.
• Keep character behavior data-driven through editable character and prompt files.
• Keep OpenAI-compatible providers configurable by baseUrl, model, and apiKeyEnv.
• Treat external content as untrusted.
• Do not enable broad write, destructive, or public actions without explicit permission checks and tests.

Testing

Run focused tests while developing, then run:

npm run build
npm test

If relevant, also run:

npm run smoke
npm run eval:character

Do not run real Telegram smoke in normal CI or PR validation. It requires explicit local setup and fresh owner messages.

Commit style

Use clear, imperative commit subjects:

Add Telegram attachment size validation
Fix provider timeout error mapping
Document local memory export flow

Maintainers may ask for smaller PRs, tests, docs updates, or safety notes. That is normal for a project handling private data and provider credentials.