Subscription Savings Lab
English

AI Tooling

Published 2026-05-14 · General · Author Mark

How to set up local tools for AI coding agents

A concise local setup guide for developers using Codex, Cursor, or Claude Code: search tools, config parsers, test commands, build tools, and OS-specific choices.

Contents

When Codex, Cursor, or Claude Code edits a repository, the model is only part of the system. The agent still has to search files, inspect config, run tests, start local services, and read Git diffs. If those commands are missing or inconsistent, the agent works with a distorted view of the project.

This guide was checked on May 14, 2026. It focuses on local developer machines on Mac and Windows. The rule of thumb is simple: install common CLI tools on the machine, but keep language versions and build commands aligned with each project.

1. Install the shared tools first

Most coding agents benefit from a small, predictable CLI base before any language-specific tooling.

AreaToolsWhy they matter
Search and file discoveryripgrep / rg, fd, treeFind code and list project files without crawling dependency folders
Config parsingjq, yqRead JSON, YAML, workflow files, and structured command output
Git workflowgh, git-deltaInspect PRs, CI, review context, and diffs
Task entry pointsjust, make, shellcheck, shfmtStandardize commands and check shell scripts
Structural searchast-grepSearch and rewrite code by syntax shape rather than plain text
Runtime managementmise, Volta, SDKMAN!, uvKeep Node, Python, Java, and related tools reproducible

On Mac, Homebrew is the most direct starting point:

xcode-select --install

brew install git gh ripgrep fd jq yq fzf bat eza tree git-delta hyperfine just shellcheck shfmt ast-grep uv mise

On Windows, use WinGet for desktop apps and runtimes, and Scoop for small CLI tools:

winget --help
winget install Git.Git GitHub.cli

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
irm get.scoop.sh | iex
scoop install ripgrep fd jq yq fzf bat eza tree delta hyperfine just shellcheck shfmt ast-grep uv mise

Install Docker Desktop only when the project needs containers, databases, queues, or isolated services. Installing every language runtime globally is usually worse than installing less: it gives the agent more ways to run the wrong version.

2. Why agents usually prefer rg over grep

grep is still useful for portable shell scripts. In a codebase, though, rg is usually the better default for an agent.

rg respects .gitignore, so it normally skips directories such as node_modules/, dist/, .venv/, and target/. Its output includes file paths, line numbers, and matched snippets, which gives the agent a clean next step. rg --files is also a practical repository index because it lists source files while honoring ignore rules.

The point is not that grep is obsolete. The point is that agent search should stay close to the files a developer would actually review.

3. Handle Mac and Windows differently

After installation, PATH is the first thing to verify. A command working in your terminal does not always mean a desktop agent launched from the OS can see the same command.

3.1 Mac: verify the Homebrew path

Apple Silicon Macs usually use /opt/homebrew; Intel Macs usually use /usr/local. Make sure the right brew shellenv line is loaded by your shell:

# Apple Silicon
eval "$(/opt/homebrew/bin/brew shellenv)"

# Intel Mac
eval "$(/usr/local/bin/brew shellenv)"

Then check the commands the agent is likely to call:

which rg fd jq yq gh
rg --version
fd --version
jq --version
yq --version
gh --version

If you changed PATH and launch the agent from the Dock or app launcher, restart the app before debugging further.

3.2 Windows: choose PowerShell or WSL

Windows is not one command environment. PowerShell, Git Bash, and WSL each have their own PATH, Node, Python, JDK, and package cache.

For frontend, Python, Go, and Java services that deploy to Linux, WSL is often the cleaner primary environment:

wsl --install
wsl --list --online

For .NET, Windows desktop work, PowerShell automation, or repositories that depend on Windows paths, keep commands in native PowerShell:

where.exe rg
where.exe fd
rg --version
fd --version
jq --version
gh --version

Avoid mixing PowerShell and WSL inside one repo unless the project explicitly documents that split. Write the intended environment into the project rules.

4. Add language tools by project

Language tooling should follow the repository, not personal habit. If the project has a lockfile, wrapper, toolchain file, or CI command, use that as the agent’s default entry point.

4.1 Python

For new projects, uv is a good baseline because it can manage Python versions, virtual environments, dependencies, and command execution:

brew install uv
uv python install 3.12
uv tool install ruff

On Windows PowerShell:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
uv python install 3.12
uv tool install ruff

Keep test and lint tools in the project when possible:

uv add --dev pytest ruff
uv run pytest
uv run ruff check .
uv run ruff format .

If the repo already uses mypy, pyright, or basedpyright, keep that choice. A useful project rule is: run Python commands through uv run, and run tests with uv run pytest.

4.2 JavaScript and TypeScript

The important choices are Node version and package manager. If the repo has pnpm-lock.yaml, do not run npm install. If package.json declares packageManager, follow it.

Mac:

brew install node mise
node --version

Windows:

winget install OpenJS.NodeJS.LTS
node --version
corepack --version
corepack enable

If the project runs in WSL, install Node inside WSL instead of relying on Windows node.exe. Frontend repositories should expose clear scripts or commands for type checking, linting, tests, and browser checks, such as pnpm exec tsc --noEmit, pnpm exec eslint ., pnpm exec vitest run, and pnpm exec playwright test.

4.3 Java

For Java, check the JDK version before installing anything. Look at pom.xml, build.gradle, .sdkmanrc, .java-version, or CI configuration.

Example with JDK 21:

brew install --cask temurin@21
java -version

Windows:

winget search Temurin
winget install EclipseAdoptium.Temurin.21.JDK
java -version

Prefer project wrappers:

./mvnw test
./gradlew test

Only fall back to local mvn or gradle when the repo does not provide a wrapper. That keeps local behavior closer to CI.

4.4 Go

Go already ships strong defaults for formatting, testing, and basic checks.

Mac:

brew install go
go version

Windows:

winget install GoLang.Go
go version

Add common development tools:

go install golang.org/x/tools/gopls@latest
brew install golangci-lint delve

A typical verification path is:

gofmt -w .
go test ./...
go vet ./...
golangci-lint run

Pin golangci-lint in CI, a Makefile, a justfile, or a tool config when the team needs consistent results.

5. Put the environment contract in project rules

Tools only answer whether a command exists. Project rules tell the agent which command is correct.

If you have not organized those files yet, see the related guide: AGENTS.md, CLAUDE.md, and Cursor Rules, explained

A compact rules block is often enough:

- Prefer `rg` and `rg --files` for search.
- On Windows, run project commands in PowerShell unless this file explicitly says WSL.
- Do not edit generated directories such as `dist/`, `.astro/`, `target/`, `build/`, `.venv/`, or `node_modules/`.
- JavaScript commands must use the package manager indicated by the lockfile.
- Python commands must use `uv run` when `uv.lock` exists.
- Java commands should prefer `./mvnw` or `./gradlew` when wrappers exist.
- Go checks should run `go test ./...` before finishing.
- Run the project build command before reporting success.

This removes guesswork from later agent sessions. The agent does not need to infer your package manager, test command, or forbidden output directories from scratch.

6. Closing note

Agent coding makes local tools more important, not less. The model can plan edits, but the local environment proves whether those edits build, test, and fit the repository.

Set up rg, fd, jq, yq, gh, the right language runtime, and the project verification commands first. On Mac, make PATH predictable. On Windows, decide whether PowerShell or WSL is the primary execution environment. That foundation matters more than adding another editor plugin.

References