OpenAgentsControl/integrations/claude-code/README.md

OpenAgents ↔ Claude Code Integration

A bridge that allows Claude Code to use OpenAgents standards and context files.

Overview

This integration provides two-way compatibility between OpenAgents and Claude Code:

1. Auto-Convert: Convert OpenAgents to Claude Code format for distribution
2. Local Adapter: Immediate context-aware behavior when using Claude in this repo

Directory Structure

integrations/claude-code/
├── converter/           # Scripts to convert OpenAgents → Claude format
│   └── src/
│       └── convert-agents.js
├── generated/           # Output of conversion (gitignored)
│   ├── agents/
│   └── skills/
├── plugin/              # Final plugin files for distribution
│   ├── agents/
│   ├── skills/
│   └── .claude-plugin/
│       └── plugin.json
├── bootstrap-install.sh # One-line installer (downloads bundle)
└── install.sh           # Install script for distribution

Quick Start

For This Repository (Local Adapter)

Just run Claude in this repository:

cd /path/to/opencode-agents
claude

Claude will automatically:

• Load the openagents-standards Skill
• Use context-scout to find relevant context in .opencode/context/
• Apply OpenAgents standards to any task

⚠️ Claude CLI Workaround

If Claude doesn't auto-load the local adapter when run in this repository: 1. **Restart Claude Code** after any changes to `.claude/` 2. **Explicitly reference the context** in your request: ``` "Load context from .claude/skills/openagents-standards/SKILL.md and .claude/agents/context-scout.md, then help me create a new agent" ``` 3. **Manual trigger** - if the Skill doesn't auto-trigger, start your request with: ``` [Use OpenAgents standards] ``` This will activate the context loading workflow. **Known Issue**: Skills auto-trigger based on Claude's heuristic. If it doesn't trigger: - The `context-scout` subagent will still be available - You can call it manually: `task(subagent_type="context-scout", ...)` - Claude will still follow OpenAgents patterns if you reference `.opencode/context/` files in your prompt

Install Claude CLI (if needed)

macOS:

brew install claude

npm:

npm install -g @anthropic-ai/claude-code

Verify:

claude --version

For Distribution (Auto-Convert)

One-Line Install (Recommended)

curl -fsSL https://raw.githubusercontent.com/darrenhinde/OpenAgents/main/integrations/claude-code/bootstrap-install.sh | bash

Prereqs: git, bash

Verify Claude Code:

claude --version

This downloads the Claude integration bundle and runs the plugin installer.

Step 1: Run the Converter

cd integrations/claude-code/converter
node src/convert-agents.js

This generates Claude-ready files in integrations/claude-code/generated/.

Step 2: Install for Personal Use

cd integrations/claude-code
./install.sh

This copies the plugin to ~/.claude/plugins/openagents-bridge/.

Step 3: Use with Claude Code

With plugin (recommended for distributed use):

claude --plugin-dir ~/.claude/plugins/openagents-bridge

Without plugin (manual mode):

# Set environment variable to load context files
export OPENAGENTS_CONTEXT_PATH=.opencode/context

# Run Claude with context loaded from your prompt
claude

💡 CLI Tips

- **Check loaded plugins**: `claude --print-plugins` - **Debug mode**: `claude --debug` (shows plugin loading) - **One-shot mode**: `claude "your request" --print-only` - **Session history**: Check `~/.claude/sessions/` for logs

How It Works

Context Discovery

1. Skill Triggers: The openagents-standards Skill automatically activates when you ask Claude to do anything.
2. Subagent Call: Claude calls context-scout to find relevant files in .opencode/context/.
3. Standards Loading: Claude reads the discovered files and applies OpenAgents standards.

Agent Conversion

The converter maps OpenAgents frontmatter to Claude format:

OpenAgents Field	Claude Field
id	name
description	description
tools / permissions	tools
model	model
mode: subagent	permissionMode: plan

Adding New Agents

For Local Use

Add to .opencode/agent/{category}/{agent}.md. The local adapter in .claude/ will pick it up on restart.

For Distribution

1. Add to .opencode/agent/{category}/{agent}.md
2. Run: cd integrations/claude-code/converter && node src/convert-agents.js
3. The converted agent appears in integrations/claude-code/generated/agents/

Files to Commit

• .claude/ - Local adapter (committed)
• integrations/claude-code/converter/src/convert-agents.js - Converter script (committed)
• integrations/claude-code/install.sh - Install script (committed)

Files to GitIgnore

• integrations/claude-code/generated/ - Generated files (ignored)
• integrations/claude-code/plugin/ - Build output (ignored)

Requirements

• Node.js 18+
• Claude Code v2.1.6+

CLI Reference

Command	Description
claude	Start interactive session
claude "request"	One-shot request
claude --plugin-dir ~/.claude/plugins/openagents-bridge	Load with plugin
claude --print-plugins	Show loaded plugins
claude --debug	Debug mode
claude --version	Show version