AgentsDojo

A Claude Code SDK-based Agent framework with A2A protocol support and a pixel-art Monitor GUI.

Quick Start

npm install -g agents-dojo

# Create a project with a sample agent
mkdir my-project && cd my-project
agents-dojo init

# Start the server
agents-dojo

Creating Agents

Each agent lives in its own directory under agents/. The only required file is manifest.jsonc.

agents/my-agent/
├── manifest.jsonc          # required — agent identity, model, A2A card
├── context.md              # optional — custom system prompt
└── CLAUDE.md               # optional — extra rules and constraints

See agents/_template_echo/ for a complete manifest reference.

context.md — Custom System Prompt

context.md controls the agent's system prompt:

• Without context.md: The agent uses Claude Code's built-in default system prompt. This is ideal for code-related agents — they get full programming capabilities (file editing, bash, code analysis, etc.) out of the box.

• With context.md: The file content replaces the default system prompt entirely. Use this for agents whose role has nothing to do with coding — e.g. a chef, poet, or customer support agent. You define the persona, behavior rules, and output format from scratch.

CLAUDE.md — Extra Rules and Constraints

CLAUDE.md is loaded automatically by the Claude Code SDK (not by AgentsDojo). It appends to whatever system prompt is active — whether the default or a custom context.md.

Use CLAUDE.md for:

• Project-specific rules ("always use TypeScript", "never delete files")
• Coding conventions and style guides
• Build/test commands the agent should know about
• Safety constraints and guardrails

agents/code-reviewer/
├── manifest.jsonc          # identity
└── CLAUDE.md               # "Review for security issues. Run `npm test` after changes."

agents/poet/
├── manifest.jsonc          # identity
├── context.md              # "You are Poet Luna, a lyrical poet..."
└── CLAUDE.md               # "Always respond in English. Keep poems under 20 lines."

Monitor GUI

The Monitor GUI starts automatically when you run agents-dojo. It picks a free port for the WebSocket and launches the Vite dev server (installing dependencies on first run). The GUI URL is printed to the console.

agents-dojo                       # monitor starts automatically
agents-dojo --monitor-port=9000   # use a specific WS port
agents-dojo --no-monitor          # disable the monitor

Chat with Agents

Users can talk to agents via btw-style one-shot chat. This forks the agent's current session (preserving context), disables all tools (text-only reply), and discards the fork afterward — the main session is never affected.

# CLI
agents-dojo chat <agentId> <message>

# REST API
curl -X POST http://localhost:41241/btw/<agentId> \
  -H "Content-Type: application/json" \
  -d '{"message": "your question"}'

# Monitor GUI: click an agent sprite → Chat

Architecture

• Framework (src/): A2A server, Claude Code SDK bridge, monitor event bus
• Monitor (monitor/): React + Pixi.js GUI

Testing

npm test              # unit + component + integration
npm run test:e2e      # E2E (requires ANTHROPIC_API_KEY)

License

MIT