tools-only Linting & Formatting Setup
Hive uses Ruff for all Python linting and formatting. This document explains the tooling, how to set it up locally, and what happens in CI.
Quick Setup
# 1. Install dev dependencies
cd core && uv pip install -e ".[dev]"
# 2. Install pre-commit hooks (runs ruff automatically before each commit)
make install-hooks
# 3. Done. Every commit is now auto-linted and formatted.
What Ruff Enforces
| Rule Set | Code | What It Catches |
|---|---|---|
| pyflakes | F |
Unused imports, undefined names |
| pycodestyle | E, W |
Style violations, whitespace issues |
| bugbear | B |
Common Python gotchas (e.g., mutable default args, missing from on raise) |
| comprehensions | C4 |
Unnecessary list() / dict() calls that should be comprehensions |
| isort | I |
Import ordering and grouping |
| quotes | Q |
Consistent double-quote usage |
| pyupgrade | UP |
Modernize syntax for Python 3.11+ |
Line length: 100 characters.
Import order: stdlib, third-party, first-party (framework / aden_tools), local.
Makefile Commands
Run these from the repository root:
make lint # Auto-fix lint issues across core/, tools/, exports/
make format # Apply ruff formatting
make check # Dry-run check (same as CI) — no files modified
make test # Run the test suite
make install-hooks # One-time: install pre-commit hooks
make help # Show all available targets
make check is the exact set of checks that CI runs. If it passes locally, CI will pass.
Pre-Commit Hooks
After running make install-hooks, every git commit will automatically:
- Lint staged Python files with
ruff check --fix - Format staged Python files with
ruff format
If ruff modifies a file, the commit is aborted so you can review and re-stage. This is intentional — it prevents unlinted code from entering the repository.
To skip hooks in an emergency (not recommended):
git commit --no-verify -m "message"
Editor Setup
VS Code (Recommended)
The repository includes .vscode/extensions.json and .vscode/settings.json. On first open, VS Code will prompt you to install the recommended Ruff extension.
Once installed, the editor will:
- Format on save using ruff
- Auto-fix lint issues on save (import sorting, fixable violations)
- Show a ruler at column 100
No manual configuration needed.
Other Editors
The .editorconfig file sets baseline formatting (UTF-8, LF line endings, 4-space indent for Python, trailing whitespace trimming). Most editors support EditorConfig natively or via plugin.
For any editor, you can always rely on make lint and make format from the command line.
AI-Assisted Development
Claude Code
The repository includes a .claude/settings.json hook that automatically runs ruff check --fix and ruff format after every file edit made by Claude Code. No setup needed — it works out of the box.
Cursor
The .cursorrules file at the repo root tells Cursor's AI the project's style rules (line length, import order, quote style, etc.) so generated code follows convention.
Antigravity IDE
Antigravity IDE (Google's AI-powered IDE) is supported via .antigravity/mcp_config.json and .antigravity/skills/ (symlinks to .claude/skills/). See antigravity-setup.md for setup and troubleshooting.
Codex CLI
Codex CLI (OpenAI, v0.101.0+) is supported via .codex/config.toml (MCP server config) and .agents/skills/ (symlinks to .claude/skills/). These files are tracked in git. Run codex in the repo root and type use hive to start. See the Codex CLI section in the README for details.
CI Pipeline
Every push and PR to main runs the Lint Python job in GitHub Actions (.github/workflows/ci.yml):
ruff check → core/, tools/, exports/
ruff format → core/, tools/, exports/ (--check mode, no modifications)
Both must pass. If CI fails:
make lint # Fix lint issues
make format # Fix formatting
make check # Verify locally before pushing
Configuration Files
| File | Scope |
|---|---|
core/pyproject.toml [tool.ruff] |
Ruff rules for core/ and exports/ |
tools/pyproject.toml [tool.ruff] |
Ruff rules for tools/ (mirrors core, first-party = aden_tools) |
.editorconfig |
Editor-agnostic formatting defaults |
.pre-commit-config.yaml |
Pre-commit hook definitions |
.vscode/settings.json |
VS Code ruff integration |
.vscode/extensions.json |
Recommended VS Code extensions |
.cursorrules |
AI assistant context |
.claude/settings.json |
Claude Code post-edit hooks |
The single source of truth for lint rules is the [tool.ruff] section in each package's pyproject.toml. All other configs (VS Code, pre-commit, Makefile, CI) reference these.
FAQ
Q: Do I need to install anything beyond uv pip install -e ".[dev]"?
Only if you want pre-commit hooks: make install-hooks. Everything else (VS Code settings, editorconfig) works automatically.
Q: Can I use a different formatter (black, autopep8)? No. The project standardizes on ruff for both linting and formatting. Using a different formatter will cause CI failures.
Q: What if ruff and my editor disagree?
The .vscode/settings.json is configured to use ruff as the formatter. If you use a different editor, run make format before committing, or rely on the pre-commit hook.
Q: I'm getting lint errors in code I didn't write. Do I need to fix them? Only fix lint errors in files you modified. Don't send drive-by lint fix PRs for unrelated files without coordinating first.
Q: How do I suppress a specific rule on one line?
x = eval("1+1") # noqa: S307
Use sparingly and only with a comment explaining why.