> ## Documentation Index
> Fetch the complete documentation index at: https://praison.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Project AGENTS.md
> Drop an AGENTS.md in your repo and every praisonai CLI command auto-loads it as project context
Place an `AGENTS.md` file at your project root and every `praisonai chat`, `run`, `code`, and `tui` command automatically injects it into the agent's system prompt — no flags needed.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
subgraph "Project AGENTS.md"
Request[📋 User Request] --> Process[⚙️ Project AGENTS.md]
Process --> Result[✅ Result]
end
classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
classDef process fill:#189AB4,stroke:#7C90A0,color:#fff
classDef output fill:#10B981,stroke:#7C90A0,color:#fff
class Request input
class Process process
class Result output
```
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant User
participant Agent
participant Feature as Project AGENTS.md
User->>Agent: Request
Agent->>Feature: Process request
Feature-->>Agent: Result
Agent-->>User: Response
```
```python theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
from praisonaiagents import Agent
agent = Agent(
name="Dev",
instructions="Help with coding tasks",
)
agent.start("How should I structure new modules in this project?")
```
The user asks a coding question; AGENTS.md from the project root is injected automatically.
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph LR
subgraph "Project AGENTS.md"
In[📝 CLI Command] --> Find[🔍 Discover AGENTS.md]
Find --> Inject[⚙️ Inject Context]
Inject --> Agent[🤖 Agent]
Agent --> Out[✅ Project-aware Reply]
end
classDef input fill:#6366F1,stroke:#7C90A0,color:#fff
classDef process fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
classDef output fill:#10B981,stroke:#7C90A0,color:#fff
class In input
class Find,Inject process
class Agent agent
class Out output
```
## How It Works
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
sequenceDiagram
participant User
participant CLI
participant Loader
participant Agent
User->>CLI: praisonai chat
CLI->>Loader: Walk up for AGENTS.md
Loader-->>Agent: Inject file into system prompt
Agent-->>User: Answer using project context
```
### Auto-Discovery
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
subgraph "Project AGENTS.md Auto-Discovery"
CWD["📁 Working directory\n/project/src/utils"] --> W1["📁 /project/src/utils/AGENTS.md?"]
W1 -->|Not found| W2["📁 /project/src/AGENTS.md?"]
W2 -->|Not found| W3["📁 /project/AGENTS.md ✅ Found!"]
W3 --> BUD{Token budget\ncheck}
BUD -->|Within budget| INJ["💬 Injected into\nsystem prompt"]
BUD -->|Over budget| TRIM["✂️ Trimmed to\ncontext_token_budget"]
INJ --> AG["🤖 Agent knows\nproject context"]
TRIM --> AG
end
classDef dir fill:#6366F1,stroke:#7C90A0,color:#fff
classDef found fill:#10B981,stroke:#7C90A0,color:#fff
classDef proc fill:#189AB4,stroke:#7C90A0,color:#fff
classDef agent fill:#8B0000,stroke:#7C90A0,color:#fff
classDef warn fill:#F59E0B,stroke:#7C90A0,color:#fff
class CWD,W1,W2 dir
class W3 found
class BUD warn
class INJ,TRIM proc
class AG agent
```
## Quick Start
```markdown theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
# Project Context
## Tech Stack
- Python 3.12, FastAPI, SQLAlchemy
- Tests with pytest; coverage >= 90%
## Style
- PEP 8; type hints everywhere; docstrings for public APIs
## Do
- Use dependency injection for database sessions
- Write one test per behaviour, not per function
## Don't
- Import from circular modules
- Use `global` variables
```
Now any `praisonai` command run inside the repo picks this up automatically:
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai code "Add a new user endpoint"
```
The agent already knows your stack, style rules, and conventions.
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
praisonai code --no-context "Explain what Python is"
```
The `--no-context` flag skips AGENTS.md injection for that run only.
```bash theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
PRAISON_NO_CONTEXT=true praisonai run task.yaml
```
Useful in CI jobs where project context would waste tokens and slow things down.
Large AGENTS.md files are trimmed to fit. Set the budget in `.praison.json`:
```json theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
{
"context_token_budget": 4000
}
```
Default is `8000` characters.
***
## Discovery Rules
```mermaid theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
graph TB
subgraph "Walk-up Discovery"
A["Start at cwd"] --> B{"AGENTS.md,\nCLAUDE.md, or\nPRAISON.md here?"}
B -->|Yes| C["Use this file\n(nearest wins)"]
B -->|No| D{".git directory\nhere?"}
D -->|Yes, at boundary| E["Stop — no context"]
D -->|No| F["Move to parent"]
F --> B
end
classDef start fill:#8B0000,stroke:#7C90A0,color:#fff
classDef decision fill:#F59E0B,stroke:#7C90A0,color:#fff
classDef found fill:#10B981,stroke:#7C90A0,color:#fff
classDef stop fill:#6366F1,stroke:#7C90A0,color:#fff
class A start
class B,D decision
class C found
class E,F stop
```
**File names searched (in order):** `AGENTS.md`, `CLAUDE.md`, `PRAISON.md`, `GEMINI.md`
**Stop condition:** A `.git` directory — the walk-up never crosses a git repository boundary.
**Nearest wins:** The first matching file found (starting from cwd and walking up) is used. Deeper files override ancestor files.
***
## Precedence
| Setting | Overrides |
| ----------------------------------------- | ------------------------------------- |
| `--no-context` flag | Everything — disables for this run |
| `PRAISON_NO_CONTEXT=true` env var | Config-level default |
| `context_token_budget` in `.praison.json` | Sets trim budget |
| Default ON | Base behaviour when nothing overrides |
***
## What to Put in AGENTS.md
Keep it concise — the budget is finite. Useful content includes:
* **Tech stack** — language versions, key frameworks, database
* **Code conventions** — naming, formatting, patterns to follow
* **Do/Don't rules** — specific things the agent should or should not do
* **Key file locations** — where models, routes, tests live
* **Project-specific vocabulary** — domain terms, component names
Avoid:
* Long prose the agent doesn't need for most tasks
* Secrets or credentials (they will end up in logs)
* Entire source files or large schemas — use `--file` flags instead
***
## Best Practices
Everyone on the team benefits when the agent knows the project conventions. Treat AGENTS.md like `.editorconfig` — check it in, keep it updated as the project evolves.
The default `context_token_budget` is 8000 characters (\~2000 tokens). Long AGENTS.md files are trimmed from the bottom up — keep the most important rules at the top.
If your monorepo has a `backend/` with Python conventions and a `frontend/` with TypeScript conventions, add separate AGENTS.md files in each subdirectory. The walk-up stops at the nearest one.
If your CI doesn't need project context (e.g., a simple test-and-lint pipeline), disable it:
```yaml theme={"theme":{"light":"vitesse-light","dark":"vitesse-dark"}}
env:
PRAISON_NO_CONTEXT: "true"
```
***
## Related
Other ways to inject context into agent sessions
Walk-up discovery for .praison.json project config
Generate a repo-tailored AGENTS.md with `praisonai init --generate`