Rules - PraisonAI

The rules command manages auto-discovered instruction files that control agent behavior.

Quick Start

# List all loaded rules
praisonai rules list

CLI Auto-Injection

praisonai run and praisonai chat automatically load project instruction files from the current directory (and walk up to the git root). Zero config required — drop an AGENTS.md into your project and every CLI run sees it.

Opt-out

Goal	How
Disable for a single run	`praisonai run "task" --no-rules`
Disable globally	Set `[rules] auto = false` in `~/.praisonai/config.toml`
Override the size cap	Set `[rules] max_chars = 16000` in `config.toml`
Still load a specific manual rule	`praisonai run "task" --include-rules security`

Precedence

--no-rules (always wins)
--include-rules <names> (manual list or auto)
[rules] auto in config.toml
Default: auto-loading on

Size caps

Cap	Default	Where to change
Per file	12 KB (12000 chars)	Hard-coded in `RulesManager.MAX_RULE_CHARS`
Total	32 KB (32000 chars)	`[rules] max_chars` in `config.toml`

Files over the per-file cap are truncated with a warning. Total context stops at max_chars.

Verbose output

praisonai run "Refactor the auth module" --verbose
# Loaded project instructions: AGENTS.md, CLAUDE.md

Only root-priority files (AGENTS.md, CLAUDE.md, PRAISON.md, GEMINI.md, .cursorrules, .windsurfrules) are listed — modular rules under .praison/rules/ and globals are loaded silently.

Usage

List Rules

praisonai rules list

Expected Output:

╭─ Loaded Rules ───────────────────────────────────────────────────────────────╮
│  📜 PRAISON.md (project root)                                               │
│  📜 CLAUDE.md (project root)                                                │
│  📜 .cursorrules (project root)                                             │
│  📜 python-guidelines.md (.praison/rules/)                                  │
╰──────────────────────────────────────────────────────────────────────────────╯

Show Rule Details

praisonai rules show <rule_name>

Create Rule

praisonai rules create my_rule "Always use type hints"

Delete Rule

praisonai rules delete my_rule

Show Statistics

praisonai rules stats

Include Rules with Prompts

praisonai "Task" --include-rules security,testing
praisonai "Task" --no-rules

Auto-Discovered Files

PraisonAI automatically discovers instruction files from your project root and git root:

File	Description	Priority
`PRAISON.md`	PraisonAI native instructions	High
`PRAISON.local.md`	Local overrides (gitignored)	Higher
`CLAUDE.md`	Claude Code memory file	High
`CLAUDE.local.md`	Local overrides (gitignored)	Higher
`AGENTS.md`	OpenAI Codex CLI instructions	High
`GEMINI.md`	Gemini CLI memory file	High
`.cursorrules`	Cursor IDE rules	High
`.windsurfrules`	Windsurf IDE rules	High
`.claude/rules/*.md`	Claude Code modular rules	Medium
`.windsurf/rules/*.md`	Windsurf modular rules	Medium
`.cursor/rules/*.mdc`	Cursor modular rules	Medium
`.praison/rules/*.md`	Workspace rules	Medium
`~/.praisonai/rules/*.md`	Global modular rules	Low
`~/.praisonai/AGENTS.md`	Global single-file instructions (loaded by `load_context_files()`)	Lowest

~/.praisonai/AGENTS.md is loaded by load_context_files() as the lowest-precedence layer whenever walk_up=True (the default). It is separate from the modular ~/.praisonai/rules/*.md files loaded by RulesManager. See Context Files → CLI auto-loading for how chat, run, code, and tui automatically inject this context into the agent system prompt.

Monorepos with per-subtree instruction files: see On-demand Subtree Attachment for why a sibling package’s AGENTS.md only loads once the agent opens a file inside it.

Rule File Format

Basic Format

# Guidelines

- Use type hints for all functions
- Follow PEP 8 style guide
- Include docstrings for public methods

With YAML Frontmatter

---
description: Python coding guidelines
globs: ["**/*.py"]
activation: always  # always, glob, manual, ai_decision
---

# Guidelines

- Use type hints
- Follow PEP 8

@Import Syntax

Reference other files in your rules:

# CLAUDE.md
See @README for project overview
See @docs/architecture.md for system design
@~/.praisonai/my-preferences.md

How It Works

Discovery: Scans project root and git root for rule files
Priority: Higher priority rules override lower priority
Injection: Rules are injected into agent system prompts
Activation: Rules activate based on globs or manual selection

Activation Modes

Mode	Description
`always`	Rule is always active
`glob`	Injected only for files the agent touches during a run — see Path-Scoped Rules in Action
`manual`	Only active when explicitly included
`ai_decision`	AI decides when to apply

Programmatic Usage

from praisonaiagents import Agent

# Agent auto-discovers CLAUDE.md, AGENTS.md, GEMINI.md, etc.
agent = Agent(name="Assistant", instructions="You are helpful.")
# Rules are injected into system prompt automatically

Best Practices

Use .local.md files for personal preferences that shouldn’t be committed to git.

High-priority rules override lower-priority ones. Be careful with conflicting instructions.

Do	Don’t
Use PRAISON.md for project-wide rules	Put personal prefs in shared files
Use .local.md for personal overrides	Commit .local.md files
Use globs for language-specific rules	Apply all rules to all files
Keep rules concise and actionable	Write verbose instructions

​Quick Start

​CLI Auto-Injection

​Opt-out

​Precedence

​Size caps

​Verbose output

​Usage

​List Rules

​Show Rule Details

​Create Rule

​Delete Rule

​Show Statistics

​Include Rules with Prompts

​Auto-Discovered Files

​Rule File Format

​Basic Format

​With YAML Frontmatter

​@Import Syntax

​How It Works

​Activation Modes

​Programmatic Usage

​Best Practices

​Related

Quick Start

CLI Auto-Injection

Opt-out

Precedence

Size caps

Verbose output

Usage

List Rules

Show Rule Details

Create Rule

Delete Rule

Show Statistics

Include Rules with Prompts

Auto-Discovered Files

Rule File Format

Basic Format

With YAML Frontmatter

@Import Syntax

How It Works

Activation Modes

Programmatic Usage

Best Practices

Related