Claude Code compatibility, config and plugins
What a harness session reads from a project (CLAUDE.md, .claude/, .mcp.json, venom.yaml, plugins, templates), how trust gates it, and the library APIs behind each.
A session reads a project's agent setup the way Claude Code does, so a repository set up for Claude Code works as it is. For an app this matters twice: it is free behaviour for your users' repositories, and it is an attack surface for repositories you do not control. This page covers what is read, how to turn it off, and the subpath exports that implement it.
What a session reads
| Source | What venom does with it |
|---|---|
AGENTS.md, CLAUDE.md, VENOM.md (project, parents, ~/.claude/CLAUDE.md) and their @imports |
memory files in the system prompt, within a size budget |
.claude/skills/, .venom/skills/, plugin skills |
skills, listed by name and description, loaded on demand |
.claude/commands/*.md, .venom/commands/*.md |
slash commands ($ARGUMENTS, !`cmd`, allowed-tools) |
.claude/agents/*.md, .venom/agents/*.md |
subagent definitions (subagents) |
.claude/settings.json, settings.local.json, ~/.claude/settings.json |
permission rules (Claude syntax mapped), defaultMode, additionalDirectories, hooks, env, model |
.mcp.json, ~/.claude.json |
MCP servers: stdio, streamable HTTP, and legacy SSE through a bridge |
Claude Code plugins (.claude-plugin/plugin.json) and venom plugins (venom-plugin.json) |
their commands, agents, skills, hooks, MCP servers and pi extensions |
venom.yaml or .venom/config.yaml (cwd, repository root), ~/.venom/config.yaml |
venom's config file |
.venom/templates/*.md |
session templates |
Each can be switched off: compat: false turns off all Claude Code sources, or pick with compat: { memory, skills, commands, agents, mcp, settings, hooks, plugins, user } (user: false ignores the user-level files under ~). contextFiles: false skips memory files; plugins: false skips venom plugins.
Trust
A project's hooks, MCP servers, env, allow rules and other loosening settings run commands or widen permissions, so they apply only once the project is trusted. Reading memory files, skills and deny rules does not need trust.
| Option | Behaviour |
|---|---|
| neither set | not trusted unless the user trusted it before in the CLI (pi's trust store plus venom's record of what the trust covered) |
projectTrusted: true / false |
force it, with no content check |
trust: async (req) => … |
asked once when the project ships such items, and again when a trusted project gained new ones. req.items, req.runs ("what would run") and req.changed describe them. Answer true, false, undefined (decide later) or "parent" |
Trust is tied to content: when a trusted project adds a hook or an MCP server, harness.trustChanged lists it and trust is suspended until confirmed. projectTrustState(...) and TrustContentStore expose the same decision.
For untrusted code (a customer upload, a pull request from a fork), use compat: false and leave trust off.
@venom/harness/compat
The pure loaders, no pi: loadMemoryFiles (with @import resolution and applyBudget), discoverCommands, parseCommandFile, expandCommand and macros (macroSteps, expandMacro), discoverAgents, parseAgentFile, loadClaudeSettings, mapClaudePermissions, mapClaudeRule, mapClaudeToolName, mapClaudeModel (sonnet → venom-default, haiku → venom-fast, opus → venom-smart), parseHooksConfig, runHooks, matcherMatches, loadClaudeMcpServers, translateMcpServer, expandClaudeVars (${VAR} and ${VAR:-default}), discoverPlugins, loadPlugin, parseFrontmatter, and the built-in skills (BUILTIN_SKILLS, materializeBuiltinSkills, searchSkills). Use them to show users what a session would load before starting one.
@venom/harness/config
venom's config file, as the CLI reads it. discoverConfigFiles({ cwd, venomHome }) finds the files (closest first), parseConfigText(text, { file, level, trusted }) validates one against CONFIG_SCHEMA without throwing (unknown keys come with a "did you mean"; credentials are dropped by key name and value shape; an untrusted project file loses its loosening keys), mergeConfigs merges levels (maps deep, lists replaced, null unsets), and loadVenomConfig({ cwd, venomHome, trusted }) does all three. setConfigValue(text, key, value) edits a file and keeps comments. Gears (named model setups): DEFAULT_GEARS, gearsFromConfig, resolveGear, pickModel, parseServerGears, loadGears. The keys themselves are in the configuration section.
@venom/harness/plugin and /plugins
/plugin is the SDK a plugin calls from inside a pi extension: venom(pi, { name, apiVersion? }) returns a VenomPluginAPI with registerTool, registerCommand, registerShortcut, registerLeaderBinding, registerBlockRenderer, setHudSegment, registerPanelSection, config, onHook, onCall, decisions and log; definePlugin wraps a plugin's entry; PLUGIN_API_VERSION is 1. /plugins (no pi) discovers and manages them: discoverAllPlugins, readPluginManifest, validateManifest, pluginStates (each PluginRecord.state is loaded, disabled, untrusted, invalid, missing, shadowed or denied), resolvePluginConfig, scaffoldPlugin and PLUGIN_TEMPLATES. A session loads allowed plugins' extensions unless loadPlugins: false. Writing one: plugins section.
@venom/harness/library
The team library: an organisation's shared skills and prompts in Venom Cloud. syncLibrary({ url, key, venomHome }) fetches it into a local cache (updated, unchanged on 304, or failed with the cache kept); with HarnessOptions.library set, org skills join the skill roots and org prompts become /org:<name> commands. expandLibraryPrompt expands $ARGUMENTS and {{name}} placeholders; resolveLibrary applies hidden entries.
@venom/harness/marketplace
The organisation plugin marketplace. installOrgPlugin({ url, key, venomHome, name, version?, keys, policy?, confirm? }) verifies the signed manifest (venom.marketplace/v1, Ed25519), checks the organisation policy, downloads and checksums the bundle, derives its permissions and asks confirm before an atomic install into <venomHome>/plugins/<name>/. Failures throw MarketplaceError with a code and leave nothing behind. Also: readBundle, inspectBundle, verifyMarketplaceManifest, removeOrgPlugin, listOrgInstalls.
@venom/harness/init
What venom init does, as a library. detectProject(root) finds ecosystems and their build, test and lint commands (with a safety rating each); planInit drafts a memory file (AGENTS.md), starter permission rules and .gitignore entries as InitFiles with diffs; applyInitFile(file, "write" | "propose" | "skip") writes one. runInit (root entry) adds a short model pass that reads the repository and writes the memory file. Secrets are scrubbed from anything drafted.
@venom/harness/templates
Session templates: a saved starting setup for a common job. A template is a markdown prompt with $ARGUMENTS and {{name}} placeholders plus frontmatter for the session it starts: gear, tools (allow rules), mode (plan, default or accept-edits, never auto or yolo), plan-exec and checks.
---
description: Draft a payment plan proposal for an account
argument-hint: account=<id>
mode: plan
tools: [lookup_account]
checks: ["npm test"]
---
Read account {{account}} and propose a payment plan that fits its history.Templates live in .venom/templates/ (trusted projects), ~/.venom/templates/, the team library (a prompt tagged template) and the built-ins (bug-fix, release, migration, dependency-bump, flaky-test-fix). After the same kind of job three times (judged from local session summaries), venom drafts a template once into ~/.venom/templates/proposed/ and nothing is saved until the user accepts it (/template learn). parseTemplate, expandTemplate (returns the text and any missing placeholders) and describeSetup are the API; the CLI's venom new and /template use them.
Related
- Plugins section
- Configuration section
- Security section, for trust from the user's side