Skip to main content

​
Overview

Traycer allows you to create custom CLI agent 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 CLI agent for different environments.

​
Available Template Tags

Custom CLI agents support the following environment variables set by Traycer at runtime:
VariableBash / Git BashPowerShell
TRAYCER_PROMPT"$TRAYCER_PROMPT""$env:TRAYCER_PROMPT"
TRAYCER_PROMPT_TMP_FILE"$TRAYCER_PROMPT_TMP_FILE""$env:TRAYCER_PROMPT_TMP_FILE"
TRAYCER_PHASE_ID"$TRAYCER_PHASE_ID""$env:TRAYCER_PHASE_ID"
TRAYCER_PHASE_BREAKDOWN_ID"$TRAYCER_PHASE_BREAKDOWN_ID""$env:TRAYCER_PHASE_BREAKDOWN_ID"
TRAYCER_TASK_ID"$TRAYCER_TASK_ID""$env:TRAYCER_TASK_ID"
TRAYCER_SYSTEM_PROMPT"$TRAYCER_SYSTEM_PROMPT""$env:TRAYCER_SYSTEM_PROMPT"
​
TRAYCER_PROMPT
placeholder
required
The prompt content. At least one of TRAYCER_PROMPT or TRAYCER_PROMPT_TMP_FILE must be referenced in your CLI agent template.
​
TRAYCER_PROMPT_TMP_FILE
placeholder
Temporary file path containing the prompt content. Ideal for large prompts that exceed environment variable size limits. Use commands like cat "$TRAYCER_PROMPT_TMP_FILE" (Bash) or Get-Content -Raw "$env:TRAYCER_PROMPT_TMP_FILE" (PowerShell) to read and pass the prompt content to the CLI agent at runtime. The temporary file is automatically cleaned up by Traycer after 30 seconds.
​
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
​
TRAYCER_SYSTEM_PROMPT
placeholder
System prompt to append to the CLI agent (environment variable set by Traycer at runtime). Use this with —append-system-prompt or equivalent flag to pass trusted instructions at the system level.

​
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 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 set up:
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"
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 CLI agents 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 CLI agents are stored in your personal settings and available across all projects. Workspace scope CLI agents are project-specific and stored in the workspace settings, making them ideal for team collaboration.
Yes, you can modify any custom CLI agent by clicking on it within the Custom CLI Agents section of Traycer settings. This will open the file for editing.
Bash (Linux/macOS/Git Bash) and PowerShell (Windows) use different syntax to reference environment variables:
ShellSyntaxExample
Bash / Git Bash"$VARIABLE_NAME"claude "$TRAYCER_PROMPT"
PowerShell"$env:VARIABLE_NAME"claude "$env:TRAYCER_PROMPT"
Key differences:
  • Bash uses $ followed by the variable name directly (e.g., $TRAYCER_PROMPT)
  • PowerShell uses $env: prefix before the variable name (e.g., $env:TRAYCER_PROMPT)
  • Double quotes are recommended in both shells to handle prompts containing spaces or special characters
Choose the appropriate syntax based on which shell your CLI agent script will run in. Git Bash on Windows uses Bash syntax, not PowerShell syntax.
The CLI agent validation will fail because at least one of $TRAYCER_PROMPT or $TRAYCER_PROMPT_TMP_FILE must be referenced in your CLI agent template to pass the task instructions to the agent.
TRAYCER_PROMPT is the recommended default for most use cases. Use TRAYCER_PROMPT_TMP_FILE when:
  • Dealing with very large prompts (multiple files, extensive context)
  • Encountering environment variable size limits (Windows: ~32KB, Linux/macOS: varies)
  • Experiencing prompt truncation issues
Both variables are always available. Use TRAYCER_PROMPT_TMP_FILE directly in your commands just like TRAYCER_PROMPT - no need for file reading commands.
Traycer creates a temporary file containing the prompt content and sets TRAYCER_PROMPT_TMP_FILE to the file path. When you reference $TRAYCER_PROMPT_TMP_FILE in your template, you need to read the file content using commands like cat "$TRAYCER_PROMPT_TMP_FILE" (bash/sh) or Get-Content -Raw "$env:TRAYCER_PROMPT_TMP_FILE" (PowerShell). This approach bypasses environment variable size limits that can cause issues with very large prompts. The temporary file is automatically cleaned up by Traycer after 30 seconds.
Yes, custom CLI agents 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 CLI agent. We recommend testing the CLI command in your terminal first to ensure it works correctly before adding it to an agent.