Skip to main content

​
Contributing to FERAL

FERAL is building toward an agent-native operating system. That is a large mission and we need help from many kinds of engineers — backend, frontend, ML, hardware, Nix/packaging, and documentation.

​
Development Setup

git clone https://github.com/FERAL-AI/FERAL-AI.git
cd FERAL-AI/feral-core
pip install -e ".[llm,dev]"
feral setup
feral serve    # brain running on localhost:9090
For the web UI (in a separate terminal): 
cd FERAL-AI/feral-client
npm install
npm run dev     # dev server on localhost:5173
Or use Make targets from the repo root: 
make dev        # install all deps
make serve      # brain
make client     # web UI dev server
make test       # run pytest
make help       # list all targets

​
Code Style

​
Python

  • Type hints on all function signatures.
  • Ruff for linting, Black-compatible formatting.
  • Keep functions focused and short. Prefer composition over inheritance.
  • Avoid broad except: blocks — catch specific exceptions.

​
TypeScript / React

  • Strict mode enabled.
  • Prettier for formatting.
  • Functional components with hooks.

​
General

  • No commented-out code in PRs.
  • Comments explain why, not what.
  • New features should include tests.

​
Testing

# Unit + integration tests
pytest

# With coverage report
pytest --cov --cov-report=term

# Target: 70% coverage minimum
Test files live in feral-core/tests/. Use pytest-asyncio for async tests — the asyncio_mode = "auto" config handles the event loop.

​
Pull Request Process

  1. Fork the repository and create a feature branch: 
    git checkout -b feat/my-feature
  2. Write tests for new functionality.
  3. Run the test suite and ensure it passes: 
    pytest
  4. Open a PR against main with a clear title and description:
    • What changed and why.
    • How to test the change.
    • Screenshots for UI changes.
  5. One approval from a maintainer is required to merge.

​
Contributor Lanes

Pick the area that matches your skills:
LaneWhat You’d Work OnEntry Points
Runtime / OrchestratorAgent loop, LLM routing, TaskFlows, sessions, securityferal-core/agents/
Memory / Knowledge4-tier memory, wiki compilation, ingest pipelines, federated syncferal-core/memory/
GenUI / Provider SurfacesSDUI engine, provider contracts, surface caching, client rendererferal-core/genui/, feral-client/src/components/SduiRenderer.jsx
Hardware / DaemonsHUP protocol, daemon SDKs, device profiles, edge bridgesferal-core/hardware/, feral-nodes/
Voice / PerceptionRealtime voice, Gemini Live, wake word, vision pipelineferal-core/voice/, feral-core/perception/
Nix / PackagingFlake outputs, NixOS modules, reproducible buildsflake.nix
Frontend / ShellWeb UI, dashboard, Tauri desktop, mobile bridgesferal-client/, desktop/
DocumentationGuides, API reference, architecture docsdocs/

​
Architecture Docs

Before diving in, read these to understand the system:

​
Reporting Issues

Open an issue at github.com/FERAL-AI/FERAL-AI/issues with:
  • Steps to reproduce.
  • Expected vs actual behavior.
  • Python version, OS, and feral --version output.

​
Contact

Alpay Kasal — info@feral.io