Skip to content
/docs/contributing

Developers

Contributing to Levix

From your first fork to a review-ready pull request.

Levix is open source under the MIT license. Bug fixes, documentation improvements, tests and focused features are welcome. This walkthrough follows the bot repository's CONTRIBUTING.md; that file is the source of truth if the process changes.

Official contributing rules ↗Issues ↗Pull requests ↗Project architecture (AGENTS.md) ↗

Before you start

  1. Search open issues and pull requests so you do not duplicate existing work.
  2. For a large feature, a change in architecture or a behavior change, open an issue and agree on the approach first. Small fixes and docs changes can go straight to a pull request.
  3. Do not publish a security vulnerability in a public issue. Follow the private disclosure process in SECURITY.md.
Security policy ↗

Fork and set up locally

You need Git, Node.js 24 or newer, and npm. Fork Abdodiab2005/levix on GitHub, then clone your fork (replace YOUR_USERNAME below). Start from an up-to-date main branch and work on a focused feature branch.

Clone and install
git clone https://github.com/YOUR_USERNAME/levix.gitcd levixgit remote add upstream https://github.com/Abdodiab2005/levix.gitgit switch -c fix/describe-your-changenpm cinpm run build:frontendnpm run dev

Make a focused change

  • For new commands, read Developers → Add a command; include bilingual English and Arabic help and replies, and follow the existing command loader contract.
  • For backend and database changes, read Developers → How the code fits together and AGENTS.md. Keep SQLite as the source of truth and mutable state inside the data directory.
  • Preserve headless mode without a listening web server, existing paired sessions, and compatibility with npm, Docker, systemd and standalone binaries.
  • Add or update regression tests for changed behavior. Document any visible behavior change in README.md or SETUP.md.

Verify before opening a PR

Required checks
npm testnpm run lint

For panel UI changes, also run npm run build:frontend. Fix failures caused by your patch, but avoid unrelated formatting or dependency updates. The automated checks do not replace a short manual verification of the affected feature.

Open a pull request

  1. Commit the smallest coherent change with a descriptive message.
  2. Push your feature branch to your fork, then open a pull request against Abdodiab2005/levix:main.
  3. Explain the problem, why you chose this solution, how you verified it and any migration or backward-compatibility considerations.
  4. Check that the PR includes no credentials, local data, unrelated generated files, or unnecessary changes. Address review feedback on the same branch.
git add <changed-files>git commit -m "fix: describe the change"git push -u origin fix/describe-your-change
Open a pull request on GitHub ↗View existing PRs ↗