NeoAgent is a Node.js/Express backend with Flutter clients. Contributions are welcome across the server, clients, integrations, skills, tests, and documentation.
- Search existing issues and pull requests before opening a duplicate.
- Use an issue to discuss large behavior changes before investing in an implementation.
- Keep pull requests focused. Unrelated refactors make review and regression analysis harder.
- Never include credentials, tokens, personal data, runtime databases, or private screenshots in an issue or pull request.
- Follow GUIDELINES.md for repository architecture, naming, security, and style requirements.
Requirements:
- Node.js 20 or newer
- npm
- Flutter stable when changing a Flutter client
Install backend dependencies:
git clone https://github.com/NeoLabs-Systems/NeoAgent.git
cd NeoAgent
npm ciNeoAgent stores development runtime data under ~/.neoagent by default. Set
NEOAGENT_HOME to an isolated directory when you do not want development data
to share the normal runtime.
Run the backend:
npm run dev:backendRun the backend and Flutter web client together:
npm run dev:stackDo not commit generated runtime data or .env files.
Run the smallest relevant test command while developing, then the broader suite before submitting:
npm run test:unit
npm run test:integration
npm run test:security
npm run test:contract
npm run test:e2e
npm run test:ws
npm run test:backendFor Flutter changes:
cd flutter_app
flutter analyze --no-pub
cd ..
npm run flutter:testFlutter web release builds are handled by the maintainer's release pipeline.
Open contributor pull requests against the beta branch, not main. Create a
feature branch in your fork, push your changes there, and select beta as the
base branch when opening the pull request. The main branch is managed by the
stable release workflow and receives promoted changes from beta.
A pull request should:
- Explain the user-visible problem and the chosen fix.
- Include focused tests for changed behavior.
- Call out migrations, configuration changes, security implications, and platform-specific behavior.
- Update documentation when commands, settings, APIs, or user workflows change.
- Pass the repository CI checks.
Maintainers may ask to split a pull request when independent changes can be reviewed and released separately.
Good starting points include:
- Documentation corrections with verified commands or links.
- Focused test coverage for an existing service or route.
- Small accessibility or error-message improvements in the Flutter UI.
- A narrowly scoped messaging or integration fix with a reproducible case.
- A skill improvement that does not depend on phrase-based filtering.
Use the good first issue and help wanted labels to find work that has already
been scoped.
Use the bug report form and include:
- The NeoAgent version or commit.
- Host operating system and Node.js version.
- Install type and runtime profile.
- Exact reproduction steps.
- The relevant error and sanitized logs.
The app may be running on a different server from the machine where you are filing the issue. Identify which host produced each log and redact secrets before posting.