Create a project reviewer
Custom agents receive their own system prompt and perform a scoped task. They are different from command templates and internal orchestrator roles. You need a project, a CLI session and readable project code.
Create .lurus/agents/reviewer.md:
---
name: Reviewer
description: Inspect correctness and tests without modifying the project
tools:
- Read
- Grep
- Glob
- GitInspect
maxTurns: 12
---
Inspect the requested code. Report only concrete correctness and test-coverage findings with file references. Do not modify files.
For global use, put the same content at ~/.lurus/agents/reviewer.md. Start a new CLI session after creation or editing. Project agents replace global agents with the same key. The lowercase path/filename determines the key reviewer; name: Reviewer is only the display name.
Invoke and manage trust
Review the agent file before approving it. “Trust and run once” saves trust persistently, despite the wording. Running an agent may incur model costs.
/agents list
/agents show reviewer
/agents trust reviewer
/agents run reviewer Review the current changes and their tests.
/agents untrust reviewer
| Step | Expected effect |
|---|---|
/agents or /agents list | Lists custom agents only, with source, key, display name, trust, tools and optional turn limit. Not a catalogue of internal built-in roles. |
/agents show reviewer | Metadata and file path; does not display the full system prompt. |
/agents trust reviewer | Persists trust for the loaded source and file content. Review the file first. |
/agents run reviewer <prompt...> | Starts the custom agent directly with your task, rather than submitting a parent prompt first. Results, partial output, tokens/cost and cancellation status may be displayed. |
/agents untrust reviewer | Removes the matching persistent trust record. Does not delete the agent file. |
Without a task, run displays usage; an unknown key does not start an agent. An untrusted source triggers a trust dialog. “Trust and run once” actually persists trust here; the label does not mean temporary trust. If saving trust persistently fails, the CLI may display a warning even though the agent was approved for the current run. Check the trust status again after restarting.
Cancellation or reaching the turn limit can leave a partial result. Custom agents report results; they do not gain write roles. You can also explicitly ask the parent agent to invoke a custom agent; this is a different entry point from the direct slash command. /reviewer … is not automatically registered as an alias.
Frontmatter and turn limits
| Field | Type / example | Effect |
|---|---|---|
name | string, Reviewer | Display name, not the invocation key. |
description | string | Purpose in the list and agent description. |
| Markdown body | Text after frontmatter | The specialist agent’s system prompt. |
tools | string[], [Read, Grep] | Requested tools, intersected with the fixed custom-role ceiling. |
model | string from the public model list | Optional agent model; availability and plan restrictions still apply. Do not guess internal identifiers. |
maxTurns | finite number, 12 | Rounded down. Values below 1 are invalid and treated as absent; values above 50 are capped at 50. Without a valid value, 25 turns. |
A turn limit is not a fixed runtime or reserved budget. Model or tool failures can end a task earlier. Extra mode, isolation or arbitrary permission fields do not unlock agent capabilities.
Fixed tool ceiling
Custom agents can receive only these built-in tools:
Read
Glob
Grep
ListDirectory
SemanticSearch
RepoMap
GetMemory
GitInspect
- Missing
tools: the entire list above is the starting allowlist. tools: []: no tools.tools: [Read, Bash, Write]: only role-compatible tools remain, hereRead.- Agent frontmatter cannot unlock Bash, Exec, Write, Edit, MultiEdit, Delete, web tools or MCP.
- Mode, policy and permission checks apply in addition to the allowlist. A tool list is not blanket permission to read secrets or external paths.
Internal write-capable orchestrator roles are not custom agents. This ceiling is useful for a read-only reviewer. Running tests or modifying files requires a different workflow with explicit parent-agent permissions.
Trust binds source and content
Approval applies to the name, source, resolved path and contents of the entire file. Global and project files are separate sources. Frontmatter changes therefore also require review.
An already loaded agent prompt and hash do not refresh automatically from disk on every invocation. After editing:
- Start a new CLI session.
- Check
/agents show reviewerand its source. - Review the file and, if needed, run
/agents trust revieweragain. - Start the task with
/agents run reviewer ….
There are no supported /agents create, reload or remove subcommands. To remove an agent, deliberately remove your file manually and restart. Manage trust through the CLI rather than editing internal settings or registries.
Advanced: Git-only review
Create .lurus/agents/git-reviewer.md:
---
name: Git reviewer
description: Review tracked changes using read-only Git inspection
tools:
- GitInspect
- Read
maxTurns: 8
---
Inspect the current diff and read relevant files. Separate confirmed problems from suggestions. Do not change files or run commands.
/agents show git-reviewer
/agents trust git-reviewer
/agents run git-reviewer Check the current diff for regressions.
Expected result: a scoped read-only review report, no Git commit or shell test run. The key is git-reviewer, not Git reviewer.
Troubleshooting
| Problem | Action |
|---|---|
| Agent missing | Check project CWD, .md path, restart and path-derived key. Command/built-in collisions may skip an agent. |
| Wrong source | A project agent replaces a global file with the same key. |
| Trust requested again | Hash, source or path changed, or the previous persistence attempt failed. |
| Tool missing | Check the fixed role ceiling and an explicitly empty tool list. |
| Task incomplete | Check partial output and turn limit; scope the task more narrowly instead of bypassing tool protections. |
Next: permissions, skills, orchestration.