Agent Integration

Overview

Merfolk works with any coding agent that can run shell commands. Use an agent to turn working context into a first diagram or update an existing one, then share the result with the people who know the work. The --json flag makes every command machine-parseable, and the bundled skills teach the conventions upfront.

OpenCode

Install the skills:

merfolk skills install --agent opencode

Skills are written to ~/.config/opencode/skills/. OpenCode picks them up automatically on the next session.

Example agent prompt:

“Create a sequence diagram for the OAuth flow and save it to my Merfolk account.”

The agent will:

Write the Mermaid source
Run merfolk diagrams create --title "OAuth flow" --content "..." --json
Return the diagram URL from the JSON output

Claude Code

Install the skills:

merfolk skills install --agent claude

Skills are written to ~/.claude/skills/. Reference them in your CLAUDE.md or include them in your project context.

Example usage:

# In a Claude Code session
merfolk diagrams list --json | jq '.[].title'

Codex

Install the skills:

merfolk skills install --agent codex

Example workflow in a Codex session:

# Create a diagram from a description
ID=$(merfolk diagrams create --title "System architecture" --json | jq -r '.id')
echo "View at: https://app.merfolk.io/d/$ID"

Any agent

For agents without a named profile, install to a custom directory and reference the skill file in your agent’s context:

merfolk skills install --dir ~/my-agent/skills

Then point your agent at ~/my-agent/skills/merfolk/SKILL.md.

Consuming the docs from an agent

Agents can use the docs site directly:

# Discover all documentation pages
curl https://docs.merfolk.io/llms.txt

# Get a specific page as Markdown
curl https://docs.merfolk.io/cli/diagrams/list.md