DX Improvements: Linting, Formatting & Pre-Commit Hooks

[TimothyZhang7]

DX Improvements: Linting, Formatting & Pre-Commit Hooks

Hey everyone — we just shipped a bunch of developer experience improvements. Here's the rundown.

What was broken

Honestly, the DX around code quality was pretty bare-bones:

• No pre-commit hooks. Nothing stopped unlinted code from getting committed. You'd push, wait for CI to fail, fix, push again. Rinse and repeat.
• No Makefile or common commands. You had to remember the right ruff invocations and manually cd into the correct package directory.
• No VS Code setup. No recommended extensions, no format-on-save, no import resolution. Pylance couldn't find framework or aden_tools imports without manual config.
• Import sorting was a mess. core/ and tools/ have different first-party packages (framework vs aden_tools). A single global ruff config would re-sort imports wrong for one of the two packages — on every single commit.
• No AI tooling hooks. If you use Claude Code or Cursor, edits didn't follow project conventions automatically.
• Type errors everywhere. No Pyright/Pylance config meant cross-package imports were unresolved, contributing to the 136+ type errors flagged in [Bug]: 136 Type Errors found by mypy (Potential Runtime Crashes) #1081.

Open issues addressed by this work

This DX overhaul directly addresses or makes progress on the following open issues:

• [Bug]: 136 Type Errors found by mypy (Potential Runtime Crashes) #1081 — 136 Type Errors found by mypy — The new pyrightconfig.json and VS Code extraPaths config resolve cross-package import resolution, eliminating a large class of false-positive type errors. Pylance now correctly finds framework and aden_tools imports.
• Cleanup: Remove legacy web app artifacts (honeycomb) #1090 — Cleanup: Remove legacy web app artifacts — While we didn't remove the legacy files, the new Makefile and CI now scope lint/format strictly to core/ and tools/, so stale artifacts in other directories no longer cause noise.
• Improve clarity of local setup and onboarding documentation #1067 — Improve clarity of local setup and onboarding documentation — The new docs/contributing-lint-setup.md covers setup end-to-end: editor config, pre-commit hooks, Makefile commands, CI behavior, and FAQ.
• [Docs]: Improve Onboarding Documentation & Local Setup Instructions #784 — Improve Onboarding Documentation & Local Setup Instructions — Same as above. Contributors now have a single doc covering prerequisites, environment setup, and verification.
• BUILDING_TOOLS.md lacks an end-to-end example and contributor checklist clarity #1088 — BUILDING_TOOLS.md lacks end-to-end example — The lint setup doc clarifies how tools/ is configured separately from core/, which was a source of confusion.
• feat(cli): add root hive CLI entry point to eliminate PYTHONPATH #1444 — feat(cli): add root hive CLI entry point to eliminate PYTHONPATH — The pyrightconfig.json and VS Code extraPaths partially address the import pain this issue describes. PYTHONPATH is no longer needed for editor import resolution.
• docs(readme): add virtual environment setup instructions #819 — docs(readme): add virtual environment setup instructions — The contributing doc now includes setup steps that work cleanly inside a venv.
• docs: add Windows examples for PYTHONPATH-based agent commands #812 — docs: add Windows examples for PYTHONPATH-based agent commands — The Pyright config eliminates the need for PYTHONPATH for type checking, reducing the Windows setup friction this issue highlights.
• Update required in the Developer and Getting-Started readme files #1442 — Update required in the Developer and Getting-Started readme files — The new contributing doc provides accurate, up-to-date setup instructions that can be referenced from the main README.
• docs(tests): centralize test organization to core/tests/  #789 — docs(tests): centralize test organization — The Makefile make test target now provides a single command to run the test suite from the repo root.
• [Bug]: Silent exception swallowing in agent_builder_server.py masks runtime errors #1447 — Silent exception swallowing in agent_builder_server.py — While fixing lint violations, we caught and fixed an UP038 modernization issue in this file. The broader exception handling fix is still open.

What we added

• Pre-commit hooks (.pre-commit-config.yaml) — Every git commit now auto-lints and auto-formats your staged Python files. Hooks are scoped per package so import sorting just works. One-time setup: make install-hooks.
• Makefile — make lint, make format, make check, make test. make check is the exact same thing CI runs, so if it passes locally, you're good.
• VS Code workspace config (.vscode/settings.json, .vscode/extensions.json) — Format-on-save, auto-fix on save, column 100 ruler, and correct import resolution for both packages. Just accept the recommended extensions when VS Code prompts you.
• Pyright config (pyrightconfig.json) — Cross-package imports resolve automatically now.
• CI updated (.github/workflows/ci.yml) — Checks both ruff check and ruff format --check, scoped per package.
• Claude Code hooks (.claude/settings.json) — Auto-runs ruff after every file edit. No setup needed.
• Cursor rules (.cursorrules) — Tells Cursor's AI about project conventions.
• EditorConfig (.editorconfig) — Baseline formatting for any editor.
• Per-package ruff config (tools/pyproject.toml) — tools/ now has its own [tool.ruff] section with known-first-party = ["aden_tools"], matching core/'s config for framework.

How to set up

cd core && pip install -e ".[dev]"
make install-hooks

That's it. You're done. Every commit from here on is auto-linted and formatted.

For the full details (rule sets, editor config, FAQ), see docs/contributing-lint-setup.md.