Skip to main content

​
Overview

Poolside lets you control how agents behave using two configuration files:
  • AGENTS.md: Project-level instructions
  • .poolside: User-level instructions
These files let you specify custom instructions, preferences, conventions, architectural context, and constraints that Poolside agents should follow when generating completions or making changes. If both files are present, Poolside adds the contents of both to the agent’s context. When instructions conflict, more specific instructions (for example, project-level rules) take precedence. Like all prompts, instructions are not deterministic.

​
How configuration is applied

Agent behavior configuration is applied automatically whenever Poolside runs an agent in the IDE or CLI.
  • User-level configuration applies across all projects on your system
  • Project-level configuration applies only within a specific repository or directory
  • Both configurations are combined and sent to the model at runtime
User-level .poolside configuration is always included if present. These configuration files apply to the default Poolside Assistant and to any custom agents you run, unless overridden by agent-specific instructions.

​
AGENTS.md

Use an AGENTS.md file to define project-specific instructions, guidelines, and conventions. Common uses include:
  • Defining coding standards and conventions
  • Providing context about your project’s structure or architecture
  • Setting constraints or preferences for agent behavior
You can place an AGENTS.md file:
  • At the root of a repository
  • In individual subdirectories to scope behavior more narrowly

​
Example AGENTS.md

## Project structure

- `/routes`: HTTP routes used for the developer-facing API.
- `/views`: All Jinja views should be placed here.

## Code style
- Always use the `loguru` package for logging.
- Begin any class names for new endpoints with `my`.

​
Resolution rules

To determine which AGENTS.md file applies, Poolside walks up the directory tree from the project root until it finds an AGENTS.md file.
  • In editors, this walk is based on the project root.
  • When using the CLI, it is based on the current working directory.
Example: 
~/dev
├── repo
│   ├── AGENTS.md   # config A
│   └── pkg
│       └── backend
│           └── AGENTS.md   # config B
  • Project root is ~/dev/repo/pkg/backend → uses config B and the user config
  • Project root is ~/dev/repo → uses config A and the user config
  • Project root is ~/dev → uses only the user config

​
.poolside

Use a .poolside file to define preferences that apply across all projects on your system. This file is a plain Markdown file, just like AGENTS.md, and is sent to the model in addition to any project-level instructions. The user-level configuration file is located at: 
~/.config/poolside/.poolside
You can override this location by setting the XDG_CONFIG_HOME environment variable.

​
Example .poolside

- If I ask for bash one-liners, give me the code first and any explanation afterwards.

## Code style
- In JavaScript, use `async/await` instead of `Promise` syntax.
- In HTML and CSS, use flex-box for any new layout code.
- Always add docstrings to any new methods.

​
Tips and caveats

  • Keep rules concise and split them into sections using Markdown headers.
  • Large blocks of text often perform worse than individual, explicit instructions.
  • If the model struggles to follow an instruction, include a short example.
  • Use these files to control output format (verbosity, code-only responses, etc.).
  • Poolside prioritizes rules defined in these files unless overridden by user prompts.
  • Empty .poolside and AGENTS.md files are not sent to the model.
For more guidance, see Prompting best practices.