Plugins
tackroom handles two kinds of plugin: Claude Code plugins, which keep their native layout and load in place from your config root, and agent-plugins-spec sources, whose skills and MCP servers sync like any other source's or reach Codex as a native plugin. Its own sync and jobs panel ships as a Claude Code plugin and a Pi package. Use this page to add either kind, or to get that panel.
tackroom sync # registers the marketplace and enables its plugins
tackroom status # the plugins column counts what is enabled
Add your own Claude Code plugins
A Claude Code plugin carries what the other surfaces cannot: mods, workflows, monitors, output styles, LSP servers and bin/ tools. Put each plugin in its native layout under the config root and list it in .claude-plugin/marketplace.json there:
{
"name": "my-agents",
"owner": { "name": "you" },
"plugins": [{ "name": "my-mods", "source": "./plugins/my-mods" }]
}
sync writes two things into ~/.claude/settings.json:
- it registers the config root under
extraKnownMarketplacesas adirectorysource; - it sets
enabledPlugins["<plugin>@<marketplace>"]totruefor each relative-path entry.
Claude Code reads a directory marketplace in place, so there is no install step and no plugin cache. Edit a plugin, run /reload-plugins, and the change is live.
What sync leaves alone or cleans up:
- A plugin you turn off in
/pluginstays off, also across a marketplace rename. - An entry with
defaultEnabled: false, in the marketplace or in the plugin's own.claude-plugin/plugin.json, is left for you to enable.statuslists it asplugins off. - An entry whose
sourceis the config root itself (".") or lives elsewhere, such as a GitHub repo, is skipped. - A bare plugin name resolves under
metadata.pluginRoot. - Enable keys for plugins the marketplace no longer lists are removed, and deleting the marketplace file removes the registration.
- A marketplace name already registered with another source, or a malformed
marketplace.jsonor settings key, is reported as a conflict and nothing is written.
tackroom doctor runs claude plugin validate on the config root when Claude Code is detected, and skips the check when there is no marketplace file.
Add an agent-plugins-spec source
A source that follows agent-plugins-spec is added like any external skill source. Its skills reach every harness, and mcp: true registers the MCP servers from its mcp.json.
external_skills:
- name: acme-tools
url: https://github.com/acme/agent-skills
branch: main
mcp: true # register the plugin's MCP servers
mcp_agents: [claude, codex] # optional; default: every harness with MCP
exclude_agents: [claude] # optional: no skills for these harnesses
tackroom skill sources add acme/agent-skills writes the pinned entry for you (skills.md). The source needs a plugin.json at its root.
The manifest names the schema https://agent-plugins.org/schemas/1.0.0/plugin.schema.json and a name of lowercase letters, digits, . and -, at most 64 characters. A missing or invalid manifest means mcp: true is ignored with a warning.
In mcp.json, tackroom takes stdio servers only:
streamable-httpandsseservers, and servers withcwd, are skipped with a warning.- A server name matches
[a-z0-9][a-z0-9_-]*. The command is a bare name or a./path inside the plugin. ${PLUGIN_ROOT}and${PLUGIN_DATA}expand inargsandenv, and both are also set as environment variables. The data folder is~/.agents/external-data/<source name>.- A server with the same name as one in your own
mcp_servers:is skipped, and so are servers that two plugin sources both declare.
The pin, the 72 hour cooldown and the audit gate apply as for any external source (skills.md). Servers a plugin adds are written and listed like your own (mcp.md).
- The audit names the source
plugin:<name>. - It also scans its stdio MCP servers and the raw
mcp.json(every transport),plugin.json,.codex-plugin/plugin.jsonandhooks/hooks.json. tackroom.lockrecords the plugin name and version.
Codex plugins
Codex loads a plugin from its own cache, so tackroom drives Codex's CLI (codex plugin marketplace add, codex plugin add, codex plugin remove) instead of writing that cache. A source is installed into Codex as a native plugin when all of these hold:
- Codex is detected and the source sets
mcp: true. - The cached source has a valid
plugin.jsonat its root. - Codex is an MCP target (
mcp_agentsis empty or listscodex) andexclude_agentsdoes not listcodex. - The source keeps the default skill layout: no
skills:,skill_dir:orskill_dirs:, because a plugin carries all of itsskills/folder. - The pin is not in cooldown or blocked.
For such a source Codex gets the skills and every MCP server, streamable-http ones included, from the plugin alone. sync links no skills and writes no [mcp_servers] rows for it into Codex. Other harnesses are unchanged, and a source without mcp: true keeps its skill links.
sync writes ~/.agents/external/.agents/plugins/marketplace.json, a generated marketplace named tackroom with one entry per plugin, and runs codex plugin marketplace add ~/.agents/external once.
It then runs codex plugin add <name>@tackroom when the plugin is not installed or Codex's copy differs from the cached source. It never writes Codex's plugin cache and never touches your own ~/.agents/plugins/marketplace.json.
tackroom status # plugins (1) acme@tackroom
- Turn one off. Set
enabled = falseunder[plugins."<name>@tackroom"]in~/.codex/config.toml.syncleaves it alone andstatuslists it asplugins off. Codex then has none of that source's skills or servers. To stop installing it for good, addcodexto the source'sexclude_agents, dropcodexfrommcp_agents, or setmcp: false. - Remove one. Deleting the source, or any setting above, makes the next
syncruncodex plugin remove, andcodex plugin marketplace remove tackroomwith the last plugin. The generatedmarketplace.jsongoes too. Only plugins ending in@tackroomare touched; plugins from other marketplaces never are. - Uninstalled in Codex. A plugin you remove with
codex plugin removecomes back on the nextsync, because the config declares it. Useenabled = falseinstead. - Same plugin name in two sources. Neither is installed into Codex, with a warning.
- A
tackroommarketplace from another source. Reported as a conflict, and nothing is written for plugins. - Failures. If
codexis not onPATHor acodex plugincall fails,syncreports an error for the Codex plugin surface; the other surfaces of that sync still apply.status,sync --dry-run,doctorand the views never runcodex: they read~/.codex/config.toml, the generated marketplace and Codex's plugin cache.
sync backs up ~/.codex/config.toml before the first codex call of a run, and runs codex with CODEX_HOME set to ~/.codex. Tested with codex-cli 0.159.2; tackroom does not check the version. Whether a Codex session loads the plugin's skills and tools is Codex's behavior, not checked by sync.
tackroom in Claude Code and Pi
The sync status and scheduled jobs from Crons are also available inside Claude Code and Pi, as a plugin and a package from the claude/ and pi/ folders of the repository.
claude plugin install tackroom --marketplace yourconscience/tackroom
pi install git:github.com/yourconscience/tackroom@v2.0.0
On a Pi entry with a packages list in tackroom.yaml, add the git: line to that list instead of running pi install, because sync writes the list as a whole (harnesses.md).
Both run tackroom from your PATH, show which harnesses are out of sync, list the jobs from tackroom cron collect, and act through tackroom cron run|pause|resume, the same verbs as the web view and the Herdr panel.
Claude Code
/tackroom opens a pane with the sync status, health counts per host, the jobs that need attention and every job per host. A job opens into its details with Run now, Pause and Resume. The plugin takes two options in /config: tackroom, the program to run, and config, the full path of a config file other than the default.
With tackroom 2.6 or newer the pane also syncs and edits, as the Herdr panel does. With an older tackroom the pane changes nothing but crons and says to update tackroom.
- Sync. When something waits, Sync shows the plan first: each change once with the harnesses it touches, and in red what the sync removes or overwrites. It applies that plan alone with
tackroom sync --plan-digest. When the plan or the config changed since it loaded, nothing is applied, the pane shows the refusal and loads the new plan. - Turn on and off. The Harnesses, MCP servers and Hooks sections open into one row each with Turn off or Turn on, and an MCP server or hook adds or removes one harness, through
tackroom config set. The change waits until you Sync. - Machines. With more than one machine in
crons.hosts, a Machines section shows each one's health, summary and the command that fixes it.
Pi
/tackroom lists the jobs with the sync status in the title; picking one shows its details and the same actions. Pi uses tackroom from the PATH and follows $TACKROOM_HOME.