Contributing
Contributing
text-to-cad is MIT-licensed and built in the open. Here is how to take part and where to start.
Ways to take part
- Bugs and plugin requests: open an issue. A bug report with the model script and the output of
cad doctoris the fastest to fix. An agent app without a plugin gets one on request. - Questions, ideas and what you made: the Discord. Say what the skills got wrong too, because that is what improves them.
- Code, skills and models: a new skill goes in
skills/, an example model inmodels/, and fixes go anywhere. - Security problems: report them privately, as SECURITY.md says.
Where the code lives
skills/: the agent skills and their references. The skills are the product.packages/: the published Python distribution,cad(the library, the server and thecadcommand, and the transport an agent app starts ascad mcp), its empty aliases, and the shared JavaScript packages.apps/: the viewer's web client (apps/web), the CAD app (apps/mcp), this documentation site (apps/docs) and the API cad talks to, for the version feed and usage stats (apps/api).models/: example models, each built withpython model.py.tests/: the test suites for the skills, the packages, the viewer and repository-wide policy.docs/: the install guide, the contributing guides and the migration guides.
How the pieces fit together is written for contributors in the repository: AGENTS.md maps the tree and its rules, the engine README covers the server's daemon, its workers, documents and exports, each package's README holds its own laws (start with the library's), and SECURITY.md draws the trust boundary.
Setting up a checkout
Branch from main and open pull requests against main. External contributors fork the repository first. In outline:
- Clone the repository and create a branch.
- Install uv and run
uv sync --python 3.14. - Install Node.js 22 if you work on the viewer, the shared packages or the docs site.
- Run the smallest check that covers your change, such as
scripts/test/test-python.shwith the test paths you changed. - To try skills and the plugin in an agent app, use
scripts/install/dev_install.py, optionally with the apps to install in.
CONTRIBUTING.md has the exact commands, the per-platform set-up and how to test in each agent app. A change that touches the plugin, the skills or the CAD app should keep Claude Code, Codex and Cursor working. An agent working in the repository starts at AGENTS.md.
Releases are made by the maintainers. Do not change VERSION in a normal pull request.
Guides in the repository
These are written for whoever changes the repository, an agent as often as a person, so they live there and open on GitHub.
- Writing a skill: add a workflow for your agent.
- Adding a document type: teach text-to-cad a new kind of file.
- Adding an integration: connect a tool text-to-cad runs for you.
- Testing: the rules for tests, adding one, and reading a red CI run.