Rules - PraisonAI

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

As of PraisonAI PR #4338, rules list/add/clear run natively on a standalone pip install praisonai-code — backed by praisonaiagents.memory.RulesManager, no wrapper needed. The remaining subcommands still require the full wrapper.

Subcommand	Standalone (`pip install praisonai-code`)	Full wrapper (`pip install praisonai`)
`list`	✅ Native	✅
`add <name> <content>`	✅ Native (PR #4338)	✅
`clear`	✅ Native — workspace scope only (PR #4338)	✅
`show <name>`, `create`, `delete`, `stats`, `--include-rules`	❌ Wrapper only	✅

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

--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

Native standalone output — one line per rule (<name> [<activation>] - <description-truncated-to-60-chars>):

PRAISON.md [always] - PraisonAI native project instructions
CLAUDE.md [always] - Claude Code memory file
python-guidelines [glob] - Use type hints and follow PEP 8 across all Pyth…

When the workspace has no rules, it prints:

No rules found. Create PRAISON.md, CLAUDE.md, AGENTS.md, or files in .praison/rules/

Wrapper output — the full wrapper renders a Rich panel instead:

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

Add Rule

Native standalone — both <name> and <content> are required. Creates a workspace-scoped rule under .praison/rules/<name>.md with activation="always":

praisonai rules add my_rule "Always use type hints"

Missing content exits 1:

Rule content required. Usage: praisonai rules add <name> <content>

Clear Rules

Native standalone — clears only workspace-scoped rules (those rules add created). Hand-authored AGENTS.md / CLAUDE.md / PRAISON.md, global rules, git-root rules, and nested subdir rules are left untouched:

praisonai rules clear
# Cleared 3 rule(s).

Show Rule Details (wrapper only)

praisonai rules show <rule_name>

Create Rule (wrapper only)

praisonai rules create my_rule "Always use type hints"

On standalone, use praisonai rules add my_rule "Always use type hints" instead.

Delete Rule (wrapper only)

praisonai rules delete my_rule

Show Statistics (wrapper only)

praisonai rules stats

Include Rules with Prompts

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

Declared instruction sources

This page covers auto-discovery — files found by convention (AGENTS.md, CLAUDE.md, .cursorrules, etc.). To declare extra sources explicitly, use the top-level instructions: config key or the praisonai run --instructions flag.

Approach	Where	How files are chosen
Auto-discovery (this page)	Project + git root, walk-up	By convention — drop a known filename and it loads
Declared sources	`instructions:` config / `--instructions` flag	Explicit list of files, globs, or `http(s)://` URLs

Declared sources load up front alongside the auto-discovered walk-up, and --no-rules suppresses both. See Instruction Sources.

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

​Add Rule

​Clear Rules

​Show Rule Details (wrapper only)

​Create Rule (wrapper only)

​Delete Rule (wrapper only)

​Show Statistics (wrapper only)

​Include Rules with Prompts

​Declared instruction sources

​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

Add Rule

Clear Rules

Show Rule Details (wrapper only)

Create Rule (wrapper only)

Delete Rule (wrapper only)

Show Statistics (wrapper only)

Include Rules with Prompts

Declared instruction sources

Auto-Discovered Files

Rule File Format

Basic Format

With YAML Frontmatter

@Import Syntax

How It Works

Activation Modes

Programmatic Usage

Best Practices

Related