Claude Code Plugin

Use your Kybernesis agents directly in Claude Code with a simple one-click setup.

Table of Contents

• Overview
• Installation
• Configuration
• Using Agents
• Available Commands
• Syncing Agents
• Saving to Memory
• Troubleshooting

Overview

The Kybernesis Claude Code plugin lets you:

• Chat with your agents directly in Claude Code
• Access workspace memories through your agents
• Save information to your workspace via natural language
• Sync agents automatically when you create new ones

How It Works

You in Claude Code: "Talk to Samantha about our marketing strategy"
    ↓
Claude Code loads the kybernesis-agents skill
    ↓
Skill calls Kybernesis API with your message
    ↓
Samantha responds using her persona + your workspace memories
    ↓
Response appears in Claude Code

Installation

Step 1: Open Connect Modal

In the Kybernesis web app:

1. Navigate to Agents or Topology page
2. Click Connect to Claude Code button
3. A modal opens with setup instructions

Step 2: Install the Plugin

Copy and run this command in your terminal:

claude plugins add gh:KybernesisAI/kybernesis-claude-code-plugin

This installs the Kybernesis plugin from GitHub.

Step 3: Get Your API Key

In the same modal:

1. Click Generate API Key (or copy existing one)
2. The key looks like: kb_abc123def456...

Step 4: Set Environment Variable

Add to your shell profile (.bashrc, .zshrc, etc.):

export KYBERNESIS_API_KEY="kb_your_api_key_here"

Then reload your shell:

source ~/.zshrc  # or ~/.bashrc

Step 5: Sync Your Agents

Run the sync command to pull your agents:

npx kybernesis-plugin sync

You'll see output like:

✓ Found 3 agents
✓ Synced: Samantha (Marketing)
✓ Synced: Max (Engineering)
✓ Synced: Alex (HR)
Done! Your agents are ready to use.

Configuration

Environment Variable

The plugin requires KYBERNESIS_API_KEY to be set:

# Check if it's set
echo $KYBERNESIS_API_KEY

# Should output: kb_xxxxx...

Plugin Location

The plugin installs to:

~/.claude/plugins/kybernesis-claude-code-plugin/

Skill Files

Agent skills are stored in:

~/.claude/plugins/kybernesis-claude-code-plugin/skills/
└── kybernesis-agents/
    └── SKILL.md

Using Agents

Invoking the Skill

In Claude Code, use the kybernesis-agents skill:

You: Use the kybernesis-agents skill to list my agents

Or more naturally:

You: Talk to my Kybernesis agent Samantha

Listing Agents

Ask to see your available agents:

You: List my Kybernesis agents

Claude Code: Here are your agents:
┌─────────────┬────────────────────────────┬────────┐
│ Name        │ Description                │ Status │
├─────────────┼────────────────────────────┼────────┤
│ Samantha    │ Marketing Manager          │ active │
│ Max         │ Senior Engineer            │ active │
│ Alex        │ HR Director                │ active │
└─────────────┴────────────────────────────┴────────┘

Chatting with an Agent

Specify which agent to talk to:

You: Ask Samantha about our Q4 marketing campaign

Claude Code: [Calls Kybernesis API]

Samantha: Based on our marketing docs, the Q4 campaign focuses on...

Continuing Conversations

The plugin maintains conversation context:

You: Ask Samantha about the campaign budget

Samantha: Following up on our Q4 discussion, the budget is...
[Samantha remembers you were discussing Q4 campaign]

Available Commands

Through the Skill

CLI Commands

# Sync agents from Kybernesis
npx kybernesis-plugin sync

# Check plugin version
npx kybernesis-plugin --version

# Verify API key
npx kybernesis-plugin verify

Syncing Agents

When to Sync

Re-sync when you:

• Create a new agent in the web UI
• Delete an agent
• Want to refresh agent metadata

Running Sync

npx kybernesis-plugin sync

What Sync Does

1. Fetches your agent list from Kybernesis API
2. Updates the skill file with agent metadata
3. Caches agent details for faster access

Automatic Sync

The plugin periodically checks for updates when used. For manual control, run sync after making changes.

Saving to Memory

How It Works

When you ask an agent to save something, they use their archival_insert tool:

You: Ask Samantha to save our discussion about the product launch

Samantha: I've saved this to your workspace as "Product Launch
          Discussion" with tags: product, launch, planning.

Trigger Phrases

Tell your agent:

• "Save this to memory"
• "Add this to my workspace"
• "Remember this for later"
• "Store this information"

Requirements

The agent must have Write Memories permission enabled (configured in web UI).

Verification

Saved memories appear in:

• Your Kybernesis Topology view
• Retrieval search results
• Future agent conversations

Troubleshooting

"KYBERNESIS_API_KEY not set"

# Set the environment variable
export KYBERNESIS_API_KEY="kb_your_key_here"

# Add to shell profile for persistence
echo 'export KYBERNESIS_API_KEY="kb_your_key_here"' >> ~/.zshrc
source ~/.zshrc

"Agent not found"

1. Verify agent exists in web UI
2. Run npx kybernesis-plugin sync
3. Check agent name spelling (case-insensitive)

"Authentication failed"

1. Verify API key is correct
2. Check key hasn't been revoked in web UI
3. Generate a new key if needed

"No agents found"

1. Create agents in the Kybernesis web UI first
2. Run npx kybernesis-plugin sync
3. Verify API key has access to correct workspace

Plugin Not Loading

# Check plugin is installed
claude plugins list

# Reinstall if needed
claude plugins remove kybernesis
claude plugins add gh:KybernesisAI/kybernesis-claude-code-plugin

Slow Responses

• Agent may be retrieving many memories
• Try a simpler question first
• Check your network connection

Claude Code Not Recognizing Skill

1. Restart Claude Code
2. Verify plugin is in ~/.claude/plugins/
3. Check skill file exists in skills/kybernesis-agents/

Advanced Usage

Multiple Workspaces

If you have agents across multiple workspaces:

• Each API key is scoped to specific workspaces
• Generate separate keys for different workspace access
• Agents only see memories from their connected workspaces

Custom Integrations

For programmatic access, use the REST API directly:

# List agents
curl -s "https://api.kybernesis.ai/v1/agents" \
  -H "Authorization: Bearer $KYBERNESIS_API_KEY"

# Chat with agent
curl -s -X POST "https://api.kybernesis.ai/v1/agents/{AGENT_ID}/chat" \
  -H "Authorization: Bearer $KYBERNESIS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"message": "Hello!"}'

See API Reference for full documentation.

What's Next?

• AI Agents - Create and configure agents
• Agent Chat - Advanced chat features
• MCP Setup - Alternative integration method

Need help? Check the API Reference or join our Discord community.