Botica

---

Documentation: https://collectiveai-team.github.io/botica/

Source Code: https://github.com/collectiveai-team/botica

---

Botica is a linter and a set of recipes for the repositories of a team.

• botica lint runs rules over the files of a project: the built-in catalog, and the rules that the project writes in .botica/rules/. Each rule checks a written standard. It never calls a model or the network, and it runs as a command, a hook of prek, a job of CI and a language server.
• botica recipe install sets up a repository of some kind: the selection of rules in botica.toml, the hooks of prek, the workflows of GitHub Actions, the agent skills and the lines of .gitignore. It adds what is missing, and a file that exists is not replaced.
• Judgment rules cover what no deterministic check can express. Botica exports them to AGENTS.md and to the rubric of abide, the judge, and filters what the judge reports with the same configuration and comments.

Most rules read Python, TypeScript and JavaScript, a few read Go and Rust, and the rest read the files of any project: their names, their size, the layout of the folders, the commit messages.

Install

Botica is one binary, published on PyPI as the wheel botica. It runs without Python.

uvx botica lint            # run it once, without installing
uv tool install botica     # or keep it installed

From a checkout: cargo build --release -p botica-cli, and the binary is target/release/botica.

Use

botica lint                    # the active rules over the current directory
botica lint --diff origin/main # only the findings on the lines that a branch adds
botica rules --all             # every rule, whether it is active, and why
botica explain no-utils        # what a rule asks, and how it is configured here

botica lint exits with 1 when a finding is an error and with 2 when the run fails. A configuration is botica.toml, or [tool.botica] in pyproject.toml:

select = ["file-size-guard", "no-utils", "log-no-print"]

[rules.file-size-guard]
warn = 500
max = 900

A comment silences one finding, with its reason:

print(report)  # noqa: BTLOG002 -- the output of the command

The guide has every command and key, the baseline of known findings, the editor (Neovim, Helix, Emacs) and the hooks and CI.

Set up a repository

From the root of the repository, with uv and npx on the PATH:

uvx botica recipe install base base-python agent-claude-code ci-python repo-public

Recipe	What it adds
base	any repository: the rules about any file and about lockfiles, the skills, .gitignore, the hooks of prek, the workflow of abide, the sections of AGENTS.md
base-python	a Python project: the rules about Python code and pyproject.toml, the Python hooks and the dev tools
full-python	base-python and ci-python
base-go	a Go module: the rules about Go code, .golangci.yml, golangci-lint and go mod tidy in prek, and govulncheck in the manual stage of prek
full-go	base-go and ci-go
base-rust	a Rust crate or workspace: the rules about Rust code, the cooldown of Cargo, and cargo fmt, clippy and cargo-shear in prek
full-rust	base-rust and ci-rust
base-node	a TypeScript or JavaScript project: the rules about its code, Biome, ESLint for JSDoc, tsc and knip in prek, the cooldown of pnpm, and those packages in package.json
full-node	base-node and ci-node
agent-claude-code, agent-codex, agent-opencode	the configuration and the skills of an agent
ci, ci-python, ci-node, ci-go, ci-rust	the workflows of GitHub Actions for commits and for an ecosystem
repo-public, repo-private	the workflows that fit the visibility of the repository
ci-publish, ci-docker, ci-dependency-review, ci-automerge-public, ci-automerge-private, ci-botica-update, secrets-varlock	one workflow or tool each
iac-terraform	Terraform or OpenTofu: the hooks of , , tflint and trivy, and the workflow that runs them and checkov

botica recipe list prints them with their steps, and botica recipe check says how the repository differs from them. A file that exists is left as it is and reported pending. Commit skills-lock.json afterwards: npx skills experimental_install restores .agents/skills/ from it. Recipes describes each step, and a project adds its own recipes in recipes/.

Extend

A project writes its rules in .botica/rules/<catalog>/, and botica rules new writes the folder of one:

botica rules new structure/no-eval --kind ast-grep --language python --catalog .botica/rules/acme
botica rules conform .botica/rules/acme   # the rule over its fixtures

This is the beginning of the README. Read the rest at the original. Read the full README ↗