Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Working with AI agents

AI coding agents work on claudius the way people do: on a branch, through a pull request with a Conventional Commit title, with cargo xtask ci run before every push. Everything after that runs on GitHub and is driven with gh, so an agent can take a change from a branch to a published release, and a person can follow every step in the web interface.

Agents read AGENTS.md at the root of the repository. This page shows the same text, so the rules for people and for agents cannot drift apart. Releasing explains what each release step does.

Rules

  • Never work on main. Make a branch named <type>/<topic>, where the type is the kind of change: feat/euclid-patterns, fix/render-error-session, docs/swing-chapter. Branches named release/* and hotfix/* belong to the release process; do not make them unless you were asked to release.
  • Every change goes in through a pull request whose title is a Conventional Commit, because the title becomes the commit on main and the line in the changelog: feat(script): add euclid() to patterns. The type is one of feat, fix, docs, refactor, perf, test, build, ci, chore; a ! after it marks a breaking change (feat(api)!: rename /api/state). Write it for someone reading the changelog.
  • Run cargo xtask ci before you push. It runs formatting, clippy with warnings as errors (also on the builds without the ears or the studio window), the tests and the examples in the docs, which is what CI checks first. Fix what it finds. If you touched the docs, the site, dependencies or workflows, run the matching checks from docs/src/contributing/setup.md too.
  • Keep the skills in step. skills/ teaches assistants the MCP tools, the commands and the script language. A change to a tool, a command, a message or a function they quote changes the skill in the same pull request; their examples run with the docs examples.
  • Keep the two features apart. Code that needs earshot goes behind #[cfg(feature = "ears")], code that needs the native window behind studio. The Intel Mac and Windows builds have no ears, and the headless Linux build has no window, so both have to keep compiling.
  • Leave rust-toolchain.toml and the workflows’ ubuntu-24.04 alone in a change of your own. Moving to a newer Rust or a newer Ubuntu is a pull request of its own, with the lints the new clippy brings or the fixes the new image needs.
  • Keep a pull request to one change, and describe in it how you checked it.
  • Notes for the changelog that need more than the PR title (an upgrade step, a highlight) go under ## [Unreleased] in CHANGELOG.md, in the same pull request.

Commands

Make a change and open a pull request:

git switch -c feat/euclid-patterns
# edit, then
cargo xtask ci
git add -A && git commit -m "feat(script): add euclid() to patterns"
git push -u origin HEAD
gh pr create --title "feat(script): add euclid() to patterns" --body "What changes, why, and how I checked it."

Watch the checks, and let GitHub merge once the required check, ci ok, passes:

gh pr checks --watch
gh pr merge --auto --squash

If a check fails, read its log (gh run view <run id> --log-failed), fix the cause on the same branch, and push again.

Release, only when the person you work for asks for it:

gh workflow run release-pr.yml -f bump=minor      # or patch, major, or an exact version such as 0.4.0
gh run list --workflow release-pr.yml --limit 1   # the run; `gh run watch <id>` follows it
gh pr view release/v0.4.0                          # the release PR, "release: v0.4.0"; read its notes
gh pr checks release/v0.4.0 --watch                # if no checks appear: gh workflow run ci.yml --ref release/v0.4.0
gh pr merge release/v0.4.0 --squash                # this publishes the release

Then check what was published:

gh run list --workflow release.yml --limit 1       # `gh run watch <id>` until it finishes
gh release view v0.4.0
gh release download v0.4.0 --pattern 'claudius-0.4.0-aarch64-apple-darwin.tar.gz' --pattern SHA256SUMS
shasum -a 256 --check --ignore-missing SHA256SUMS
gh attestation verify claudius-0.4.0-aarch64-apple-darwin.tar.gz --repo devlato/claudius \
  --signer-workflow devlato/claudius/.github/workflows/release.yml --source-ref refs/heads/main
gh release download v0.4.0 --pattern install.sh --pattern SHA256SUMS --clobber && shasum -a 256 --check --ignore-missing SHA256SUMS

Never

  • Push to main or force-push it, or rewrite its history.
  • Get a check to pass by going around it: no --no-verify, no #[allow(...)], #[ignore] or deleted assertions to silence a failure, no edits to workflows or deny.toml that drop a failing check. If a check is wrong, say so in the pull request.
  • Commit secrets, tokens, .env files, downloaded models or sample packs, or anything from target/ and out/.
  • Change the version in Cargo.toml, the released sections of CHANGELOG.md, or v* tags by hand. Versions change only through the release PR that release-pr.yml opens.
  • Start a release or merge a release PR without being asked to.