Migrating to Symbiotic Code

Move from any coding agent to Symbiotic Code

Already using Claude Code, Codex, Cursor, GitHub Copilot, or OpenCode? You can get started with Symbiotic Code in a few minutes. Your existing instructions, skills, commands, agents, and MCP servers can come with you.

	Automatic migration	Manual migration
Instructions	AGENTS.md, CLAUDE.md, ~/.claude/CLAUDE.md	.cursorrules, .cursor/rules/, .github/copilot-instructions.md, GEMINI.md, ~/.codex/AGENTS.md
Skills	.claude/skills/, .agents/skills/ (project and global)	Any other location
MCP servers	—	All sources
Commands	—	All sources (mostly a copy)
Agents	—	All sources (frontmatter must be converted)

---

1. Install Symbiotic Code

You can install Symbiotic Code in 2 ways: VS Code extension or CLI. You can use both at the same time.

VS Code extension

Download the .vsix extension and install it in VS Code or another VS Code-based IDE.

CLI

Install the CLI globally with npm:

npm i -g @symbioticsec/code

Then launch Symbiotic Code with:

symbiotic

---

2. Create your account

You need a Symbiotic Security account to use Symbiotic Code. Create an account or log in through the Symbiotic Portal.

	Free plan	Paid plans
Members	Up to 8	No limit
Included models	One limited free model	Optimized frontier models
Bring your own key	Use additional models from other providers with API keys	Use local models or specific models not offered with your plan with API keys

3. Connect to a model

Use the built-in models

Depending on your plan, Symbiotic Code comes with optimized support for the most popular frontier models. The Auto model uses smart routing to select the right model for each request while helping manage costs. Use /models to switch models.

Use your own provider

To use an existing Claude, OpenAI, or Gemini subscription, or a local or custom model:

1. Run /connect and select your provider.
2. Enter your provider API key.
3. Use /models to list and switch between available models.

See Models and providers for supported providers and custom configuration.

---

4. Project memory / instructions

Loaded automatically

Symbiotic Code loads these instruction files without any configuration:

Scope	File	Tool it came from
Project	AGENTS.md	Codex, OpenCode, and most other agents
Project	CLAUDE.md	Claude Code
Global	~/.config/symbiotic/AGENTS.md	Symbiotic Code
Global	~/.claude/CLAUDE.md	Claude Code

Project files are searched from your working directory up to the repository root.

Only one project file name is used. If a repo contains both AGENTS.md and CLAUDE.md, only AGENTS.md is loaded and CLAUDE.md is ignored. The same applies globally: if ~/.config/symbiotic/AGENTS.md exists, ~/.claude/CLAUDE.md is not loaded. Merge the files, or add the second one to instructions (see below).

Add instructions from other tools

Rule files from Cursor, GitHub Copilot, Gemini, Windsurf, and Codex’s global AGENTS.md are not loaded automatically. Reference them with the instructions key in symbiotic.json. It accepts paths and glob patterns:

symbiotic.json

{
  "$schema": "https://config.symbioticsec.ai/config.json",
  "instructions": [
    ".cursorrules",
    ".cursor/rules/*.mdc",
    ".github/copilot-instructions.md",
    ".github/instructions/*.md",
    ".windsurfrules",
    "GEMINI.md"
  ]
}

For global rules, add them to ~/.config/symbiotic/symbiotic.json instead, for example "instructions": ["~/.codex/AGENTS.md"].

Paths that don’t exist are skipped, so a single shared list works across repos that use different tools.

---

5. Skills

Skills in these locations are picked up automatically, so no action is needed:

• .claude/skills/<name>/SKILL.md and ~/.claude/skills/<name>/SKILL.md
• .agents/skills/<name>/SKILL.md and ~/.agents/skills/<name>/SKILL.md

For skills stored anywhere else, move them to .symbiotic/skills/<name>/SKILL.md (project) or ~/.config/symbiotic/skills/<name>/SKILL.md (global), or point to their folder with skills.paths:

symbiotic.json

{
  "skills": {
    "paths": ["~/my-skills"]
  }
}

A SKILL.md with missing name or description frontmatter is skipped. Check the naming rules if a skill does not show up.

