Rules

Auto-discovered instruction files for agent behavior

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, praisonai chat, and bare prompts (praisonai "…", which route to run) 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 modern-engine invocation 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

1. --no-rules (always wins)
2. --include-rules <names> (manual list or auto)
3. [rules] auto in config.toml
4. 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

1. Discovery: Scans project root and git root for rule files
2. Priority: Higher priority rules override lower priority
3. Injection: Rules are injected into agent system prompts
4. 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

Related

• Rules Feature
• Hooks CLI
• Workflow CLI