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.
Project instructions: CHAMPREP.md
Section titled “Project instructions: CHAMPREP.md”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.mdat 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.
| Action | How |
|---|---|
| Create one | /init surveys the repository and writes CHAMPREP.md, keeping useful content from an existing AGENTS.md. |
| Add a note | Start 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.
Custom commands
Section titled “Custom commands”A custom command is a Markdown prompt template you run as /<name>.
| Location | Scope |
|---|---|
.champrep/commands/NAME.md | This project |
$CONFIG/ai/commands/NAME.md | You |
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 fixargument-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.mdRecent changes:!`git log --oneline -5`$ARGUMENTSis everything after the command name;$1,$2, … are single arguments. If the template uses neither, the arguments are appended.@pathincludes 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-toolslimits the tools for that turn, andmodeloverrides the model.
Skills
Section titled “Skills”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.
| Location | Scope |
|---|---|
.champrep/skills/NAME/SKILL.md | This project |
$CONFIG/ai/skills/NAME/SKILL.md | You |
---description: Release checklist for this servicewhen_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>.
Custom agents
Section titled “Custom agents”A custom agent is a subagent with its own instructions, tools, and model.
| Location | Scope |
|---|---|
.champrep/agents/NAME.md | This project |
$CONFIG/ai/agents/NAME.md | You |
---name: test-writerdescription: 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-editsisolation: worktree---You write focused unit tests that follow this project's existing style.descriptiontells the main agent when to delegate to it.toolsnarrows the tools; leave it out to inherit the session’s tools.permission_modecan only make the agent stricter than your session.isolation: worktreeruns 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.
| Event | Runs |
|---|---|
SessionStart | When a session starts. |
UserPromptSubmit | Before a prompt is sent. Can block it or add context. |
PreToolUse | Before a local tool runs. Can block it. |
PostToolUse | After a local tool runs. Can add feedback to the result. |
PermissionRequest | When a permission prompt is shown. |
Notification | When the agent notifies you. |
SubagentStop | When a subagent finishes. |
PreCompact | Before the conversation is compacted. |
Stop | When a turn ends. |
SessionEnd | When 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" } ] }}matcheris 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 areason, blocks the action where the event allows it.additionalContextin 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.
Look and feel
Section titled “Look and feel”| Command | Options |
|---|---|
/color | An accent colour for this project’s sessions, to tell parallel sessions apart: blue, cyan, green, yellow, orange, red, pink, magenta, purple, gray, or reset. |
/theme | auto, dark, light, high-contrast, or colorblind. NO_COLOR and --no-color turn colour off. |
/statusline | Pick 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-style | default, concise, explanatory, or learning. |
/vim | Vim-style editing in the prompt. |
/keybindings | View bindings; /keybindings edit opens $CONFIG/ai/keybindings.json. |
/config | All of the above on one screen. |
Local files
Section titled “Local files”The agent’s conversations live on your CHAMPREP AI account. Only machine-specific state is stored locally. Print every location on your machine with:
champrep ai paths| What | Where |
|---|---|
| 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 instructions | CHAMPREP.md |
| Worktrees | .champrep/worktrees/ |
Credentials are never stored in these files. They stay in the operating-system keychain.
| Root | macOS and Linux | Windows |
|---|---|---|
$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.