Skip to content

FineCode

FineCode gives you one intent-based workflow for developer tooling across CLI, IDE, CI, and AI assistants.

Most teams wire the same tooling logic multiple times: shell scripts for local use, YAML for CI, editor plugins, and now MCP glue for AI. FineCode replaces all of that with one reusable layer. Define lint, format, or test once — then run the same action everywhere:

python -m finecode run lint           # terminal
python -m finecode run format         # CI pipeline
# Same actions surface in VSCode and MCP-compatible AI clients automatically

What you get

FineCode organizes developer tooling into features — linting, formatting, testing, and more. Each feature is packaged as a preset you add to your project.

With fine_python_recommended you get all of these out of the box:

Feature Tools Where it works
Linting Ruff, Flake8 CLI, IDE diagnostics, CI, AI
Formatting Ruff formatter, isort CLI, IDE format-on-save, CI, AI
Type checking Pyrefly CLI, IDE diagnostics, CI, AI
Import checking import-linter CLI, CI, AI
Testing pytest CLI, IDE test panel, CI, AI
IDE language support Pyrefly IDE (hover, go-to-definition, references, call hierarchy, inlay hints, semantic tokens)
TOML support Tombi IDE (linting, formatting, semantic tokens)

Want only specific features? Pick individual presets instead — see the feature catalog in Getting Started.

Try it in minutes

Add FineCode and a preset to your pyproject.toml:

[dependency-groups]
dev_workspace = ["finecode==0.3.*", "fine_python_recommended==0.3.*"]

[tool.finecode]
presets = [{ source = "fine_python_recommended" }]

Bootstrap the workspace tooling environment:

pipx run finecode bootstrap
# or
uvx finecode bootstrap

Then activate the bootstrapped environment:

source .venvs/dev_workspace/bin/activate
# Windows: .venvs\dev_workspace\Scripts\activate

Then prepare tool environments and run your first action:

python -m finecode prepare-envs
python -m finecode run lint

For the full setup flow, see Getting Started.

Customize your setup

Presets give you sensible defaults. Override anything in your pyproject.toml — no Python code needed.

Add stricter lint rules:

[[tool.finecode.action_handler]]
source = "fine_python_ruff.RuffLintFilesHandler"
config.extend_select = ["B", "I", "UP", "SIM"]

Disable a tool you don't need:

[[tool.finecode.action_handler]]
source = "fine_python_flake8.Flake8LintFilesHandler"
enabled = false

Pin a tool version:

[tool.finecode.extension.fine_python_ruff]
dependencies_override = ["ruff==0.15.*"]

See Configuration for the full reference.

Why teams use FineCode

  • One workflow everywhere — the same actions run in terminal, CI, IDE, and AI assistants. No duplicated glue code, no mismatches between local and CI.
  • Swap tools, keep the workflow — replace ruff with another linter, or add a new formatter, without redesigning your setup. The action surface stays stable.
  • Reusable standards — package your team's tooling setup as a preset and share it across repositories. Roll out updates through normal dependency management.
  • Isolation without fragmentation — developer tooling runs in isolated environments, separate from your runtime dependencies, while still presenting one coherent workflow.
  • Scales with your codebase — works the same for a single project, a multi-project workspace, or a mixed-language monorepo.

For the deeper design reasoning, see Why FineCode's Action Model Works.

Where to go next

Community

Have questions or feedback? Join Matrix or Discord.