Adding a New Symbiont to Myco's SymbiontInstaller

Prerequisites

• Understand the new agent's hook format and config file locations
• Know the agent's config directory name (e.g., .claude/, .cursor/, .gemini/)
• Determined whether the agent reads AGENTS.md natively or needs a thin instruction stub

Integration Classes

Not all agents can be wired via the same procedure. Before starting, identify which class applies:

Class	Description	Example agents
Class 1 — Config-File	Agent is configured via JSON or TOML files in a project directory. Hooks, MCP entries, and instructions are written by SymbiontInstaller as file I/O.	Claude Code, Cursor, Windsurf, Codex, Gemini CLI, VS Code Copilot
Class 2 — Plugin-API	Agent exposes a plugin registration API; it cannot be configured by writing files into a config directory. Requires a dedicated, agent-specific installation path in SymbiontInstaller — the standard Steps 1–8 below do NOT apply.	opencode (v0.15.0+, 7th symbiont, implemented)

If you are adding a Class 2 agent: the steps below describe the Class 1 path only. Class 2 integration requires a separate SymbiontInstaller code path for plugin registration — consult the opencode implementation as the reference. Do not attempt to adapt the file-based manifest/hook steps for a plugin-API agent.

Steps

1. Create the Symbiont Manifest

Manifests live in src/symbionts/manifests/. Create <agent-name>.yaml:

name: my-agent
displayName: My Agent
configDir: .myagent          # project-local config directory this agent uses

# Required: controls per-project activation default at myco init
defaultEnabled: true         # or false — SymbiontInstaller reads this at init time

# Optional: declare 'toml' if the agent uses TOML config files (e.g., Codex)
# settingsFormat: json       # default; omit for JSON-based config agents
# settingsFormat: toml       # required for agents like Codex that use config.toml

registration:
  hooksTarget: .myagent/hooks.json   # where to write hook registrations
  mcpTarget: .myagent/mcp.json       # where to write MCP server config
  skillsTarget: .myagent/skills/     # where to symlink skills
  hookFields:                         # payload field normalization (if needed)
    session_id: sessionId             # agent-specific field name → canonical name
  resumeCommand: my-agent resume      # optional: how to resume a session

# Optional: for agents needing their own instruction file
# instructionsFile: MY-AGENT.md       # omit if agent reads AGENTS.md natively

defaultEnabled is required. SymbiontInstaller reads this field during myco init to populate the project's symbionts list in myco.yaml. A manifest without defaultEnabled means the symbiont won't be included in the init-time activation list, even if installed on the machine. The field must be explicit — there is no fallback default.

settingsFormat controls how the installer reads and writes the agent's config file. Default is 'json'. Set settingsFormat: toml for agents whose settings file is TOML-based (e.g., Codex uses config.toml). The installer dispatches on this field when writing MCP entries and hook registrations — an incorrect or missing value will write JSON syntax into a TOML file and break the agent's config. TOML read/write operations use src/symbionts/toml-helpers.ts (upsertTomlSection / removeTomlSectionKeys) — reference that module rather than hand-rolling TOML string manipulation.

2. Register in SymbiontInstaller

Open src/symbionts/installer.ts and add the new symbiont to the registry:

import myAgentManifest from './manifests/my-agent.yaml';

export const SYMBIONT_MANIFESTS = [
  claudeCodeManifest,
  cursorManifest,
  // ... existing ...
  myAgentManifest,  // add here
];

The order in SYMBIONT_MANIFESTS determines display order in myco init interactive prompts and myco doctor output.

3. Create Hook Templates

Hook templates define the hook scripts written to the agent's config directory during myco init.

Create template files in src/symbionts/templates/<agent-name>/:

src/symbionts/templates/my-agent/
  session-start.sh
  user-prompt-submit.sh
  post-tool-use.sh
  stop.sh

Each hook script must:

1. Include the cross-platform hook guard at the top (see below)
2. Call myco-run hook <event> with the correct payload
3. Forward MYCO_AGENT_SESSION to prevent re-entrancy

Template example:

#!/bin/bash
# Cross-platform hook guard — prevents execution if myco is not installed
source "$(dirname "$0")/../myco-hook.cjs" 2>/dev/null || exit 0

export MYCO_AGENT_SESSION=1
myco-run hook session-start \
  --session-id "$SESSION_ID" \
  --agent my-agent

4. Wire the Cross-Platform Hook Guard

The hook guard .agents/myco-hook.cjs prevents hooks from failing for OSS contributors who don't have Myco installed. It is a CJS module that:

• Checks if myco-run is available on PATH
• Exits cleanly if Myco is not installed (no error, no noise)
• Is sourced at the top of every hook script before any Myco commands

New symbiont hooks must source this guard. Do not inline the guard logic — reference the shared file to keep updates centralized.

5. Handle Hook Payload Normalization

If the new agent's hook payloads use different field names than the canonical format, declare the mapping in the manifest's hookFields section:

hookFields:
  session_id: trajectory_id          # agent uses trajectory_id, Myco expects session_id
  tool_name: tool_info.command_line  # dot-path for nested fields
  # session_id: $env:AGENT_SESSION   # env-var source (prefix with $env:)

