Skip to content

Custom Agents

Jump to bottom
wody edited this page May 24, 2026 · 4 revisions

Custom Agents (.agents/)

Introduced in v0.31.0. 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). Until v0.31.0 the only way to manage these was:

  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 new 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.

Related

Clone this wiki locally