ai-rulez

Name: ai-rulez
Author: Na'aman Hirschfeld

Manage one project's AI coding rules, skills and agents, and generate configs for many coding tools

By Na'aman Hirschfeld (individual) Go Local · stdio Developer tools

GitHub npm Website

65 popularity score ★ 167 ↓ 17k/wk

Connect your client

Local (npm)

Add in one click

Add to Cursor Add to VS Code Add to LM Studio Add to Goose

Opens the app, which asks before it adds the server.

Or add it by command or config

Claude CodeTerminal

claude mcp add ai-rulez -- npx -y ai-rulez@latest mcp

Claude Desktopclaude_desktop_config.json

{
  "mcpServers": {
    "ai-rulez": {
      "command": "npx",
      "args": [
        "-y",
        "ai-rulez@latest",
        "mcp"
      ]
    }
  }
}

Cursor~/.cursor/mcp.json

{
  "mcpServers": {
    "ai-rulez": {
      "command": "npx",
      "args": [
        "-y",
        "ai-rulez@latest",
        "mcp"
      ]
    }
  }
}

VS Code.vscode/mcp.json

{
  "servers": {
    "ai-rulez": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "ai-rulez@latest",
        "mcp"
      ]
    }
  }
}

Codex~/.codex/config.toml

[mcp_servers.ai-rulez]
command = "npx"
args = ["-y", "ai-rulez@latest", "mcp"]

Gemini CLITerminal

gemini mcp add --scope user ai-rulez npx -- -y ai-rulez@latest mcp

Local (PyPI)

Add in one click

Add to Cursor Add to VS Code Add to LM Studio Add to Goose

Opens the app, which asks before it adds the server.

Or add it by command or config

Claude CodeTerminal

claude mcp add ai-rulez -- uvx ai-rulez mcp

Claude Desktopclaude_desktop_config.json

{
  "mcpServers": {
    "ai-rulez": {
      "command": "uvx",
      "args": [
        "ai-rulez",
        "mcp"
      ]
    }
  }
}

Cursor~/.cursor/mcp.json

{
  "mcpServers": {
    "ai-rulez": {
      "command": "uvx",
      "args": [
        "ai-rulez",
        "mcp"
      ]
    }
  }
}

VS Code.vscode/mcp.json

{
  "servers": {
    "ai-rulez": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "ai-rulez",
        "mcp"
      ]
    }
  }
}

Codex~/.codex/config.toml

[mcp_servers.ai-rulez]
command = "uvx"
args = ["ai-rulez", "mcp"]

Gemini CLITerminal

gemini mcp add --scope user ai-rulez uvx -- ai-rulez mcp

Settings 4

`AI_RULEZ_GIT_TOKEN` secret	Optional: Git access token for private skill and include repositories, sent over https only (a git credential helper also works). For install_skill.
`AI_RULEZ_GIT_TOKEN_HOSTS`	Optional: Comma-separated hosts the git token may be sent to. Default `github.com`. For install_skill.
`AI_RULEZ_MAX_CLONE_BYTES`	Optional: Clone size cap in bytes for git skill sources (256 MiB); max_clone_bytes per source overrides it. Default `268435456`. For install_skill.
`AI_RULEZ_MAX_CLONE_FILES`	Optional: Cap on entries in a git skill source clone; max_clone_files per source overrides it. Default `20000`. For install_skill.

What it does

ai-rulez is a command-line tool that keeps one project's instructions for coding assistants in a single `.ai-rulez/` folder. Rules, context files, skills, agents, commands, checks, hooks and MCP server entries all live there. From that folder it writes each tool's own files for Claude Code, Cursor, Copilot, Windsurf, Gemini, Codex and others.

Running `ai-rulez mcp` starts a stdio MCP server over the same folder. An assistant can then create and edit that content, change config.toml and regenerate the outputs. It can also pull read-only reports on token counts, cost, lock state and policy. Add `--serve-skills` and the process hands out skills on demand through the MCP Skills extension, so a skill is loaded only when a session asks for it.

The guide counts 71 tools. That figure covers the authoring set in internal/mcp/tools.go, but skills mode registers six more in serve_tools.go and context serving adds two in serve_context.go, which makes 79. Which of them a client sees depends on the flags. `--read-only` drops every tool that writes, and `--tools` keeps only the names you give it. The session exposure report the README now describes is a command-line feature, and no MCP tool reaches it.

What it needs

Runtime	Node.js
Runs on	macOS, Windows, Linux
Also	uv, for the uvx way instead of npx git on PATH, to install skills from git