To stop loading files from other tools:

Variable	Disables
SYMBIOTIC_DISABLE_CLAUDE_CODE_PROMPT=1	~/.claude/CLAUDE.md
SYMBIOTIC_DISABLE_EXTERNAL_SKILLS=1	Skills in .claude/skills/ and .agents/skills/
SYMBIOTIC_DISABLE_CLAUDE_CODE=1	Both of the above

---

6. MCP servers

MCP servers are configured under the mcp key of symbiotic.json:

• Global servers (available in every project): ~/.config/symbiotic/symbiotic.json
• Project servers (shared with your team): symbiotic.json at the repo root

symbiotic.json

{
  "$schema": "https://config.symbioticsec.ai/config.json",
  "mcp": {
    "my-local-server": {
      "type": "local",
      "command": ["npx", "-y", "my-mcp-server"],
      "environment": {
        "API_KEY": "{env:MY_API_KEY}"
      }
    },
    "my-remote-server": {
      "type": "remote",
      "url": "https://mcp.example.com/mcp",
      "headers": {
        "Authorization": "Bearer {env:MY_TOKEN}"
      }
    }
  }
}

You can also add servers interactively with symbiotic mcp add. See MCP servers for all options.

Where your current config lives

Tool	Location	Key
Claude Code	~/.claude.json (user scope, and per project under projects.<path>.mcpServers), .mcp.json (project)	mcpServers
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json (macOS), %APPDATA%\Claude\claude_desktop_config.json (Windows)	mcpServers
Codex	~/.codex/config.toml, .codex/config.toml (project)	[mcp_servers.<name>] tables (TOML)
Cursor	~/.cursor/mcp.json, .cursor/mcp.json	mcpServers
VS Code / GitHub Copilot	.vscode/mcp.json, or mcp.json in your VS Code user profile	servers
Windsurf	~/.codeium/windsurf/mcp_config.json	mcpServers
OpenCode	opencode.json, ~/.config/opencode/opencode.json	mcp (same format, copy as-is)

Field mapping

Other tools	Symbiotic Code
command + args	"type": "local", "command": [command, ...args]
env	environment
url, or type set to http, sse, or streamable-http	"type": "remote", url
headers / Codex http_headers	headers
Codex bearer_token_env_var = "X"	"headers": { "Authorization": "Bearer {env:X}" }
${VAR} / $VAR in values	{env:VAR}
disabled: true / Codex enabled = false	"enabled": false
Timeouts in seconds (Codex startup_timeout_sec, tool_timeout_sec)	timeout, in milliseconds (default 30000)
cwd, alwaysAllow, autoApprove, tool allow/deny lists, VS Code ${input:...}	Not supported. Remove the field and set secrets through {env:VAR}

MCP entries are validated strictly. A single unsupported field such as args, env, or cwd in any entry prevents the whole config file from loading. Copying a mcpServers block as-is will not work.

Local servers inherit your shell environment, so variables already exported in your shell don’t need to be listed in environment.

OAuth tokens are not transferred between tools. After migrating a remote server that uses OAuth, run:

symbiotic mcp auth <server-name>

Migrate your existing MCP config automatically

Paste this prompt into Symbiotic Code (or your current coding agent) to find and convert your existing MCP servers:

Migrate MCP server configs from other tools to Symbiotic Code

CopiedCopy prompt

---

7. Custom commands

Symbiotic Code commands are Markdown files with optional YAML frontmatter, very close to Claude Code and Cursor commands:

Scope	Location
Project	.symbiotic/commands/
Global	~/.config/symbiotic/commands/

