Skip to content
Documentation

Customize the AI agent

Everything on this page is a local file. Files under .champrep/ in a repository are shared with your team through git; files under $CONFIG/ai/ apply only to you, in every project. When a project and a user definition have the same name, the project one wins.

Project content in .champrep/ stays inactive until you trust the repository. See Repository trust.

CHAMPREP.md holds standing instructions for the agent: how to build and test the project, conventions, and things to avoid. The agent reads, at the start of each session:

  • $CONFIG/ai/CHAMPREP.md, your personal instructions for every project;
  • CHAMPREP.md at the project root and in each directory from the root down to where you started the agent.

If a directory has no CHAMPREP.md, an AGENTS.md there is used instead.

ActionHow
Create one/init surveys the repository and writes CHAMPREP.md, keeping useful content from an existing AGENTS.md.
Add a noteStart a prompt with #, for example # run make lint before committing.
View or edit/memory, or /memory edit [user|project|FILE] to open it in your editor.

Your CHAMPREP AI account memory, managed in your CHAMPREP AI settings on the web, applies in the terminal too. /memory shows it read-only.

A custom command is a Markdown prompt template you run as /<name>.

LocationScope
.champrep/commands/NAME.mdThis project
$CONFIG/ai/commands/NAME.mdYou

A file in a subfolder, such as commands/git/commit.md, becomes /git:commit. Create one with /commands new NAME and list them with /commands.

---
description: Explain a failing test and propose a fix
argument-hint: <test name>
allowed-tools: [local_read_file, local_grep, local_bash]
---
Find the test named $1, run it, and explain why it fails.
Relevant notes: @docs/testing.md
Recent changes:
!`git log --oneline -5`
  • $ARGUMENTS is everything after the command name; $1, $2, … are single arguments. If the template uses neither, the arguments are appended.
  • @path includes a workspace file. Secret files are never included.
  • !`command` runs a command when you invoke the template. You are asked to approve this once per template, and again whenever it changes.
  • allowed-tools limits the tools for that turn, and model overrides the model.

A skill is a folder of instructions, and optional supporting files, that the agent loads only when it needs it. Until then the model sees only the skill’s name and description, so many skills cost very little context.

LocationScope
.champrep/skills/NAME/SKILL.mdThis project
$CONFIG/ai/skills/NAME/SKILL.mdYou
---
description: Release checklist for this service
when_to_use: When the user asks to cut, tag, or publish a release
---
1. Confirm the changelog has an entry for the new version.
2. ...

/skills lists skills, including skills from your CHAMPREP AI account. Run one directly with /<skill-name>.

A custom agent is a subagent with its own instructions, tools, and model.

LocationScope
.champrep/agents/NAME.mdThis project
$CONFIG/ai/agents/NAME.mdYou
---
name: test-writer
description: Writes and fixes unit tests. Use after a code change.
tools: [local_read_file, local_grep, local_glob, local_edit_file, local_bash]
permission_mode: accept-edits
isolation: worktree
---
You write focused unit tests that follow this project's existing style.
  • description tells the main agent when to delegate to it.
  • tools narrows the tools; leave it out to inherit the session’s tools.
  • permission_mode can only make the agent stricter than your session.
  • isolation: worktree runs it in its own git worktree.

Manage agents with /agents create|edit|delete NAME. Start a session as an agent with champrep ai --agent NAME, or send it a prompt with @NAME prompt. See Subagents.

Hooks are shell commands the CLI runs at points in a session, for example to format files after an edit or to block certain commands.

EventRuns
SessionStartWhen a session starts.
UserPromptSubmitBefore a prompt is sent. Can block it or add context.
PreToolUseBefore a local tool runs. Can block it.
PostToolUseAfter a local tool runs. Can add feedback to the result.
PermissionRequestWhen a permission prompt is shown.
NotificationWhen the agent notifies you.
SubagentStopWhen a subagent finishes.
PreCompactBefore the conversation is compacted.
StopWhen a turn ends.
SessionEndWhen the session ends.

Configure hooks in any settings file:

{
"hooks": {
"PostToolUse": [
{ "matcher": "local_edit_file|local_write_file", "command": "npm run format --silent", "timeout": 30 }
],
"PreToolUse": [
{ "matcher": "local_bash", "command": "./scripts/check-command.sh" }
]
}
}
  • matcher is a regular expression on the tool name; leave it out to match every tool.
  • The hook receives a JSON description of the event on standard input.
  • Exit code 2, or JSON output with "decision": "block" and a reason, blocks the action where the event allows it. additionalContext in JSON output adds text for the model.
  • The default timeout is 60 seconds, and the maximum is 10 minutes.
  • Hooks run with your environment minus CHAMPREP credentials.

Manage hooks with /hooks, /hooks add EVENT [--matcher M] [--timeout S] [--scope user|project] -- COMMAND, /hooks disable ID, and /hooks enable ID.

CommandOptions
/colorAn accent colour for this project’s sessions, to tell parallel sessions apart: blue, cyan, green, yellow, orange, red, pink, magenta, purple, gray, or reset.
/themeauto, dark, light, high-contrast, or colorblind. NO_COLOR and --no-color turn colour off.
/statuslinePick segments from profile, model, context, branch, mode, cost, and tasks; use /statusline command CMD to show the first line of your own command’s output; /statusline reset restores the default.
/output-styledefault, concise, explanatory, or learning.
/vimVim-style editing in the prompt.
/keybindingsView bindings; /keybindings edit opens $CONFIG/ai/keybindings.json.
/configAll of the above on one screen.

The agent’s conversations live on your CHAMPREP AI account. Only machine-specific state is stored locally. Print every location on your machine with:

Terminal window
champrep ai paths
WhatWhere
CLI profiles and environments$CONFIG/config.toml
Your agent settings: rules, mode, theme, status line, hooks$CONFIG/ai/settings.json
Key binding overrides$CONFIG/ai/keybindings.json
Your personal instructions$CONFIG/ai/CHAMPREP.md
Your agents, commands, and skills$CONFIG/ai/agents/, commands/, skills/
Your local MCP servers$CONFIG/ai/mcp.json
Trusted projects$CONFIG/ai/trusted-projects.json
Recent conversations per directory, and task lists$STATE/ai/sessions.json
Prompt history (redacted and capped)$STATE/ai/history.jsonl
Debug logs (redacted, kept 7 days)$STATE/ai/logs/
File checkpoints$CACHE/ai/checkpoints/
Project settings (committable).champrep/settings.json, mcp.json, agents/, commands/, skills/
Your project overrides (git-ignored).champrep/settings.local.json
Project instructionsCHAMPREP.md
Worktrees.champrep/worktrees/

Credentials are never stored in these files. They stay in the operating-system keychain.

RootmacOS and LinuxWindows
$CONFIG$XDG_CONFIG_HOME/champrep, else ~/.config/champrep%APPDATA%\champrep
$STATE$XDG_STATE_HOME/champrep, else ~/.local/state/champrep%LOCALAPPDATA%\champrep\state
$CACHE$XDG_CACHE_HOME/champrep, else ~/.cache/champrep%LOCALAPPDATA%\champrep\cache

Set CHAMPREP_CONFIG_DIR to keep all three under one directory, in config/, state/, and cache/ subfolders. This is useful for portable installs and isolated CI runs.