Opencode Agent Runner Shell Function

opencode.1.md

OPENCODEAGT(1)

NAME

opencodeagt - One-shot execution of Opencode agents from markdown files

SYNOPSIS

opencodeagt [AGENT_NAME] [FLAGS...]

DESCRIPTION

opencodeagt facilitates a workflow for using custom Opencode agents defined in the .opencode/agent/ directory.

Opencode allows you to place custom agent definitions in .opencode/agent/. This script parses out the model from the YAML frontmatter and the prompt from the file body. It then runs the agent as a one-shot task using the opencode run command.

This enables you to define reusable, pre-configured agent prompts and models in your project repository and trigger them quickly from the command line without manual configuration every time.

NOTE: This tool passes any additional command-line arguments directly to opencode run.

INSTALLATION

To use this function permanently, append it to your shell configuration:

cat opencodeagt.sh >> ~/.zshrc

Or source it in your current session:

source opencodeagt.sh

The function is designed for zsh but should be compatible with bash.

DIRECTORY STRUCTURE

The function expects the following directory structure in your project:

.
└── .opencode
    └── agent
        └── [AGENT_NAME].md

AGENT FILE FORMAT

Agent files must be Markdown files with YAML frontmatter specifying the model. The content after the frontmatter is used as the prompt.

Example (.opencode/agent/DataTester.md):

---
model: opencode/gemini-3-flash
---
Run regression tests and export the results to CSV...

EXAMPLES

Basic usage: Run the 'DataTester' agent:

opencodeagt DataTester

With additional flags: Pass flags supported by opencode run directly to the script:

opencodeagt DataTester --print-logs --log-level DEBUG

TROUBLESHOOTING

The tool seems to hang: If the tool appears to hang or stop responding, it is likely waiting for user approval on stdin (if the underlying model or configuration requires it).

To fix this:

1. Check the terminal for any prompt requests.
2. Check opencode run --help for any flags that might control interactivity or permissions in your specific version.

SEE ALSO

opencode(1)

opencodeagt.sh

# shellcheck disable=SC2148
opencodeagt() {
  # set -x
  local agent_name="${1}"
  local agent_file=".opencode/agent/${agent_name}.md"

  # 1. Check if agent file exists
  if [[ ! -f "$agent_file" ]]; then
    echo "Error: Agent file '$agent_file' not found in $(pwd)" >&2
    return 1
  fi

  # 2. Extract model from frontmatter
  local model
  model=$(awk '
    NR==1 && /^---$/ { in_fm=1; next }
    /^---$/ { in_fm=0; exit }
    in_fm && /^model:/ { sub(/^model:[[:space:]]*/, ""); print; exit }
  ' "$agent_file")

  if [[ -z "$model" ]]; then
    echo "Error: 'model' not specified in frontmatter of $agent_file" >&2
    return 1
  fi

  # 3. Extract body (everything after second ---)
  local body
  body=$(awk '
    BEGIN { seps=0 }
    /^---$/ { seps++; next }
    seps >= 2 { print }
  ' "$agent_file")

  if [[ -z "$body" ]]; then
    echo "Error: No prompt body found in $agent_file" >&2
    return 1
  fi

  # 4. Run opencode
  # Using "$body" ensures newlines are preserved
  echo "Running opencode with model: $model"
  # Pass any remaining arguments ($@) to opencode run to support flags like --yolo or --allow-*
  opencode run --model "$model" "$body" "${@:2}"
  # set +x
}