Node.js runs the npx way and uv runs the uvx way. A Homebrew, Go or pip install of the `ai-rulez` binary works too. The project needs an `.ai-rulez/` configuration, which `init_project` or `ai-rulez init` creates. Private skill repositories need `AI_RULEZ_GIT_TOKEN` or a git credential helper. The `judge` tool works only when your user config names a model provider and allows it.

Limits

Not covered stdio only: no HTTP transport, and no elicitation, sampling or roots
Limit Directory arguments must lie inside the start folder unless the server runs with `--root <dir>` or `--allow-any-dir`
Not covered Signing, approving, `ai-rulez lock`, publishing and the session exposure report are command-line only
Size cap A git skill source clone is capped at 256 MiB and 20000 entries by default (`AI_RULEZ_MAX_CLONE_BYTES`, `AI_RULEZ_MAX_CLONE_FILES`, or per source)
Limit In skills mode two served skills with the same name stop the server from starting
Size cap `load_skill` fails with "session budget exhausted" once a session reaches its byte cap
Size cap `find_context` returns 10 results by default, up to 50 with `limit`
Limit `find_context` and `load_context` return an error unless repository discovery is on
Cost `judge` sends file content to your model provider and spends money, only with `allow_llm` true and your user config allowing it
Limit `update` refuses a moved tag or failed scan, and the flags that accept those exist on the command line only

stdio only: no HTTP transport, and no elicitation, sampling or roots. Directory arguments must lie inside the folder the server was started in unless it is started with `--root <dir>` or `--allow-any-dir`. Signing, approving, publishing and other commands that use credentials or the network for trust are command-line only, as is `--allow-local-drift`. Lists page at 100 entries. Skill sources default to at most 200 skills, 64 MiB of files and a 256 MiB clone (`AI_RULEZ_MAX_CLONE_BYTES`). In skills mode two skills with the same name stop the server from starting. Its docs mark the pre-OKF folder layout as deprecated (`migrate okf` converts it).

Who it suits

Suits a team or developer who keeps one shared set of assistant rules and skills for several coding tools and wants the assistant to edit and regenerate them instead of hand-editing files. It runs locally on the project folder with no account. Skills mode also helps a large repository that pays for every skill in every session today. Pick something else if one coding tool and its own rules file are enough, or if you only want an assistant to read files. The tools are tied to the `.ai-rulez/` format, and most of them write.

Tools 60 of 79

38 only read, 13 change things, 9 can delete or overwrite.

init_project changes: Create a new .ai-rulez/ configuration, refusing to overwrite one that exists
read_config: Return the parsed settings from config.toml
update_config changes: Make a typed edit to config.toml that keeps its comments and order
generate_outputs changes: Write the native config files for each configured coding tool
clean_outputs deletes: Delete generated files and the managed .gitignore block, leaving .ai-rulez/ alone
validate_config: Check the configuration and report errors
doctor: Diagnose problems with the project setup
scan_content: Scan content for problems such as committed credentials
judge: Review the agent configuration with your own model provider, only when allow_llm is set
run_verifiers: Run the configured verifiers and report results
list_verifiers: List configured verifiers
create_domain changes: Add a domain, a scoped group of content
list_domains: List domains
delete_domain deletes: Delete a domain with everything in it
create_rule changes: Add a rule
read_rule: Read one rule
update_rule changes: Replace a rule in one call
delete_rule deletes: Remove a rule
list_rules: List rules
create_check changes: Add a code-review check file under .ai-rulez/checks/
delete_check deletes: Remove a check
list_checks: List checks
create_context changes: Add a context file
delete_context deletes: Remove a context file
list_context: List context files
create_skill changes: Add a skill
delete_skill deletes: Remove a skill
list_skills: List skills
read_context: Read one context file
update_context changes: Replace a context file in one call
read_skill: Read one skill
update_skill deletes: Replace a skill in one call
list_installed_skills: List installed skills
list_includes: List includes
add_include changes: Pull in shared content from another source
install_skill changes: Install a skill from a git repository or local path
uninstall_skill deletes: Remove an installed skill from the configuration
add_profile changes: Add a profile
list_roles: List the configured roles with item counts and token estimates
resolve_role: Show what a person holding one role receives
lock_status: Check the project against its ai-rulez.lock file
lock_diff: Show how sources and outputs differ from ai-rulez.lock, for pull request review
catalog: List every item with owner, version, tokens, digest and lock status
lock_outdated: List pinned sources that allow a newer tag, reading remote tags over the network
update_plan: Preview which pins an update would move, with a security scan of each new tree
update deletes: Move version-constrained pins to the newest allowed tag and rewrite ai-rulez.lock
token_report: Report how many tokens the content costs
cost_report: Estimate what the content costs to load
sbom: Produce a CycloneDX or SPDX bill of materials for the content
okf_validate: Validate the .ai-rulez/ bundle against the OKF format
approvals_status: Show reviewer approvals
policy_show: Show the organisation policy that applies
find_skill: Rank served skills against a query (skills mode)
search_skills: List and filter served skills by name (skills mode)
get_skill: Return a served skill with provenance and digests (skills mode)
load_skill: Read one served skill within the session byte budget (skills mode)
list_skill_resources: List the files of a served skill (skills mode)
read_skill_file: Read a supporting file of a served skill by skill:// URI (skills mode)
find_context: Search the repository's indexed context files (needs repository discovery)
load_context: Read one context file from the repository when called (needs repository discovery)