normalizeHookInput() reads the active manifest at hook runtime and applies the mapping before any processing logic runs. Each hook invocation is a fresh process, so per-invocation manifest detection is correct.

6. Wire Instruction File (If Needed)

If the new agent does not read AGENTS.md natively, declare instructionsFile in the manifest:

registration:
  instructionsFile: MY-AGENT.md

SymbiontInstaller.installInstructions() will write a thin stub that defers to AGENTS.md. If the file already exists, a reference block is prepended (idempotently) rather than overwriting user content.

Agents that read AGENTS.md natively (Cursor, Codex, Windsurf) should omit instructionsFile entirely — the installer skips instruction file management for them.

7. Implement the Transcript Adapter

The intelligence pipeline needs a transcript parser for each agent's session format:

Create src/symbionts/adapters/<agent-name>.ts:

export function parseMyAgentTranscript(content: string): Turn[] {
  // Parse the agent's transcript format into canonical Turn objects
  // Each Turn has: role ('user' | 'assistant'), content, and optional toolCalls
}

Register the adapter in src/symbionts/adapters/index.ts.

Common format pitfalls:

• Some agents use JSONL (one JSON object per line) — parse line by line
• Some use a single JSON file with a messages array — do NOT parse line by line
• Some use delta JSONL (state-replay format) — must replay deltas in sequence

8. Test the Integration

After wiring everything:

myco init     # should include new symbiont in symbionts list if defaultEnabled: true
myco doctor   # should check new symbiont's registration state
myco update   # should refresh hooks and MCP for new symbiont
make build    # must pass all 1,600+ tests with 0 TypeScript errors

Verify myco init includes the new symbiont in the generated myco.yaml:

symbionts:
  - claude-code
  - my-agent      # should appear if defaultEnabled: true

Common Pitfalls

Missing defaultEnabled in manifest. This is the most impactful omission: SymbiontInstaller reads this field at myco init to seed the project's symbionts list. Without it, the symbiont will never be in the default activation list for new projects. Developers must add it manually after init. The field must be a boolean (true or false) — there is no implicit default.

Missing or wrong settingsFormat for TOML-based agents. Codex uses config.toml, not settings.json. Its manifest must declare settingsFormat: toml. Without this, the installer writes JSON syntax into a TOML file and silently corrupts the agent's config. Additionally, Codex hooks are experimental and require an explicit feature flag in config.toml:

[features]
hooks = true

Without this block, hooks defined in the symbiont manifest are silently ignored by Codex regardless of how they are registered. (Codex previously named the flag codex_hooks; that spelling is now deprecated and emits a warning. Updating the template drops the stale key automatically because installSettingsToml reconciles each Myco-managed section against the template — the section body is rewritten on every install, not just patched key-by-key.)

Class 2 agents cannot use this procedure. Plugin-API agents (e.g., opencode) do not expose a config directory for file-based hook/MCP injection. Attempting to wire them via manifest + template steps will produce a silently incomplete integration. These agents require a dedicated installation code path in SymbiontInstaller. Do not adapt the Class 1 steps for a plugin-API agent.

Class 2 (opencode): client.app.log is silently swallowed. Output via client.app.log() is swallowed by the TUI and does not appear anywhere observable. Use console.error() for debug output during Class 2 plugin development — it appears in opencode's stderr stream.

Class 2 (opencode): chat.message({ synthetic: true }) causes infinite crash loops. Injecting synthetic messages via chat.message() triggers the model to respond, which re-enters the plugin callback, which injects another message — a hard crash loop with no escape. Use session.prompt({ noReply: true }) with TextPartInput.synthetic: true to inject content without triggering a model response.

Class 2 (opencode): OSS safety pattern differs from hook guard. Unlike Class 1 symbiont hooks (which source .agents/myco-hook.cjs), Class 2 plugins check for .myco/daemon.json at startup using a filesystem check. If the file is absent (Myco not installed), the plugin exits silently as a no-op. Do not use shell guard sourcing — the plugin runs in the opencode process context.

Class 2 (opencode): Use server.instance.disposed for cleanup. This event fires reliably on TUI exit (Ctrl+C or q). It is the correct hook for cleanup operations (closing connections, flushing state). Do not rely on process exit signals directly.

Using getEnabledSymbiontNames() is the canonical read path. Don't filter myco.yaml.symbionts inline in new code. Always call getEnabledSymbiontNames(config) from src/config/loader.ts. This was previously copy-pasted in 3 places before being canonicalized.

Forgetting the hook guard. Hooks without the cross-platform guard will fail loudly for contributors without Myco installed. Always source .agents/myco-hook.cjs at the top of every hook script.

hookFields for camelCase or nested fields. Many agents use non-snake-case field names (e.g., VS Code uses sessionId not session_id). Declare the mapping in hookFields rather than special-casing it in hook scripts or normalizeHookInput logic.

Hardcoding agent detection. The installer uses config directory presence (.myagent/ exists) as the signal for "agent is used in this project" — NOT binary-on-PATH presence. Binary detection was removed from the init flow. Don't add it back.

instructionsFile for AGENTS.md-native agents. Cursor, Codex, and Windsurf read AGENTS.md natively — their manifests must NOT declare instructionsFile, or they'll get an unnecessary stub written at init time.