Skip to main content

​
Overview

Traycer allows you to create custom CLI agent templates with custom arguments and permissions for any CLI-based coding agent. This powerful feature enables you to pass special flags and create platform-specific configurations tailored to your workflow.

​
What are Custom CLI Agents?

Custom CLI agents allow you to:
  • Execute any CLI-based coding agent with custom arguments.
  • Pass special flags like --dangerous or --force for elevated permissions.
  • Create platform-specific templates for different environments.

​
Available Template Tags

Custom CLI agent templates support the following environment variables set by Traycer at runtime:
​
$TRAYCER_PROMPT
placeholder
required
The prompt content. This environment variable is required in all templates.
​
$TRAYCER_PHASE_ID
placeholder
Per-phase identifier for maintaining session across plan and verification.
​
$TRAYCER_PHASE_BREAKDOWN_ID
placeholder
Phase breakdown identifier for maintaining session across current phase list.
​
$TRAYCER_TASK_ID
placeholder
Task identifier for maintaining session across all phase iterations, plans, and verification execution

​
Creating Custom CLI Agents

Custom CLI Agents
1

1. Open Manage CLI Agents

Click the three dots on the top of the sidebar to open the context menu, then click “Manage CLI Agents”.
2

2. Click Add CLI Agent

Click “Add CLI Agent” to add a new custom CLI agent.
3

3. Choose scope

Select either User (personal CLI agents available across all projects) or Workspace (project-specific CLI agents stored in workspace settings).
4

4. CLI Agent Name

Provide a descriptive name for your custom CLI agent and click “Create CLI Agent”.
5

5. Add CLI Agent Command

Add your custom command to the created file and save it.

​
Template Scopes

Custom CLI agents can be created in two different scopes:
  • User scope: Personal CLI agents that are available across all your projects. These templates are stored in the home directory under .traycer/cli-agents and travel with you.
  • Workspace scope: Project-specific CLI agents that are stored in your workspace root under .traycer/cli-agents. These are ideal for team-shared configurations or project-specific agent setups.
Here are some popular CLI-based coding agents you can use with custom templates:
  • Claude Code CLI
  • Codex CLI
  • Gemini CLI
  • Cline CLI
  • Factory Droid CLI
  • Cursor CLI
  • Aider
The following are frequently used arguments. For more details, visit the official documentation.
Basic
#!/bin/sh
claude "$TRAYCER_PROMPT"
Verbose
#!/bin/sh
claude --verbose "$TRAYCER_PROMPT"
Dangerous Mode
#!/bin/sh
claude --dangerously-skip-permissions "$TRAYCER_PROMPT"

​
Using Custom Paths

If your CLI agent is installed at a custom location, you can specify the full path in your template: 
#!/bin/sh
/usr/local/bin/claude --verbose "$TRAYCER_PROMPT"
The $TRAYCER_PROMPT environment variable is required in all templates. The prompt content is securely passed via temporary files.
Flags like --dangerous grant elevated permissions to the agent. Always review what permissions you’re granting to CLI agents.

​
Use Cases

Custom CLI agents are particularly useful for:
  • Passing dangerous/elevated permissions flags.
  • Using custom model configurations.
  • Setting specific output formats.
  • Creating environment-specific agent configurations.

​
FAQ

Yes, you can pass any flags supported by your CLI agent, including --dangerous, --force, or other elevated permission flags. However, be cautious as these flags grant the agent more control over your system. Always understand what permissions you’re granting before using such flags.
You can share custom CLI agents with your team by creating them in Workspace scope. Workspace-scoped templates are stored in your project’s workspace root under .traycer/cli-agents, which can be committed to your repository. When team members pull the latest changes, they’ll automatically have access to the shared custom CLI agents. This approach ensures consistent agent configurations across your entire team.
User scope templates are stored in your personal settings and available across all projects. Workspace scope templates are project-specific and stored in the workspace settings, making them ideal for team collaboration.
Use .sh for shell scripts on Linux, macOS, or Git Bash on Windows. Use .bat for Windows Command Prompt or PowerShell. The extension determines how the template is executed.
Yes, you can edit any custom CLI agent template by clicking on it in the Custom CLI Agents section of Traycer settings. The template file will open for editing.
The template validation will fail. The $TRAYCER_PROMPT environment variable is required in all custom CLI agent templates as it contains the actual task instructions.
Yes, custom CLI agents that use supported CLI tools (like Claude Code CLI, Codex CLI, or Gemini CLI) can work with YOLO Mode for automated execution.
Yes, you can create multiple custom CLI agents with different names that use the same underlying CLI tool. For example, you could have “Claude Verbose”, “Claude Dangerous”, and “Claude Standard” - each with different flags but all calling the same claude CLI agent.
Traycer does not install CLI agents for you. You must install the CLI tool separately before creating a custom template. We recommend testing the CLI command in your terminal first to ensure it works correctly before adding it to a template.