This is the bet.
Come build it with us.
Most AI is built to remember you. We're building something rarer — and harder: an AI that's truly understood you. It's in beta and open from the first line. If that's a bet worth making, there's room for you here.
What we believe
Your data, memory, and identity remain on your machine. Nothing leaves your environment without your explicit knowledge.
Chalie prepares actions, explains them, and asks for approval before executing anything consequential.
Designed with security from the ground up. Secure patterns are the path of least resistance.
Fully open source under Apache 2.0. Every Skill is part of the core — readable, forkable, and improvable by anyone.
If you can use a phone, you can use Chalie. Complexity belongs in the implementation, not the experience.
Why we're building this
We believe your attention is the most precious thing you have — and the only honest way to protect it is to be truly understood, not merely remembered. So we're building something that works to understand you the way a trusted person does: it forms a sense of what matters, forgets what doesn't, and earns — slowly, provably — the right to act on your behalf. So one day you can stop managing your life and get back to living it.
A yes-man is just a faster way to be wrong. Chalie pushes back. That's the bet — and it's open from the first line of code.
Issues matter as much as code
Opening an issue for a feature you need, or reporting a bug you found, is just as valuable as — often more valuable than — a code contribution. A well-described problem is half the solution.
How the project is organized
Chalie is a Python backend paired with a set of self-contained web apps. Knowing where things live makes your first contribution much faster.
Service-oriented Python
A single entry point boots everything — SQLite initializes itself, and no external services are required to run locally.
backend/
├── services/ # Business logic and service classes
├── workers/ # Background worker threads
├── api/ # REST API + WebSocket blueprints
├── configs/ # Configuration files
├── data/ # SQLite database (auto-created)
├── prompts/ # LLM prompt templates
├── tests/ # Test suite
├── schema.sql # Database schema
└── run.py # Single entry pointSelf-contained TypeScript apps
The frontend is a set of independent TypeScript applications. Each directory is self-contained — keep interface code inside the app it belongs to rather than spreading it elsewhere.
frontend/interface/ # Main chat interface
frontend/brain/ # Admin / cognitive dashboard
frontend/on-boarding/ # Account setup wizardGet it running locally
SQLite auto-initializes and no external services are required, so you can be up and running in a couple of commands.
Install dependencies
uv pip install --system -e backend/ # all dependencies, voice (TTS/STT/VAD) includedThere's nothing to configure by hand — runtime settings live in the Brain interface.
Run it
# Start everything (SQLite auto-initializes, no external services required)
./run.sh
# Custom port
./run.sh --port=9000Everything runs as a single process and logs to stdout, which keeps debugging simple. The SQLite database lives at data/chalie.db — inspect it with the sqlite3 CLI any time.
New to Chalie? The installation guide walks through a full setup, and getting started covers connecting a model provider.
Running tests
Tests run with no external dependencies. Before you push, make sure the unit suite is green.
# The pre-merge gate — run this before you push
cd backend && pytest -m unit -q
# Run the full suite
pytest
# Verbose output
pytest -v
# A specific test file
pytest tests/test_file.pycd backend && pytest -m unit -q must pass. It's fast, deterministic, and needs nothing external — there's no excuse to skip it.
What needs a test
Ship with tests that exercise the behavior you added.
Include a test that reproduces the bug, so it can't quietly come back.
Existing tests must still pass — that's how you know behavior held.
Code style
Keep it readable and consistent with what's already there.
- Python: Follow PEP 8.
- TypeScript: Follow standard ES2022+ / TypeScript conventions.
- Documentation: Keep docstrings clear and concise.
- Comments: Explain the why, not the what.
Adding to Chalie
The codebase has a few well-worn paths. Following them keeps new work consistent with the rest of the system.
A new REST API endpoint
- Create a blueprint in
backend/api/my_endpoint.py. - Register it in
backend/api/__init__.py. - Add auth with the
@require_sessiondecorator. - Test it with curl or a REST client.
A new service
- Create
backend/services/my_service.py. - Implement a class with a clear public interface.
- Add tests in
backend/tests/test_my_service.py. - Register it in
run.pyif it needs background execution.
A new background worker
- Create
backend/workers/my_worker.pyextendingWorkerBase. - Implement the worker's main loop.
- Register it in
run.pyas a daemon thread. - Add integration tests.
A change to the web interface
- Keep changes inside the frontend app they belong to.
- Keep styling in the app's CSS and logic in its TypeScript files.
- Design mobile-first and responsive.
- Test across multiple device sizes — and both light and dark themes.
Want to add a capability instead of plumbing? Chalie's abilities are part of the core — readable, forkable, and improvable; reusable playbooks (Skills) are documented in the guide at /guide/skills/. The architecture docs are the best map of how the pieces fit together.
Submitting your changes
Fork, branch, and open a pull request. Clear commits and a green test run make review quick.
- Create a feature branch:
git checkout -b feature/your-feature. - Make focused commits with clear messages.
- Run the tests locally —
cd backend && pytest -m unit -qmust pass. - Push your branch:
git push origin feature/your-feature. - Open a pull request describing what changed and why.
A note on config & secrets
Chalie has no .env files and no environment-variable configuration. Code-level config is Python constants; everything a user would change at runtime is a setting in the Brain interface. Secrets auto-generate on first run — never commit API keys or credentials.
Keep the guardrails intact
Chalie acts on people's behalf, so safety isn't a feature — it's the contract. When you change the system, keep these guarantees true.
- Data stays scoped. Queries are scoped to their topic — no cross-topic leakage.
- Approval before consequence. Chalie prepares actions, explains them, and asks before doing anything consequential.
- Operational limits hold. Hard timeouts, budgets, and cooldowns exist on purpose — don't quietly remove them.
- Local-first. Nothing should leave a person's environment without their explicit knowledge.
Be kind, be patient, and assume good faith. We're building something hard, in the open, and the best contributions start with a conversation. If you're unsure where to begin, look for an existing pattern in similar files, open an issue, or start a discussion — someone will help you find your footing.