Context Files

Context files are Markdown documents that provide Mona with project-specific knowledge. They are automatically read at the start of every conversation in that directory.

Supported context files

MonoClaw looks for these files in order of priority:

.monoclaw.md

The preferred context file for MonoClaw projects:

# Project Context

## Stack
- Next.js 15 + React 19
- TypeScript
- Tailwind CSS
- shadcn/ui

## Conventions
- Use functional components with hooks
- Prefer `async/await` over callbacks
- Colocate tests with `*.test.ts` suffix

## Commands
- `npm run dev` — Start dev server
- `npm run build` — Production build
- `npm run test` — Run test suite

AGENTS.md

A cross-compatible standard adopted by multiple AI tools:

# Agent Instructions

## Code Style
- Follow the existing patterns in the codebase
- Use explicit types over `any`
- Comment complex business logic

## Testing
- Write tests for new features
- Run existing tests before committing

SOUL.md

Global personality file stored at ~/.monoclaw/SOUL.md:

# Mona's Voice

- Warm but professional
- Concise — no filler words
- Honest about limitations
- Uses British spelling

This shapes Mona's personality across all projects.

How context files are loaded

1. Mona checks the current working directory for context files
2. She walks up the directory tree until she finds one
3. All found files are loaded and merged
4. Global SOUL.md is always loaded last

Context file limits

• Max size — 4K tokens per file
• Max files — 5 files per conversation
• Nesting — Mona reads up to 3 parent directories

Best practices

• Keep it current — Update context files when the stack changes
• Be specific — Include exact commands and file paths
• Avoid duplication — Don't repeat what's in skills
• Version it — Commit context files to git so teammates share them

Context file vs skills

Disabling context files

For a single session:

monoclaw --no-context

Or permanently:

# ~/.monoclaw/config.yaml
context:
  enabled: false