Context Files

Overview

Loop loads project instructions into the system prompt from the agent directory, your home directory, and the working directory and its parents.

Supported Files

In each directory, Loop loads every group that exists. Within a group, the first spelling wins.

File	Description
`AGENTS.md` or `AGENTS.MD`	Agent instructions
`CLAUDE.md` or `CLAUDE.MD`	Claude-compatible instructions
`CLAUDE.local.md`	Local instructions, usually left uncommitted
`.claude/CLAUDE.md`	Claude project file

Search order:

The agent directory (~/.loop/agent/, or LOOP_CODING_AGENT_DIR)
~/.claude/CLAUDE.md
The working directory, then each parent up to the filesystem root

All of those files are appended to the system prompt inside <project_context>. A symlink or a second copy with the same contents is included once.

~/.loop/agent/AGENTS.md
~/.claude/CLAUDE.md
/home/user/project/AGENTS.md
/home/user/project/src/AGENTS.md
/home/user/project/src/CLAUDE.local.md
/home/user/project/src/.claude/CLAUDE.md

Writing Context Files

AGENTS.md

# Project: My API Server

## Tech Stack
- Rust with Actix-Web
- PostgreSQL with sqlx
- Redis for caching

## Coding Conventions
- Use `anyhow::Result` for error handling in application code
- Use `thiserror` for library error types
- All public functions must have doc comments
- Tests go in `tests/` not inline

## Architecture
- Handlers in `src/handlers/`
- Business logic in `src/services/`
- Database queries in `src/db/`
- Never put business logic in handlers

## Important Notes
- The `users` table has a soft-delete column `deleted_at`
- Rate limiting is handled by the `RateLimiter` middleware
- All API responses use the `ApiResponse<T>` wrapper

Best Practices

Be specific about conventions

Instead of “follow best practices,” specify exactly what patterns to use:

- Error handling: Use `?` operator with `anyhow::Context`
- Logging: Use `tracing` macros, not `println!`
- Tests: Use `#[tokio::test]` for async tests

Document non-obvious architecture

Help the agent understand design decisions:

We use the repository pattern. Each entity has:
- A `Repository` trait in `src/repos/traits.rs`
- A PostgreSQL implementation in `src/repos/pg/`
- Never access the database directly from handlers

Keep it focused

Context files consume tokens. Focus on information the agent needs to write correct code — skip general documentation the agent can find by reading source files.

Disabling Context Files

Skip context file loading with the --no-context-files or -c flag:

loop --no-context-files
loop -c

This is useful when:

Context files are large and you want to save tokens
You’re working outside the project’s conventions
You want a clean agent context

Claude Code Compatibility

Loop loads CLAUDE.md, CLAUDE.local.md, and .claude/CLAUDE.md alongside AGENTS.md. If you’re migrating from Claude Code, your existing context files work without changes.

You can maintain a single AGENTS.md file that works with both Loop and other AI coding tools that support the convention.

Getting Started

Guides

Features

Context Files

Overview

Supported Files

Writing Context Files

AGENTS.md

Best Practices

Disabling Context Files

Claude Code Compatibility

​Overview

​Supported Files

​Writing Context Files

​AGENTS.md

​Best Practices

​Disabling Context Files

​Claude Code Compatibility

Overview

Supported Files

Writing Context Files

AGENTS.md

Best Practices

Disabling Context Files

Claude Code Compatibility