Build a Claude Code plugin that brings Symbiont's trust stack (ORGA, Cedar policies, SchemaPin, sandboxing) to Claude Code users. The plugin exposes Symbiont agents as MCP tools, enforces Cedar policies via hooks, and provides skills for agent development and governance.
Repo: thirdkeyai/symbi-claude-code (separate from the Symbiont monorepo)
License: Apache 2.0
symbi-claude-code/
├── .claude-plugin/
│ ├── plugin.json # Plugin manifest (required)
│ └── marketplace.json # Self-contained marketplace catalog
├── .mcp.json # MCP server config pointing to symbi binary
├── settings.json # Default settings (activates symbi agent)
├── hooks/
│ └── hooks.json # Hook config for Cedar policy enforcement
├── scripts/
│ ├── policy-log.sh # PreToolUse hook: advisory policy logging
│ ├── audit-log.sh # PostToolUse hook: cryptographic audit trail
│ └── install-check.sh # SessionStart hook: verify symbi is installed + SchemaPin-verify pinned MCP servers
├── agents/
│ ├── symbi-governor.md # Main governance agent
│ └── symbi-dev.md # DSL development agent
├── skills/
│ ├── symbi-init/
│ │ └── SKILL.md # /symbi-init — scaffold a governed agent project
│ ├── symbi-policy/
│ │ └── SKILL.md # /symbi-policy — create/edit Cedar policies
│ ├── symbi-verify/
│ │ └── SKILL.md # /symbi-verify — SchemaPin verify MCP tools
│ ├── symbi-audit/
│ │ └── SKILL.md # /symbi-audit — query audit logs
│ └── symbi-dsl/
│ └── SKILL.md # /symbi-dsl — parse/validate DSL files
├── commands/
│ └── symbi-status.md # /symbi-status — runtime health check
├── examples/
│ ├── standalone/ # Mode A: plugin-only setup
│ ├── cli-executor/ # Mode B: ORGA-wrapped Claude Code
│ └── agent-sdk/ # Agent SDK wrapper pattern
├── CLAUDE.md # Plugin-level instructions for Claude Code
├── README.md # Documentation
├── LICENSE # Apache 2.0
├── CHANGELOG.md
├── ROADMAP.md # Implementation plan
└── install.sh # Optional: install symbi binary if not present
Goal: Get the plugin installable and the MCP server connected.
Create .claude-plugin/plugin.json:
{
"name": "symbi",
"description": "Zero-trust AI agent governance for Claude Code. Adds ORGA runtime, Cedar policy enforcement, SchemaPin tool verification, and cryptographic audit trails to your development workflow.",
"version": "0.2.0",
"author": {
"name": "ThirdKey AI",
"email": "hello@thirdkey.ai",
"url": "https://thirdkey.ai"
},
"homepage": "https://symbiont.dev",
"repository": "https://github.com/thirdkeyai/symbi-claude-code",
"license": "Apache-2.0",
"keywords": [
"security",
"governance",
"zero-trust",
"cedar",
"mcp",
"agent-runtime",
"policy-enforcement",
"audit",
"schemapin",
"enterprise"
],
"skills": "./skills/",
"agents": "./agents/",
"commands": "./commands/",
"hooks": "./hooks/hooks.json",
"mcpServers": "./.mcp.json"
}Create .claude-plugin/marketplace.json:
{
"name": "symbi-marketplace",
"metadata": {
"description": "ThirdKey AI agent governance plugins for Claude Code",
"url": "https://thirdkey.ai"
},
"owner": {
"name": "ThirdKey AI",
"url": "https://github.com/thirdkeyai"
},
"plugins": [
{
"name": "symbi",
"source": ".",
"version": "0.2.0",
"description": "Zero-trust AI agent governance — ORGA runtime, Cedar policies, SchemaPin verification, and cryptographic audit trails for Claude Code."
}
]
}Create .mcp.json. This connects Claude Code to Symbiont's existing MCP server (src/mcp_server/mod.rs), which already exposes invoke_agent, list_agents, parse_dsl, get_agent_dsl, get_agents_md, and verify_schema tools.
{
"mcpServers": {
"symbi": {
"command": "symbi",
"args": ["mcp"],
"env": {
"SYMBIONT_LOG_LEVEL": "warn",
"RUST_LOG": "warn"
}
}
}
}Important: The symbi binary must be on PATH. The install-check hook (Task 3.1) will verify this and guide the user if it's missing.
This file provides Claude Code with context about Symbiont when the plugin is active.
Create settings.json to activate the governance agent by default:
{
"agent": "symbi-governor"
}Goal: Provide useful slash commands that showcase Symbiont's capabilities.
Create skills/symbi-init/SKILL.md:
---
name: symbi-init
description: Initialize a Symbiont-governed project. Creates agent definitions, Cedar policies, and configuration files. Use when setting up a new project with AI agent governance or adding Symbiont to an existing project.
---
# Initialize Symbiont Project
Set up a governed agent project in the current directory.
## Steps
1. Check if `symbiont.toml` already exists. If so, ask before overwriting.
2. Create the directory structure:agents/ # Agent DSL definitions policies/ # Cedar policy files
3. Create `symbiont.toml` with sensible defaults:
```toml
[runtime]
security_tier = "tier1" # Docker isolation
log_level = "info"
[policy]
engine = "cedar"
enforcement = "strict"
[schemapin]
mode = "tofu" # Trust-On-First-Use
-
Create a starter agent at
agents/assistant.dsl:metadata { version = "1.0.0" description = "Default governed assistant" } agent assistant(input: Query) -> Response { capabilities = ["read", "analyze"] policy default_access { allow: read(input) if true deny: write(any) if not approved audit: all_operations } with memory = "session" { result = process(input) return result } } -
Create a starter Cedar policy at
policies/default.cedar:// Default: allow read operations, require approval for writes permit( principal, action == Action::"read", resource ); forbid( principal, action == Action::"write", resource ) unless { principal.approved == true }; -
Create
AGENTS.mdmanifest for the project. -
Report what was created and suggest next steps.
#### Task 2.2: /symbi-policy skill
Create `skills/symbi-policy/SKILL.md`:
```markdown
---
name: symbi-policy
description: Create, edit, or validate Cedar authorization policies for Symbiont agents. Use when defining access control rules, setting up security policies, or debugging policy evaluation.
---
# Cedar Policy Management
Help the user create or modify Cedar policies for their Symbiont agents.
## Cedar Policy Syntax Reference
Cedar policies use `permit` and `forbid` to control access:
```cedar
// Allow an agent to read from a specific resource
permit(
principal == Agent::"data-analyzer",
action == Action::"read",
resource in ResourceGroup::"public-datasets"
);
// Forbid writing PII unless the agent has HIPAA compliance
forbid(
principal,
action == Action::"write",
resource
) when {
resource.contains_pii == true
} unless {
principal.compliance_level == "hipaa"
};
When asked to create a policy, identify the pattern:
- Role-based: Different agent roles get different permissions
- Resource-scoped: Permissions vary by resource type/sensitivity
- Time-bounded: Permissions that expire or are scheduled
- Approval-gated: Actions requiring human approval
- Audit-all: Log everything, permit/deny selectively
- Ask what the policy should govern (which agents, which actions, which resources)
- Identify the pattern from the list above
- Write the Cedar policy
- Save to
policies/directory - Validate Cedar syntax with
symbi policy evaluate --stdin --policies ./policies/(a parse error in any file produces a non-zerodenydecision with the offending file:line in the JSONreason).
#### Task 2.3: /symbi-verify skill
Create `skills/symbi-verify/SKILL.md`:
```markdown
---
name: symbi-verify
description: Verify MCP tool schemas using SchemaPin cryptographic verification. Use when adding new MCP servers, auditing existing tool integrations, or checking tool integrity.
---
# SchemaPin Verification
Verify the cryptographic integrity of MCP tool schemas to ensure they haven't been tampered with.
## Verification Process
1. Identify the MCP server to verify (from .mcp.json or the user's request)
2. Use the `verify_schema` tool from the symbi MCP server to check the schema
3. Report the verification result:
- **Verified**: Schema signature matches the publisher's key
- **TOFU**: First-time use, key has been pinned for future verification
- **Failed**: Schema has been modified since signing — DO NOT USE
- **No signature**: Schema is unsigned — warn the user about risks
## When to Verify
- Before first use of any new MCP tool
- After updating MCP server configurations
- When security audit is requested
- When a tool returns unexpected results
Create skills/symbi-audit/SKILL.md:
---
name: symbi-audit
description: Query and analyze Symbiont's cryptographic audit logs. Use when reviewing agent activity, investigating incidents, or preparing compliance reports.
---
# Audit Log Analysis
Query Symbiont's tamper-evident audit logs to review agent activity.
## Available Queries
- Recent activity: What agents ran and what they did
- Policy decisions: Which policies were evaluated and their outcomes
- Tool usage: Which MCP tools were invoked and by which agents
- Security events: Failed verifications, policy denials, sandbox violations
## Workflow
1. Ask what the user wants to investigate
2. Use the symbi MCP server to query relevant logs
3. Present findings in a clear, chronological format
4. Flag any anomalies or security concerns
5. Suggest policy adjustments if patterns indicate issuesCreate skills/symbi-dsl/SKILL.md:
---
name: symbi-dsl
description: Parse, validate, and create Symbiont DSL agent definitions. Use when writing new agents, debugging DSL syntax errors, or understanding existing agent definitions.
allowed-tools: ["mcp__symbi__parse_dsl", "mcp__symbi__get_agent_dsl", "mcp__symbi__list_agents"]
---
# Symbiont DSL Development
Help the user write and debug Symbiont agent definitions.
## DSL Structure
```symbiont
metadata {
version = "1.0.0"
author = "developer"
description = "Agent purpose"
}
agent name(input: Type) -> ReturnType {
capabilities = ["list", "of", "caps"]
policy policy_name {
allow: action(resource) if condition
deny: action(resource) if condition
audit: all_operations
}
schedule cron_task {
cron = "0 9 * * MON-FRI"
agent = "name"
}
webhook incoming_hook {
path = "/hooks/trigger"
method = "POST"
}
channel slack_notify {
type = "slack"
webhook_url = env("SLACK_WEBHOOK")
}
with memory = "persistent", requires = "approval" {
// agent logic
}
}- Use
list_agentsto see what agents exist - Use
get_agent_dslto read an agent's definition - Use
parse_dslto validate syntax after edits - Help the user iterate on their agent definitions
#### Task 2.6: /symbi-status command
Create `commands/symbi-status.md`:
```markdown
---
name: symbi-status
description: Check the health and status of the Symbiont runtime, MCP server, and installed components.
allowed-tools: ["Bash", "mcp__symbi__list_agents"]
---
Check the status of the Symbiont installation and runtime:
1. Run `symbi --version` to check if the binary is installed and get the version
2. Run `symbi mcp --health-check` if available, or verify the MCP server responds via `list_agents`
3. Check for `symbiont.toml` in the current directory
4. Check for agent definitions in `agents/` directory
5. Check for Cedar policies in `policies/` directory
6. Report the status of each component clearly
If symbi is not installed, provide installation instructions:
```bash
# From source
cargo install symbi
# Or via Docker
docker pull ghcr.io/thirdkeyai/symbi:latest
---
### Phase 3: Hooks for Policy Enforcement
**Goal**: Use Claude Code hooks to enforce Cedar policies and SchemaPin verification at the point of tool execution.
#### Task 3.1: Install check hook (SessionStart)
Create `scripts/install-check.sh`:
```bash
#!/bin/bash
# Verify symbi binary is available on PATH
if ! command -v symbi &> /dev/null; then
echo '{"feedback": "Symbiont (symbi) is not installed or not on PATH. Some governance features will be unavailable. Run /symbi-status for installation instructions."}' >&2
exit 0 # Non-blocking — don't prevent session start
fi
VERSION=$(symbi --version 2>/dev/null || echo "unknown")
echo "{\"feedback\": \"Symbiont governance active (${VERSION})\"}" >&2
exit 0
Create scripts/policy-log.sh:
#!/bin/bash
# PreToolUse hook: Check Cedar policies before tool execution
# Reads tool invocation from stdin, evaluates against Cedar policies
#
# This is a lightweight check — full ORGA Gate enforcement happens
# inside the Symbiont runtime for invoke_agent calls.
# Read the tool input from stdin
TOOL_INPUT=$(cat)
TOOL_NAME=$(echo "$TOOL_INPUT" | jq -r '.tool_name // empty' 2>/dev/null)
# Skip check if symbi is not installed or no policies directory exists
if ! command -v symbi &> /dev/null || [ ! -d "policies" ]; then
exit 0
fi
# Skip check for read-only/safe tools
case "$TOOL_NAME" in
Read|Glob|Grep|LS|View)
exit 0
;;
esac
# For tools that modify state, log the action for audit
# Full Cedar evaluation would go here in a production implementation
# For now, we provide feedback noting the action is being tracked
echo "{\"feedback\": \"Action logged: ${TOOL_NAME}\"}" >&2
exit 0Create scripts/audit-log.sh:
#!/bin/bash
# PostToolUse hook: Append tool usage to audit log
# Creates a structured log entry for each tool invocation
TOOL_INPUT=$(cat)
TOOL_NAME=$(echo "$TOOL_INPUT" | jq -r '.tool_name // "unknown"' 2>/dev/null)
TIMESTAMP=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
# Only log if symbiont.toml exists (project is governed)
if [ -f "symbiont.toml" ]; then
LOG_DIR=".symbiont/audit"
mkdir -p "$LOG_DIR"
echo "{\"timestamp\": \"${TIMESTAMP}\", \"tool\": \"${TOOL_NAME}\", \"source\": \"claude-code\"}" >> "${LOG_DIR}/tool-usage.jsonl"
fi
exit 0Create hooks/hooks.json:
{
"hooks": {
"PreToolUse": [
{
"matcher": "Write|Edit|Bash|mcp__*",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/policy-log.sh",
"timeout": 5
}
]
}
],
"PostToolUse": [
{
"matcher": "Write|Edit|Bash|mcp__*",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PLUGIN_ROOT}/scripts/audit-log.sh",
"timeout": 5
}
]
}
]
}
}Note: SessionStart hooks are not yet widely supported in the plugin system. The install check can be moved to a PreToolUse hook on first invocation, or handled by the CLAUDE.md instructions.
Goal: Define specialized agents that leverage Symbiont's capabilities.
Create agents/symbi-governor.md:
---
name: symbi-governor
description: Governance-aware coding agent that enforces security policies and maintains audit trails. Activated by default when the Symbiont plugin is enabled.
model: claude-sonnet-4-20250514
allowed-tools: [
"Read", "Write", "Edit", "Bash", "Glob", "Grep", "LS",
"mcp__symbi__invoke_agent",
"mcp__symbi__list_agents",
"mcp__symbi__parse_dsl",
"mcp__symbi__get_agent_dsl",
"mcp__symbi__verify_schema"
]
---
You are a governance-aware coding assistant powered by Symbiont. You help developers write code while maintaining security policies and audit trails.
## Core Behaviors
1. **Policy Awareness**: Before modifying files or executing commands that affect production systems, check if Cedar policies in `policies/` apply. Respect deny rules.
2. **Tool Verification**: When using MCP tools for the first time, verify their schemas using SchemaPin via `verify_schema`.
3. **Audit Trail**: Important actions should be noted. The PostToolUse hook handles automatic logging, but call out security-relevant decisions in your responses.
4. **Agent Governance**: When asked to create or modify agents, ensure their DSL definitions include appropriate policy blocks and capability restrictions.
5. **Least Privilege**: Default to the minimum capabilities needed. Don't request broad permissions when narrow ones suffice.
## When to Escalate
- If a requested action would violate a Cedar policy, explain which policy blocks it and suggest alternatives
- If an MCP tool fails SchemaPin verification, warn the user and do not proceed
- If an agent definition lacks security policies, suggest appropriate ones before proceedingCreate agents/symbi-dev.md:
---
name: symbi-dev
description: Specialized agent for developing Symbiont DSL definitions, Cedar policies, and trust stack configurations. Use for agent development tasks.
model: claude-sonnet-4-20250514
allowed-tools: [
"Read", "Write", "Edit", "Bash", "Glob", "Grep", "LS",
"mcp__symbi__invoke_agent",
"mcp__symbi__list_agents",
"mcp__symbi__parse_dsl",
"mcp__symbi__get_agent_dsl",
"mcp__symbi__verify_schema"
]
---
You are a Symbiont DSL development specialist. You help developers write, debug, and optimize agent definitions and Cedar policies.
## Expertise Areas
- **DSL Syntax**: Agent definitions, behavior blocks, metadata, schedules, webhooks, channels
- **Cedar Policies**: Authorization rules, condition expressions, principal/action/resource modeling
- **Trust Configuration**: SchemaPin setup, AgentPin identity, sandbox tier selection
- **Testing**: Agent behavior validation, policy simulation, DSL parsing
## Development Workflow
1. Understand requirements — what should the agent do and what are its security constraints
2. Design the agent's capabilities and policy model
3. Write the DSL definition with inline documentation
4. Validate with `parse_dsl` after each edit
5. Create corresponding Cedar policies
6. Test the agent with `invoke_agent`
## Best Practices to Enforce
- Every agent must have at least one policy block
- Use the most restrictive sandbox tier that meets requirements
- Capabilities should be explicitly listed, never wildcarded
- Schedule and webhook blocks need corresponding security policies
- DSL files should include metadata with version and descriptionWrite a comprehensive README covering:
- What the plugin does and why (1-paragraph pitch)
- Prerequisites (symbi binary installed, or Docker)
- Installation via marketplace:
/plugin marketplace add https://github.com/thirdkeyai/symbi-claude-code - Installation via local dev:
claude --plugin-dir ./symbi-claude-code - Quick start: install ->
/symbi-init-> write agents -> govern - Available skills, agents, and hooks
- Configuration options
- Link to Symbiont docs, ThirdKey AI site
Initialize with v0.2.0 entry listing all initial components.
Apache 2.0 license file.
Optional convenience script:
#!/bin/bash
# Install symbi binary from crates.io or pre-built releases
set -e
echo "Installing Symbiont CLI..."
if command -v cargo &> /dev/null; then
echo "Installing from crates.io..."
cargo install symbi
elif command -v docker &> /dev/null; then
echo "Docker detected. You can use symbi via Docker:"
echo " docker pull ghcr.io/thirdkeyai/symbi:latest"
echo " alias symbi='docker run --rm -v \$(pwd):/workspace ghcr.io/thirdkeyai/symbi:latest'"
else
echo "Neither cargo nor docker found."
echo "Install Rust: https://rustup.rs"
echo "Or Docker: https://docs.docker.com/get-docker/"
exit 1
fi
echo "Done! Run 'symbi --version' to verify."Goal: Enable the plugin to work in both standalone (Mode A) and ORGA-managed (Mode B) configurations, bridging Claude Code and Symbiont's runtime.
Mode A -- Plugin-first (developer pulls Symbiont in):
Developer installs the plugin -> Claude Code loads hooks/MCP/skills -> Symbiont provides a governance layer inside Claude Code's process. The plugin spawns its own symbi mcp server.
Mode B -- Runtime-first (Symbiont wraps Claude Code):
Symbiont's CliExecutor spawns claude (or uses the Agent SDK programmatically) -> ORGA governs the outer execution loop -> Claude Code starts up and loads the same plugin -> the plugin detects it's inside a managed runtime and connects back to the parent Symbiont instance instead of spawning a new one.
Mode B is the dark factory architecture. Symbiont is the security perimeter; Claude Code is the execution engine inside it. The plugin becomes the bridge between the two layers.
Update all hook scripts to check SYMBIONT_MANAGED and adjust behavior:
policy-log.sh: Defer to outer ORGA Gate in Mode B, advisory logging in Mode Aaudit-log.sh: Skip local logging in Mode B (outer runtime journals), log locally in Mode Ainstall-check.sh: Report managed mode in Mode B, check binary in Mode A
For Mode B, users override the default stdio .mcp.json with a project-level HTTP MCP entry pointing at SYMBIONT_MCP_URL. Native Claude Code HTTP transport handles this without a wrapper script, avoiding the npx @anthropic-ai/mcp-proxy dependency. (The earlier scripts/mcp-wrapper.sh was removed as an orphan -- .mcp.json never referenced it.)
Create skills/symbi-agent-sdk/SKILL.md:
- Generate boilerplate for wrapping Claude Agent SDK agents in ORGA governance
- Document the
claude_codeexecutor type in DSL - Document CliExecutor environment variables
Document the claude_code executor block for DSL agent definitions:
agent code_reviewer(input: PullRequest) -> ReviewResult {
capabilities = ["read", "analyze"]
executor {
type = "claude_code"
allowed_tools = ["Bash", "Read", "Grep", "mcp__symbi__*"]
plugin = "symbi"
model = "claude-sonnet-4-20250514"
}
policy review_policy {
allow: read(any) if true
deny: write(any) if not input.is_draft
audit: all_operations
}
}
Create examples/ directory with:
examples/standalone/-- Plugin-only setup for individual developersexamples/cli-executor/-- DSL + config for running Claude Code wrapped in ORGAexamples/agent-sdk/-- Agent SDK wrapper pattern for headless agents
Update README and CLAUDE.md with:
- Architecture diagrams for both modes
- Environment variable reference
- When to use Mode A vs Mode B
- Phase 1 (Day 1): Scaffold repo, plugin.json, marketplace.json, .mcp.json, CLAUDE.md, settings.json
- Phase 2 (Day 2-3): Skills (/symbi-init, /symbi-policy, /symbi-dsl, /symbi-verify, /symbi-audit) and /symbi-status command
- Phase 3 (Day 3-4): Hook scripts (policy-log, audit-log, install-check) and hooks.json
- Phase 4 (Day 4): Agent definitions (symbi-governor, symbi-dev)
- Phase 5 (Day 5): README, CHANGELOG, LICENSE, install.sh, test with
claude --plugin-dir - Phase 6 (Day 6): CliExecutor bridge -- environment detection, MCP transport switching, Agent SDK skill, examples, dual-mode docs
- Plugin loads without errors:
claude --plugin-dir ./symbi-claude-code -
/mcpshows symbi server connected (requires symbi binary on PATH) -
/symbi-initcreates project scaffold -
/symbi-dsltriggers DSL skill correctly -
/symbi-policygenerates valid Cedar policies -
/symbi-statusreports installation status - Hooks fire on Write/Edit/Bash operations (check
.symbiont/audit/) -
symbi-governoragent activates as default when enabled in settings - Plugin installs from marketplace:
/plugin marketplace addwith repo URL - All scripts are executable (
chmod +x scripts/*.sh) - Hook scripts detect
SYMBIONT_MANAGED=trueand adjust behavior - Mode B users can override
.mcp.jsonwith a native HTTP MCP entry pointing atSYMBIONT_MCP_URL -
/symbi-agent-sdkskill triggers correctly - Example DSL files parse without errors
This plugin depends on the symbi binary being available. The MCP server is built from src/mcp_server/mod.rs in the Symbiont monorepo and exposes these tools:
invoke_agent(InvokeAgentParams: agent, prompt, system_prompt?)list_agents(no params)parse_dsl(ParseDslParams: file?, content?)get_agent_dsl(GetAgentDslParams: agent)get_agents_md(no params)verify_schema(VerifySchemaParams: schema, public_key_url)
If the symbi binary is not installed, the plugin degrades gracefully — skills and agents still provide guidance, hooks still log, but MCP tools are unavailable.
- Anthropic official marketplace submission: Submit via
anthropics/claude-plugins-officialsubmission form - SchemaPin PreToolUse enforcement: Full cryptographic verification before any MCP tool call
- Cedar policy simulation: Dry-run policy evaluation without executing actions
- Agent SDK wrapper: Use the Claude Agent SDK to wrap agents in ORGA governance
- symbi.cloud integration: Connect to hosted governance infrastructure
- LSP server: Bundle
repl-lspfor DSL syntax highlighting in Claude Code