Ballast installs AI agent rules for Cursor, Claude Code, OpenCode, and Codex.
Release v4.0.0 supports three first-class language profiles in this repository:
- TypeScript
- Python
- Go
@everydaydevopsio/ballast(npm)ballast-python(GitHub Releases artifact)ballast-go(Go)ballast(Homebrew formula on Linux, Homebrew cask on macOS)
Common agents (all languages):
local-devcicdobservability
Language-specific agents:
- TypeScript:
linting,logging,testing - Python:
linting,logging,testing - Go:
linting,logging,testing
Agent sources in this repo:
agents/common/*agents/typescript/*agents/python/*agents/go/*
ballast is the wrapper command (intended for Homebrew) that detects repo language and dispatches to the matching language CLI.
brew tap everydaydevopsio/ballast
brew reinstall --formula everydaydevopsio/ballast/ballast
ballast install --target cursor --all
ballast doctor
ballast install-cli --language python
ballast upgradebrew tap everydaydevopsio/ballast
brew install --cask ballast
ballast install --target cursor --allIf Homebrew still installs an older Ballast release after the tap has been updated, your local tap checkout is stale. Reset the tap to the latest origin/HEAD, then reinstall the fully qualified formula:
brew update-reset "$(brew --repository everydaydevopsio/ballast)"
brew info --formula everydaydevopsio/ballast/ballast
brew reinstall --formula everydaydevopsio/ballast/ballastIf the tap still does not refresh, remove and re-add it:
brew untap everydaydevopsio/ballast
brew tap everydaydevopsio/ballast
brew reinstall --formula everydaydevopsio/ballast/ballastNotes:
- Use
everydaydevopsio/ballast/ballastfor the Linux formula. Plainballastcan collide with an unrelated Homebrew cask. - Verify the installed version with
brew info --formula everydaydevopsio/ballast/ballastandballast --version.
pnpm add -D @everydaydevopsio/ballast
pnpm exec ballast-typescript install --target cursor --allVERSION=4.0.0
uv tool install --from "https://github.com/everydaydevopsio/ballast/releases/download/v${VERSION}/ballast_python-${VERSION}-py3-none-any.whl" ballast-python
ballast-python install --target cursor --all
# or
uvx --from "https://github.com/everydaydevopsio/ballast/releases/download/v${VERSION}/ballast_python-${VERSION}-py3-none-any.whl" ballast-python install --target codex --agent lintingVERSION=5.0.5
OS="$(uname -s | tr '[:upper:]' '[:lower:]')"
ARCH="$(uname -m)"
case "$ARCH" in
x86_64) ARCH=amd64 ;;
arm64|aarch64) ARCH=arm64 ;;
esac
curl -fsSL -o /tmp/ballast-go.tar.gz "https://github.com/everydaydevopsio/ballast/releases/download/v${VERSION}/ballast-go_${VERSION}_${OS}_${ARCH}.tar.gz"
tar -xzf /tmp/ballast-go.tar.gz -C /tmp
mkdir -p "${HOME}/.local/bin"
install -m 0755 /tmp/ballast-go "${HOME}/.local/bin/ballast-go"
ballast-go install --target cursor --allIn a monorepo that contains TypeScript, Python, and Go projects, run Ballast once per language profile.
pnpm exec ballast-typescript install --target cursor --allVERSION=4.0.0
uvx --from "https://github.com/everydaydevopsio/ballast/releases/download/v${VERSION}/ballast_python-${VERSION}-py3-none-any.whl" ballast-python install --target cursor --allballast-go install --target cursor --allRecommended order for one repository that uses all three languages:
- Run the TypeScript command.
- Run the Python command.
- Run the Go command.
Ballast only installs shipped agents and follows the single overwrite policy (existing rule files are preserved unless --force is passed). Use --patch to merge new Ballast content into an existing rule file while preserving the user's version of edited sections.
--target, -t:cursor,claude,opencode,codex--agent, -a: comma-separated agent list--all: install all agents for the selected language--force, -f: overwrite existing rule files--patch, -p: merge upstream rule updates into existing rule files while preserving user-edited sections (--forcewins if both are set)--yes, -y: non-interactive mode
ballast install: install rules for the detected or selected language; add--refresh-configto reapply saved.rulesrc.jsonsettings and rewrite the config versionballast doctor: inspect local Ballast CLI versions and.rulesrc.jsonmetadata; add--fixto install/upgrade backend CLIs and refresh config automaticallyballast upgrade: rewrite.rulesrc.jsonto the running Ballast wrapper version, then sync backend CLIs to match itballast install-cli [--language <typescript|python|go>] [--version <x.y.z>]: install or upgrade backend CLIs into the current repo’s.ballast/directory; omit--versionfor the latest release
- TypeScript CLI:
.rulesrc.ts.json - Python CLI:
.rulesrc.python.json - Go CLI:
.rulesrc.go.json
- Cursor:
.cursor/rules/<agent>.mdc - Claude:
.claude/rules/<agent>.md - OpenCode:
.opencode/<agent>.md - Codex:
.codex/rules/<agent>.mdand rootAGENTS.md
nvm install
pnpm install
pnpm test
pnpm run lint
pnpm run buildTo test the wrapper against the local checkout instead of installed package binaries:
cd ~/src/ballast
make build
~/src/ballast/cli/ballast/ballast install --target cursor --allmake build builds the local artifacts the wrapper looks for:
packages/ballast-typescript/dist/cli.jspackages/ballast-go/ballast-gocli/ballast/ballast
The wrapper then dispatches to the local TypeScript, Python, and Go backends from this repo when those artifacts are present. If a local backend artifact is missing, the wrapper falls back to an installed backend on PATH.
Use Dockerfile.smoke to test wrapper + language CLIs.
Default (all binaries preinstalled from local checkout):
docker build -f Dockerfile.smoke -t ballast-smoke .
docker run --rm -it ballast-smokeOn-demand mode (start with ballast wrapper and lazy-download language CLIs from GitHub):
docker build -f Dockerfile.smoke --build-arg PREINSTALL_ALL_BINARIES=0 -t ballast-smoke-lazy .
docker run --rm -it ballast-smoke-lazyMIT