Resources 7

ai-rulez://config: The project configuration, absent when there is no project
ai-rulez://catalog: The catalog of everything the project defines
ai-rulez://catalog{?path,scope,recursive}: The catalog filtered by path or scope
ai-rulez://{kind}/{name}: One rule, context file, skill, check, agent or command
ai-rulez://domains/{domain}/{kind}/{name}: One item inside a domain
skill://<name>/<path>: A served skill file (skills mode)
context://<scope>/<name>: A served context file (needs repository discovery)

Prompts 4

author-skill: Draft a skill, create it, then check it for problems and cost
add-rule: Create or update a rule after checking for an existing one, then validate
review-config: Run the read-only checks and summarise what to fix without changing anything
trim-context: Find the largest always-loaded items and propose edits before applying them

Popularity

65 popularity score, on our list (the bar is 36)

★ 167 ↓ 17k/wk

GitHub stars, whole repository	167	26.7 points
Stars in 30 days	+8	4.8 points
npm downloads, last week	16,826	33.8 points
PyPI downloads, last month	13,250

It lives in the folder release/npm of goldziher/ai-rulez, which holds more than this server. Its stars are the whole repository's, so in the score they never count for more than its own downloads.

Measured 2026-11-07. How the score works.

Where it is published

Code	goldziher/ai-rulez/release/npm ★ 167, the whole repository
npm	ai-rulez 5.11.1, 2026-11-06, the one the command runs
PyPI	ai-rulez 5.3.0, 2026-10-14

What it can reach

Runs	On your machine
Reaches	Files on your machine, The internet, Your code
Changes things	Yes: it can write, send, create or delete
Sign-in	None
Licence	MIT AND Apache-2.0 AND Unicode-3.0 (npm)
Usage data	Only if you turn it on (`ai-rulez telemetry enable`) Identifier-only load events (item kind, id, digest, harness, role, salted session hash, outcome) over OTLP/HTTP, never prompts, file contents, arguments or absolute paths
Last code change	2026-11-06

Runs on your machine as a local process over stdio and needs no sign-in. Most tools write under `.ai-rulez/` and edit config.toml. `generate_outputs` writes other tools' config files, including their MCP entries, hooks and permission rules, and by default adds an ai-rulez entry to project MCP files unless `[mcp] self_server = false` or `--no-self-mcp` is set. Generation stops before writing a secret-bearing MCP value to a file that is not gitignored. `install_skill`, `lock_outdated`, `update_plan` and `update` reach git remotes, and the git token goes only to https remotes on github.com unless `AI_RULEZ_GIT_TOKEN_HOSTS` names others. `judge` sends file content to your model provider. `--read-only` registers only tools that do not write and drops `judge` and `update`.

Over time

GitHub stars, whole repository 167 +8 (+5 %)

167159

8 Oct 20267 Nov 2026

npm downloads a week 17k +17k (+5763 %)

17k33

20 Oct 20257 Nov 2026

Before the site measured it, read from npm's daily download counts.

Popularity score 65 +7 (+12 %)

6555

8 Oct 20267 Nov 2026

What is rising across the directory

Sources

Page checked 2026-11-04.

Badge for your README

Shows this server's rank in its category, and stars for a server that runs on your machine. It updates every hour.

MarkdownREADME.md

[![ai-rulez on EveryMCPServer](https://everymcpserver.com/badge/ai-rulez.svg)](https://everymcpserver.com/servers/ai-rulez)

Connect your client

Add in one click

Or add it by command or config

Add in one click

Or add it by command or config

Settings 4

What it does

What it needs

Limits

Who it suits

Tools 60 of 79

Resources 7

Prompts 4

Similar servers

agnix

AIWG

ReevesAgents

Serena

MisakaNet

autocontext