Skip to content

Custom Agents

Jump to bottom
Sia edited this page May 31, 2026 · 4 revisions

Custom Agents (.agents/)

Manage Claude Code's custom sub-agents (~/.claude/agents/*.md) through a UI instead of docker exec + a text editor.

View at /agents (left nav: "Agents").

Why a UI

Claude Code reads ~/.claude/agents/*.md on startup and exposes each as a named sub-agent (via the agent tool or /agents slash command). Without the UI, the only way to manage these would be:

  1. docker exec -it --user vibe vibe-coder-server bash
  2. vi ~/.claude/agents/code-reviewer.md
  3. exit, restart the session, hope you got the YAML frontmatter right.

The UI replaces all of that with:

  • A list view (name + size + last-modified + first 200-char preview).
  • A monospaced edit textarea (up to 64 KB body).
  • Delete buttons with confirm() guard.
  • Atomic write (<name>.md.tmp then move REPLACE_EXISTING) so a Ctrl-C mid-save doesn't leave the file half-written.
  • Strict name sanitization ([A-Za-z0-9._-]{1,64}, no leading .).

What an agent file looks like

Claude Code's docs are the source of truth, but the basic shape is:

---
name: code-reviewer
description: Reviews PRs for security issues before merge
---

You are a security-focused code reviewer. When asked to review code:

1. Identify common OWASP Top 10 patterns.
2. Flag any use of `eval`, `exec`, raw SQL, or shell concatenation.
3. Suggest specific remediations with file:line references.

Be concise. Skip cosmetic / style suggestions unless explicitly asked.

The page links out to Anthropic's official sub-agent documentation for the full frontmatter reference.

Where files live

Inside the container: ${CLAUDE_CONFIG_DIR}/agents/<name>.md where CLAUDE_CONFIG_DIR defaults to /home/vibe/.claude.

On the host: ${VIBE_DATA_ROOT}/claude/agents/<name>.md because of the bind mount described in Data Volumes & Backup. So agents survive docker compose pull && up -d --force-recreate like every other piece of persistent state.

Limits

Constraint Value Why
Name length 1–64 chars Filesystem-safe + visually scannable
Name charset [A-Za-z0-9._-] Path traversal / shell escape safety
Body size 64 KB max Sub-agent definitions are short; cap prevents accidental log-paste DoS
File extension .md only Filter the listing to known formats
Hidden files Rejected (no leading .) Avoid .git/-style traps

Audit

Action Logged as
Create / overwrite agent.save OK
Delete agent.delete OK / FAIL

See Audit Log for filter recipes.

JSON API for dispatch UI

The console page (and any 3rd-party client) can fetch the registered agents through GET /api/agents (Bearer):

curl -H "Authorization: Bearer $TOKEN" http://localhost:17880/api/agents
# → { "agents": [ {"name":"code-reviewer", "sizeBytes":1234, "preview":"..."}, ... ] }

The browser console exposes an @ Agent dispatch dropdown next to the prompt template picker. Selecting an agent prepends Use the <agent-name> sub-agent to to the prompt input — one-click invocation of Claude Code's standard sub-agent mechanism. The Android client and the VS Code extension can adopt the same UX with the same endpoint.

Real sub-agent process pool

For parallel sub-agent execution (e.g. reviewer + frontend + backend all working on the same project at once) see Multi-Agent Sub-Agent Pool. The dispatch dropdown runs inside the single project Claude child; the pool spawns one child per (projectId, agentName) so each agent has its own console, session-id, and WebSocket stream.

Both UX paths share this /agents registry — the pool reads the same .md files. Manage definitions here, dispatch from anywhere.

Related

Clone this wiki locally