Tool	Where your commands live	Notes
Claude Code	.claude/commands/, ~/.claude/commands/	Copy as-is, then check the frontmatter below
Cursor	.cursor/commands/	Plain Markdown, copy as-is
Codex	~/.codex/prompts/	Copy as-is. Named placeholders like $FILE are not supported; use $1, $2, or $ARGUMENTS
GitHub Copilot	.github/prompts/*.prompt.md	Rename to <name>.md and remove the mode and tools fields
OpenCode	.opencode/command/, ~/.config/opencode/command/	Copy as-is

These placeholders work the same way as in Claude Code: $ARGUMENTS, $1, $2, …, !`shell command` and @path/to/file.

Frontmatter differences:

Field	Behavior in Symbiotic Code
description, agent, subtask	Supported
model	Must include the provider, for example anthropic/claude-sonnet-4-5. A bare model name like claude-3-5-haiku-20241022 fails when the command runs. Remove the field to use the current model.
allowed-tools, argument-hint	Ignored. Use tool permissions instead of allowed-tools.

Subfolders become part of the command name: .symbiotic/commands/frontend/component.md is invoked as /frontend/component.

See Custom commands for details.

---

8. Custom agents

Agents are also Markdown files with YAML frontmatter, but the frontmatter is not compatible with Claude Code and must be converted.

Scope	Location
Project	.symbiotic/agents/
Global	~/.config/symbiotic/agents/

Tool	Where your agents live
Claude Code	.claude/agents/, ~/.claude/agents/
GitHub Copilot	.github/agents/*.agent.md, or .github/chatmodes/*.chatmode.md (legacy)
OpenCode	.opencode/agent/, ~/.config/opencode/agent/ (copy as-is)

Copying a Claude Code agent file without converting it prevents Symbiotic Code from loading its configuration: tools: Read, Grep and color: blue are rejected.

Frontmatter mapping:

Claude Code	Symbiotic Code
name	Remove it. The agent name is the file name.
description	description (unchanged)
tools: Read, Grep, Glob (comma-separated list)	permission map, see the example below
model: inherit	Remove the field
model: sonnet / opus / haiku	A full provider/model id, for example anthropic/claude-sonnet-4-5
color: blue	A hex color ("#3B82F6") or a theme color: primary, secondary, accent, success, warning, error, info
—	mode: subagent to keep the Claude Code behavior (invoked by other agents or with @name). Without it, the agent is also available as a primary agent.

Example: this Claude Code agent

.claude/agents/code-reviewer.md

---
name: code-reviewer
description: Reviews code for quality and security issues
tools: Read, Grep, Glob
model: sonnet
color: blue
---
You are a senior code reviewer...

becomes:

.symbiotic/agents/code-reviewer.md

---
description: Reviews code for quality and security issues
mode: subagent
model: anthropic/claude-sonnet-4-5
color: "#3B82F6"
permission:
  edit: deny
  bash: deny
  webfetch: deny
---
You are a senior code reviewer...

Tools that aren’t listed are allowed or ask for confirmation according to your tool permissions, so deny explicitly the ones the agent should not use. Claude Code tools map to these permission keys: Read → read, Edit/Write/MultiEdit → edit, Bash → bash, Grep → grep, Glob → glob, LS → list, WebFetch → webfetch, WebSearch → websearch, Task → task, TodoWrite → todowrite.

See Custom agents for all options.

Migrate your existing commands and agents automatically

Migrate custom commands and agents from other tools to Symbiotic Code

CopiedCopy prompt

---

9. Coming from OpenCode

Symbiotic Code uses the same configuration format as OpenCode, but it does not read OpenCode’s files. To migrate:

1. Rename opencode.json / opencode.jsonc to symbiotic.json / symbiotic.jsonc, and ~/.config/opencode/ to ~/.config/symbiotic/.
2. Rename .opencode/ to .symbiotic/.
3. Replace the $schema value with https://config.symbioticsec.ai/config.json.
4. Move skills from .opencode/skills/ to .symbiotic/skills/.

---

10. What is not migrated

• Claude Code hooks: use plugins instead.
• Permission rules in Claude Code settings.json (for example Bash(git diff:*)): rewrite them as tool permissions, for example "bash": { "git diff *": "allow" }.
• OAuth tokens and API keys: reconnect with /connect for providers and symbiotic mcp auth <name> for MCP servers.
• Session history.

---

11. Security modes

Symbiotic Code adds a security mode that Claude Code and OpenCode don’t have. Toggle it with Ctrl+S while running, or set a default per-agent in config:

{
  "agent": {
    "build": {
      "security_mode": "balanced"
    }
  }
}

Options: permissive (fastest, fewest confirmations), balanced (default), strict (most confirmations).

See Security Modes for details.