[BUG] Custom agents in ~/.claude/agents/ not discovered on Linux ARM (v2.0.14)

Resolved 💬 2 comments Opened Oct 11, 2025 by ghsaboias Closed Oct 11, 2025

Bug Description

Custom agents defined in ~/.claude/agents/ are not being discovered or loaded on Linux ARM (Raspberry Pi), while the same agents work correctly on macOS ARM with the same version.

Environment

Broken Platform:

  • OS: Linux (Raspberry Pi)
  • Architecture: ARM (aarch64)
  • Claude Code Version: 2.0.14
  • Installation Method: npm global install

Working Platform (for comparison):

  • OS: macOS
  • Architecture: ARM (Apple Silicon)
  • Claude Code Version: 2.0.14
  • Installation Method: npm global install

Steps to Reproduce

  1. Create custom agent files in ~/.claude/agents/ (e.g., test-simple.md, html-escaper.md)
  2. Verify files exist with proper frontmatter:

```yaml
---
name: test-simple
description: Use this for testing purposes
model: sonnet
---

You are a test agent.
```

  1. Start Claude Code and query available agents
  2. Observe that only 3 built-in agents are listed (general-purpose, statusline-setup, output-style-setup)

Expected Behavior

Custom agents from ~/.claude/agents/ should be discovered and available via the Task tool, just like they are on macOS ARM.

Actual Behavior

On Linux ARM, Claude Code only loads 3 built-in agents and completely ignores custom agent files in ~/.claude/agents/, even though the files exist with correct permissions (644) and valid frontmatter.

Verification

Linux ARM (Raspberry Pi):

$ ls -la ~/.claude/agents/
-rw-r--r-- 1 user user  7910 Oct  9 15:53 claude-code-specialist.md
-rw-r--r-- 1 user user 10862 Oct 10 12:52 conversation-parser-specialist.md
-rw-r--r-- 1 user user   300 Oct 11 10:57 html-escaper.md
-rw-r--r-- 1 user user 10291 Oct  9 15:56 telegram-bot-api-specialist.md
-rw-r--r-- 1 user user   106 Oct 11 10:54 test-simple.md

$ echo 'list available agents' | claude
# Returns only: general-purpose, statusline-setup, output-style-setup

macOS ARM (Working):

$ ls -la ~/.claude/agents/
-rw-r--r-- 1 user staff 35105 Oct  9 11:50 claude-code-specialist.md
-rw-r--r-- 1 user staff  9171 Sep  9 09:42 cloudflare-specialist.md
[... other agent files ...]

$ echo 'list available agents' | claude
# Returns 11 agents including all custom agents from ~/.claude/agents/

Additional Notes

  • Both systems use the same npm installation method
  • Agent files have identical formatting on both platforms
  • File permissions are correct (readable by user)
  • The bug appears to be specific to Linux ARM builds

Impact

Users on Raspberry Pi and other Linux ARM devices cannot use custom agents, which significantly limits the extensibility of Claude Code on these platforms.

View original on GitHub ↗

This issue has 2 comments on GitHub. Read the full discussion on GitHub ↗