Key Discovery: How to Invoke Agents in Headless Mode

✅ Successful Pattern

To invoke a custom agent in claude -p headless mode:

Terminal window
claude -p "Use the [agent-name] and provide its complete response. [your request]"

Required elements:

  1. Explicit agent name: “Use the [agent-name]”
  2. Request for response: “and provide its complete response”
  3. Your actual task/question

Example: Simple Agent Test

Terminal window
cd /path/to/project
claude -p "Use the simple-agent and provide its complete response. Test agent invocation."

Output:

SIMPLE AGENT ACTIVATED


Agent Name: simple-agent
Model: haiku
Status: Successfully invoked!


You asked me to: [task description]


This confirms that:
✅ The agent file was loaded
✅ The agent was successfully invoked
✅ Custom agents are working correctly

Testing Workflow

1. Create a Simple Test Agent

Create .claude/agents/simple-agent.md (minimal agent for testing):

---
name: simple-agent
description: A simple test agent that responds with a specific message
tools: Read, Write
model: haiku
---


You are a simple test agent. Always respond with:


🤖 SIMPLE AGENT ACTIVATED 🤖
Agent: simple-agent
Status: Working!

2. Test from Project Root

Important: Run from the project directory where .claude/agents/ is located:

Terminal window
cd /path/to/your/project
claude -p "Use the simple-agent and provide its complete response."

3. Verify Agent Loading

Check for both models in JSON output:

Terminal window
claude -p "Use the simple-agent and provide its complete response." \
  --output-format json | jq '.modelUsage'

Should show:

  • Agent’s model (e.g., haiku)
  • Main instance model (e.g., sonnet)

What We Learned

❌ What DOESN’T Work

Relying on automatic delegation:

Terminal window
# This doesn't invoke the custom agent reliably
claude -p "Generate a rate card from the files"

The main instance responds instead of delegating to the specialized agent.

✅ What DOES Work

Explicit agent invocation:

Terminal window
# This correctly invokes the custom agent
claude -p "Use the rate-card-extractor-generator agent and provide its complete response. Generate a rate card from files X and Y."

Limitations & Observations

1. Response Transformation

  • Agent responses may be summarized/formatted by the main instance
  • Emoji and special formatting might be stripped
  • Core content is preserved

2. Complex Agents May Timeout

  • Large, detailed agents (like rate-card-extractor-generator) may timeout in headless mode
  • Simple agents (like simple-agent) work quickly
  • Consider using --timeout or breaking complex tasks into steps

3. Model Usage Indicator

When an agent is invoked, you’ll see TWO models in usage:

  • Agent’s model (does the work)
  • Main instance model (delegates and formats response)

Example from JSON output:

{
  "modelUsage": {
    "claude-haiku-4-5-20251001": {
      "inputTokens": 1887,
      "outputTokens": 217
    },
    "claude-sonnet-4-5-20250929": {
      "inputTokens": 4,
      "outputTokens": 264
    }
  }
}

Best Practices

For Testing Agents

  1. Start simple: Create a minimal test agent first
  2. Explicit invocation: Always name the agent and request its response
  3. Run from project root: Where .claude/agents/ exists
  4. Check model usage: Verify both agent and main models were used
  5. Iterate quickly: Headless mode is faster than restarting interactive sessions

For Development Workflow

Terminal window
# 1. Edit agent
vim .claude/agents/my-agent.md


# 2. Test immediately (no restart needed!)
claude -p "Use the my-agent and provide its complete response. Test task."


# 3. Iterate
vim .claude/agents/my-agent.md
claude -p "Use the my-agent and provide its complete response. Different test."


# 4. When satisfied, use in interactive session
# (restart interactive Claude Code to load agent there)

Common Issues & Solutions

Issue: “Agent not found” or generic response

Solution: Ensure you’re running from the project directory:

Terminal window
pwd  # Should show your project root
ls .claude/agents/  # Should list your agents

Issue: Timeout

Solution: Complex agents need more time:

Terminal window
# Increase timeout
timeout 120 claude -p "Use the complex-agent..."


# Or simplify the request
claude -p "Use the complex-agent and describe what you would do (don't execute)"

Issue: Response doesn’t match agent’s instructions

Check:

  1. Agent file syntax (YAML frontmatter correct?)
  2. Agent description matches task
  3. You’re explicitly requesting agent invocation
  4. You’re asking for complete response

Example: Rate Card Agent Test

Simple Test (Quick)

Terminal window
claude -p "Use the rate-card-extractor-generator agent and provide its complete response. What files do you need to process rate cards?"

Complex Test (May timeout)

Terminal window
# Full processing - may need interactive mode
claude -p "Use the rate-card-extractor-generator agent and provide its complete response. Generate rate card from Rate cards/Absorption Co 2025 - Rate Card.xlsx and Rate cards/Stord Mapping key - Generic.xlsx"

Alternative: Test Logic Without Execution

Terminal window
claude -p "Use the rate-card-extractor-generator agent and provide its complete response. If given rate card files, describe your processing steps without executing."

Summary

Headless agent invocation formula:

claude -p "Use the [AGENT-NAME] and provide its complete response. [TASK]"
          ^^^^^^^^^^^^^^^^       ^^^^^^^^^^^^^^^^^^^^^^^^^^^^  ^^^^^^
          Explicit agent         Request raw output            Your task

This enables:

  • ✅ Rapid iteration during agent development
  • ✅ Testing without restarting interactive sessions
  • ✅ Verification that agents work correctly
  • ✅ Debugging agent behavior

Perfect for the agent development workflow we established earlier!