Developer Guide
Who This Is For
If you're reading this, you're probably:
- A developer who wants to contribute tools, features, or fixes
- Someone evaluating the codebase before deciding to contribute
- Me, six months from now, trying to remember why I made certain decisions
This guide assumes you're comfortable with Python and/or TypeScript. You don't need to be an expert in React, FastAPI, or Polars - but you should know your way around a terminal and a debugger.
Why Contribute?
A few honest reasons:
-
You'll actually use it. The best contributors are users who hit a limitation and fix it themselves.
-
The codebase is approachable. Domain-driven design means most changes are localized. Adding a tool doesn't require understanding the whole system.
-
It's AGPL-3.0. Your contributions remain open forever. No bait-and-switch to proprietary.
-
The maintainer (hi) is responsive. I review PRs, answer questions, and value good-faith contributions.
Where to Start
| Goal | Start Here |
|---|---|
| Set up your dev environment | Getting Started |
| Understand how things fit together | Architecture Overview |
| Add a new tool | Adding Tools |
| Fix a bug | Contributing Workflow |
| Run the test suite | Testing Philosophy |
| Build a release | Packaging |
Communication
- Bug reports: GitHub Issues
- Feature discussions: GitHub Discussions
- Questions: Open an issue or discussion. I prefer public channels so answers help others
Guiding Principles
These show up throughout the codebase and documentation:
- Ship, then polish. Working software beats perfect plans.
- Test the bones, not the skin. Core logic gets heavy testing; UI gets light testing.
- Explicit over magic. Configuration and behavior should be predictable and traceable.
- Every feature has maintenance cost. Say no to scope creep.
- Honest documentation. If something's broken, say so. If a decision was a tradeoff, explain why.
Ready to dive in? Start with Getting Started.