CodeTurtle

Slow down! Read code.

CodeTurtle evaluates repository policies locally and publishes authenticated CI reports through a BAML service.

frontend/  TypeScript UI
backend/   BAML HTTP service, auth, storage and provider integrations
           crypto.py: Python RS256 signing and verification helper
           tests/: service and crypto integration tests
cli/       BAML policy engine, Python Git adapter and reporting transport,
           fixtures, package metadata and GitHub Action

CLI usage and policy reference · Service configuration and deployment

Install Python 3.10+, Git and BAML 0.20.2-nightly.20261004.a, then:

python3 -m pip install ./cli
codeturtle help
npm --prefix frontend ci
npm --prefix frontend run build

The GitHub Action lives at owner/repo/cli@full-commit-SHA. Build the service image from this directory using backend/Dockerfile. The backend reads the shared report model from cli/baml_src/models.baml.

baml --agent-skill-check off test --directory cli
python3 -m unittest discover -s cli -p test_reporting.py -v
baml --agent-skill-check off test --directory backend
backend/.venv/bin/python -m unittest discover -s backend/tests -p test_crypto.py -v
CODETURTLE_TEST_SQL=/absolute/path/to/operator-handoff.md \
CODETURTLE_TEST_REVIEW_SQL=/absolute/path/to/codeturtle-review-signoffs.md \
  backend/.venv/bin/python -m unittest discover -s backend/tests -p test_service.py -v
npm --prefix frontend run build

The service integration tests use a disposable local PostgreSQL cluster and mocked providers. Secrets belong in the ignored backend/.env or deployment secret store.

Create CODETURTLE.md at the reviewed repository root; see the policy syntax. The PR comment groups requirements by reviewer and links to personal review pages. Reviewers sign in with the isolated WorkOS AuthKit, link their own GitHub identity, and open the original CodeTurtle review workspace. Each owned file gets an explicit Approve or Reject decision; rejections require a reason. Decisions and inline comments remain private drafts until Submit review publishes them atomically. Any/All ownership rules accumulate. Changed files need new decisions; unchanged files retain approvals. Rejections survive new revisions until cleared by their reviewer or a repository administrator with an audited reason. Overrides do not supply approvals.

The frontend ports the existing tools/shep website to TypeScript, preserving its CSS, fonts, turtle artwork, Monaco split/unified diff editor, file tree, comment controls, per-file decisions and review progress. The demonstration identities, fictional PR and simulated-commit controls are replaced by authenticated API data. The ownership tab shows evaluated rule provenance rather than fictional policy.

The CLI evaluator is the original tools/codeturtle engine: contracts.baml, engine.baml, help.baml, lint.baml, main.baml, models.baml and ownership.baml are byte-identical to the source port. Changes surround it: independent packaging/runtime pinning, trusted Git input, root CODETURTLE.md loading, and authenticated CI reporting.

These are CodeTurtle decisions and comments stored in the database. They do not submit native GitHub approvals or enforce branch protection. Slack remains unconfigured. Binary files, files over 1 MB and files outside GitHub's comparison response limit provide a GitHub fallback instead of an incomplete inline diff. Team owners require GitHub API access to verify team membership; individual GitHub handles work without that additional permission.

The additive reviewer database migration must be applied before deploying this workspace. It is supplied separately as the operator SQL handoff. Deployment and publishing the updated GitHub Action are separate from local build/test success.