External Agents

Cross-tool compatibility

Autohand can load agent definitions from directories used by other AI coding assistants. This means you can:

• Reuse existing agents: Agents you've created for Claude Code or Codex work in Autohand
• Share across tools: Write once, use everywhere
• Migrate gradually: Keep using your existing agent library

Agent discovery

Autohand searches for agents in these locations:

Agents from external locations are automatically copied to your Autohand directory for caching and offline access.

Configuring external paths

Add custom agent directories in your settings.json:

{
  "externalAgents": {
    "paths": [
      "~/.claude/agents",
      "~/.codex/agents",
      "~/my-company/shared-agents"
    ],
    "autoCopy": true
  }
}

Settings:

Agent file format

Agent definitions are markdown files with YAML frontmatter. The format is compatible across tools:

---
name: code-reviewer
description: Review code for bugs, security issues, and best practices
model: claude-sonnet-4
allowed-tools: read_file search git_diff
---

# Code Review Agent

You are an expert code reviewer. When reviewing code:

1. Check for bugs and logic errors
2. Identify security vulnerabilities
3. Suggest performance improvements
4. Ensure code follows project conventions

Be specific in your feedback and provide examples of how to fix issues.

Frontmatter fields

Using external agents

List and use agents with slash commands:

# List all agents (including external)
/agents

# View agent details
/agents info code-reviewer

# Create a new agent
/agents-new

Agents can also be invoked programmatically:

# Delegate a task to an agent
"Use the code-reviewer agent to review the changes in this PR"

# Run with a specific agent from CLI
autohand --agent code-reviewer --prompt "Review src/auth/login.ts"

Agent delegation

Autohand can delegate tasks to specialized agents:

• delegate_task: Send a task to a specific agent
• delegate_parallel: Run up to 5 agents in parallel

# Single agent delegation
"Delegate the security review to the security-auditor agent"

# Parallel execution
"Run the code-reviewer, test-writer, and docs-updater agents in parallel on this PR"

Syncing agents

When autoCopy is enabled, Autohand syncs external agents on startup:

1. Scans configured external paths for agent files
2. Compares with cached copies in ~/.autohand/agents/
3. Updates cached copies if external versions are newer
4. Logs any new or updated agents

To force a resync, delete the cached agent and restart Autohand.

Best practices

• Use descriptive names: typescript-refactorer over agent1
• Limit tool access: Only allow tools the agent needs
• Be specific: Narrow agents perform better than general ones
• Version your agents: Keep agents in version control for your team
• Test before sharing: Verify agents work as expected

Troubleshooting

Agent not found

If an external agent isn't loading:

1. Check the file is named with .md extension
2. Verify the path is in your externalAgents.paths config
3. Ensure the YAML frontmatter is valid
4. Check file permissions are readable

Agent not updating

If changes to external agents aren't reflected:

1. Delete the cached copy: rm ~/.autohand/agents/agent-name.md
2. Restart Autohand to trigger resync