---
title: "External Agents"
source: https://docs.autohand.ai/working-with-autohand-code/external-agents
---

# External Agents

Load agent definitions from external directories and integrate with agents created for other AI coding tools like Claude Code and Codex.

## 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:

| Location | Source |
|---|---|
| ~/.autohand/agents/ | Autohand native |
| ~/.claude/agents/ | Claude Code |
| ~/.codex/agents/ | OpenAI Codex |
| ~/.gemini/agents/ | Google Gemini |
| <project>/.autohand/agents/ | Project-specific |

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`:

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

Settings:

| Key | Description | Default |
|---|---|---|
| paths | Array of directories to search for agents | Claude, Codex defaults |
| autoCopy | Copy external agents to Autohand location | true |

## Agent file format

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

``` yaml
---
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

| Field | Required | Description |
|---|---|---|
| name | Yes | Unique identifier for the agent |
| description | Yes | Brief description shown in listings |
| model | No | Override the default model for this agent |
| allowed-tools | No | Space-separated list of permitted tools |
| temperature | No | Model temperature (0-1) |
| max-tokens | No | Maximum response tokens |

## Using external agents

List and use agents with slash commands:

``` bash
# 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:

``` bash
# 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

``` bash
# 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