CLI to install TypeScript AI agent rules for Cursor, Claude Code, OpenCode, and Codex. One package, one command—pick your platform and which agents to install.
- nvm (Node Version Manager)
After cloning the repo, install and use the project's Node version:
nvm install # installs the version from .nvmrc
nvm use # switches to it (or run `nvm install` which does both)Then install dependencies: pnpm install (or npm install / yarn).
| Agent | Description |
|---|---|
| linting | ESLint, Prettier, Husky, lint-staged, GitHub Actions (full instructions) |
| local-dev | Local dev environment (nvm, Docker, env), license setup (MIT default), MCP (optional) |
| cicd | CI/CD pipelines, quality gates, deployment (placeholder outline) |
| observability | Logging, tracing, metrics, SLOs (placeholder outline) |
| logging | Pino + Fluentd (Node/Next.js API), pino-browser to /api/logs, window.onerror, unhandledrejection |
| testing | Jest (default) or Vitest for Vite, 50% coverage default, test step in build GitHub Action |
Once installed, rule files are loaded automatically by your AI platform (Cursor, Claude Code, or OpenCode). Use an agent by asking the AI for help in that area; the rule gives it the instructions.
| Agent | How to use it |
|---|---|
| linting | In any session: "Help me set up linting for this project" or "Fix lint errors per the linting rules." The agent will add ESLint, Prettier, Husky, lint-staged, and CI workflows. |
| local-dev | Ask for help with local dev environment, license setup (LICENSE, package.json, README), or optional MCP integration. |
| cicd | Ask for help with CI/CD pipelines, quality gates, or deployment (placeholder). |
| observability | Ask for help with logging, tracing, metrics, or SLOs (placeholder). |
| logging | Ask for help with centralized logging: Pino + Fluentd for server, pino-browser to /api/logs for console, exceptions, window.onerror, unhandledrejection. |
| testing | Ask for help setting up Jest or Vitest, coverage (default 50%), and a test step in the build GitHub Action. |
- Installation guide — For AI coding agents: install ballast from within Cursor, Claude Code, OpenCode, or Codex using a prompt.
- Agent guides — Per-agent docs: what each agent sets up, what it provides, and prompts to improve your app.
Install as a dev dependency in your project:
npm install -D @everydaydevopsio/ballast
# or
pnpm add -D @everydaydevopsio/ballast
# or
yarn add -D @everydaydevopsio/ballastFrom your project root:
npx ballast installYou’ll be prompted for:
- AI platform:
cursor,claude,opencode, orcodex - Agents: comma-separated (e.g.
linting, local-dev) orall
Your choices are saved to .rulesrc.json. Future runs reuse them (non-interactive).
# Install linting agent for Cursor
npx ballast install --target cursor --agent linting
# Install all agents for Claude
npx ballast install --target claude --all
# Overwrite existing rule files
npx ballast install --target cursor --agent linting --force
# Non-interactive (CI): require --target and --agent/--all if no .rulesrc.json
npx ballast install --yes --target cursor --agent linting
ballast install --yes --target codex --allIn CI (or with --yes), if .rulesrc.json is not present you must pass --target and either --agent or --all:
ballast install --yes --target cursor --agent linting
ballast install --yes --target opencode --allnpx ballast --help
npx ballast --versionRules are written under your project root:
| Platform | Path | File pattern |
|---|---|---|
| Cursor | .cursor/rules/ |
<agent>.mdc |
| Claude | .claude/rules/ |
<agent>.md |
| OpenCode | .opencode/ |
<agent>.md |
| Codex | .codex/rules/ |
<agent>.md |
Codex installs a root AGENTS.md that references the .codex/rules/ files so Codex CLI and Codex app can load the same guidance.
Existing rule files are never overwritten unless you pass --force. Same behavior for all platforms.
After an interactive install, .rulesrc.json in the project root stores:
{
"target": "cursor",
"agents": ["linting", "local-dev"]
}Commit this file to make installs repeatable for your team and in CI (or pass --yes --target --agent in CI when the file is not present).
Single package (no workspaces).
pnpm install
pnpm test
pnpm run test:coverage
pnpm run lint
pnpm run lint:fix
pnpm run prettier:fixFrom the repo root:
pnpm publish --access publicVersion history: v1 (OpenCode-only) is opencode-typescript-linting-agent; v2 (multi-platform) is this repo, typescript-linting-agent.
MIT License - see LICENSE file for details.
Mark C Allen (@markcallen)