robotter 0.8.0

Project:

Package:

Development:

Contents

• Overview
  • Rendering a template
  • Editing an agent's configuration
  • Browsing an agent's global configuration
• Installation
• Development
• Additional Information
• License

Overview

robotter composes GenAI "dotfiles" (the instruction/configuration files read by AI coding agents) from a single source template.

Different agents read their configuration from different locations under different filenames. robotter renders one Jinja2 template and writes the result to the appropriate location(s) for a target agent, at either global (user-level) or project scope:

Templates may include optional YAML frontmatter (preserved in the rendered output) and may compose other templates via the include_configuration("<relative path>") function, letting you maintain shared content once and assemble agent-specific files from it.

How to use robotter

Render a template to an agent's configuration location(s):

uvx robotter render <template> <agent> [<dir>] [--verbose] [--debug]

Examples

Render instructions.md to the current user's global Claude Code configuration:

uvx robotter render instructions.md claude-code

Render instructions.md to the project-level OpenCode configuration under ./my-project:

uvx robotter render instructions.md opencode ./my-project

Editing an agent's configuration

Open an agent's rendered configuration file in an editor:

uvx robotter edit <agent> [<dir>] [--verbose] [--debug]

The configuration file must already exist (for example, produced by a prior render); edit fails if it does not. The editor is selected from the VISUAL or EDITOR environment variable when set, otherwise the operating system's default handler for the file is used.

Examples

Edit the current user's global Claude Code configuration:

uvx robotter edit claude-code

Edit the project-level OpenCode configuration under ./my-project:

uvx robotter edit opencode ./my-project

Browsing an agent's global configuration

Open an agent's global (user-level) configuration directory in a file browser:

uvx robotter browse <agent> [--verbose] [--debug]

The directory is opened using the operating system's default file browser. The directory must already exist (for example, produced by a prior render); browse fails if it does not.

Example

Browse the current user's global Claude Code configuration directory:

uvx robotter browse claude-code

Example Configuration

A configuration file is a Jinja2 template with optional YAML frontmatter. Use the include_configuration("<relative path>") function to compose shared content from another configuration file, letting you maintain that content once and reuse it across multiple templates.

The following instructions.md template includes a shared shared/coding-standards.md file:

---
description: Instructions for AI coding agents
---
# Project Instructions

## Overview
This project composes GenAI dotfiles from a single source template.

## Coding Standards
{{ include_configuration("shared/coding-standards.md") }}

The included shared/coding-standards.md file (its frontmatter, if any, is ignored when included):

- Prefer clarity over cleverness.
- Write tests for all new functionality.
- Document public interfaces.

The path passed to include_configuration is resolved relative to the file that contains the call, so a template in one directory can include a file located in a subdirectory ("shared/coding-standards.md") or a parent directory ("../coding-standards.md"). Included files may themselves call include_configuration, allowing configuration to be composed from arbitrarily nested fragments.

Rendering the instructions.md template above produces the following output (the frontmatter is preserved; the include_configuration call is replaced with the rendered content of the included file):

---
description: Instructions for AI coding agents
---
# Project Instructions

## Overview
This project composes GenAI dotfiles from a single source template.

## Coding Standards
- Prefer clarity over cleverness.
- Write tests for all new functionality.
- Document public interfaces.

Installation

Note that it isn't necessary to install robotter when running via uvx.

Verifying Signed Artifacts

Artifacts are signed and verified using py-minisign and the public key in the file ./minisign_key.pub.

To verify that an artifact is valid, visit the latest release and download the .minisign signature file that corresponds to the artifact, then run the following command, replacing <filename> with the name of the artifact to be verified:

uv run --with py-minisign python -c "import minisign; minisign.PublicKey.from_file('minisign_key.pub').verify_file('<filename>'); print('The file has been verified.')"

Development

Please visit Contributing and Development for information on contributing to this project.

Additional Information

Additional information can be found at these locations.

License

robotter is licensed under the MIT license.