Tap System

Taps are Homebrew-style registries for distributing Octomind agents, skills, and capabilities.

Overview

A tap is a Git repository (or local directory) containing:

agents/
  category/
    variant.toml    # Agent manifest
deps/
  [dependency definitions]
skills/
  skill-name/
    SKILL.md        # Skill instructions
    scripts/        # Executable scripts
    references/     # Documentation files
    assets/         # Static files
capabilities/
  capability-name/
    provider.toml   # Provider-specific capability config

Managing Taps

List Taps

octomind tap

Add a Tap

# From GitHub
octomind tap myorg/my-agents

# From local directory (symlink)
octomind tap myorg/my-agents /path/to/local/tap

Remove a Tap

octomind untap myorg/my-agents

Built-in Tap

The default tap muvon/octomind-tap is always active and ships production-ready agents.

Tap Priority

When multiple taps provide the same agent tag, priority is:

  1. User-added taps (in order added)
  2. Built-in default tap (muvon/octomind-tap)

Using Tap Agents

From the CLI

Run a tap agent with domain:spec format:

octomind run octomind:assistant
octomind run developer:general

When you specify a tag with :, Octomind:

  1. Searches taps for a matching agent manifest
  2. Downloads and resolves dependencies
  3. Merges the manifest into config
  4. Starts the session with the agent's role

From within a session — the tap core tool

Inside a running session you can launch a tap role as a subagent via the tap core tool. Same role catalog, but invoked from the LLM mid-conversation rather than a CLI command:

{"action": "discover", "intent": "review a legal contract"}
{"action": "run", "role": "lawyer:sg", "prompt": "What are the notice period rules?"}
{"action": "list"}
{"action": "stop", "session": "tap-lawyer-sg-9b2c1d"}

Use background: true for long tasks; the reply lands as a user message in the next turn. See MCP Tools — tap for the full schema.

Model Overrides

Set a preferred model for specific tap agents in your config:

[taps]
"developer:general" = "ollama:glm-5"

This overrides the model for octomind run developer:general while leaving other agents unchanged. Priority: CLI --model > [taps] override > role.model > config.model

Agent Manifests

Agent manifests are TOML files in agents/<category>/<variant>.toml. The header comment block is part of the schema — # Title: and # Description: are required (used by tap discover and octomind run autocomplete):

# agents/developer/general.toml
# Agent: developer:general
# Title: General Developer
# Description: Elite senior developer. Pragmatic, precise, zero waste.

[[roles]]
system = "You are an expert software developer..."
temperature = 0.3

[roles.mcp]
server_refs = ["core", "runtime", "filesystem"]
allowed_tools = ["core:*", "runtime:*", "filesystem:*"]

The role's name is auto-injected from the file path (category:variant becomes the name) — manifests don't need to declare it. Manifests can include any config sections: roles, layers, workflows, MCP servers, etc.

If the role needs runtime harness control (mcp / agent / skill tools), include "runtime" in server_refs. Most roles only need "core" (planning, scheduling, capability, tap) plus the data servers they actually use.

Skills

Skills are reusable instruction packs managed via the skill MCP tool. Auto-activation uses declarative rules: in SKILL.md frontmatter — see Skills for full documentation.

Skill Structure

skills/code-review/
  SKILL.md              # Instructions (injected into context)
  validate              # Optional: validation script
  scripts/
    lint.sh             # Executable scripts
    test.sh
  references/
    style-guide.md      # Documentation for AI to read
    patterns.md
  assets/
    config.json         # Static files

Using Skills in Session

# Discover skills
skill(action="list")

# Activate a skill
skill(action="use", name="code-review")

# Deactivate (triggers compression to clean up)
skill(action="forget", name="code-review")

When activated, the skill's SKILL.md is injected into context, and a resource catalog lists all available scripts, references, and assets with absolute paths.

Dependencies

Agent manifests can declare dependencies:

dependencies = ["octocode", "octofs"]

Dependencies are resolved and installed automatically on first run.

Capability Overrides

Taps provide capability implementations. Override which provider is used:

# In config.toml
[capabilities]
codesearch = "octocode"

This maps to capabilities/codesearch/octocode.toml within the tap, allowing different implementations of the same capability.

Storage

Taps are stored in ~/.local/share/octomind/taps/:

taps/
  user/
    myorg-my-agents/     # Git clone or symlink
  muvon/
    octomind-tap/        # Built-in default