The Claude Code plugin
One plugin brings Knossos into Claude Code. It carries:
- the session brief, injected when a session starts;
- the routing skill, which says which questions to bring to the graph;
- the mod: the band, the pane, the live watcher, and the messages for the model.
The plugin ships no binary of its own: its hooks run the knossos already on your machine. The installer installs it for you, and the rest of this page is for a checkout or for doing it by hand.
Install
Preview first:
knossos install-agent-pluginThis prints the two commands it would run, the data directory it would write into the hooks, and changes nothing:
claude plugin marketplace add '/home/me/knossos/.plugin' --scope user
claude plugin install knossos@knossos --scope user --yesThen install:
knossos install-agent-plugin --data-dir="$HOME/.knossos" --execute--execute writes the plugin directory, .plugin/ beside the checkout, and runs both commands. Options:
| option | what it does |
|---|---|
--execute | write .plugin/ and run the two claude commands; without it, a preview |
--scope=SCOPE | user (the default), project or local |
--data-dir=DIR | the data directory your server uses, written into the hooks (see below) |
--json | print the result as JSON |
--plugin-dir=DIR | where to write the plugin instead of .plugin/ |
--bin=PATH | the knossos the hooks call instead of the checkout's bin/knossos |
--no-register | write the plugin and run no claude command |
Start a new session afterwards. The brief appears at its start, and /knossos opens the pane once the project is scanned.
A release installed with install.sh picks its own defaults: the plugin goes to plugin/ in the install directory (~/.local/share/knossos/plugin, or <install dir>/plugin, in container mode) and the hooks call the launcher, so a knossos self-update never leaves them on an old version: it rewrites that directory in place, which Claude Code has registered. Restart Claude Code afterwards. Neither option may point inside that install's versions/. In container mode install-agent-plugin is refused, because the plugin is managed from the host.
For a containerised server, use --out instead; see the container guide.
The data directory
The MCP server and the hooks must read the same graph. The server gets its data directory from its own registration, and hooks never see that environment. So the install writes the data directory into the hooks, chosen in this order:
--data-dir=DIR, when you pass it.- The
KNOSSOS_DATA_DIRof the shell you install from. - The installation's own directory,
~/.knossos, when~/.knossos/knossos.sqliteexists. That is the graphtools/installcreates and the server reads. - None of these: the hooks fall back to the
.knossos/directory nearest the project, which is right only when your server uses that too.
The value must be an absolute path. The hooks then use DIR/roots.json as the roots file. A KNOSSOS_DATA_DIR or KNOSSOS_ROOTS_FILE already set in the environment Claude Code runs the hooks in takes precedence over the one written in.
To check which directory your server reads, call its server_info tool. See one data directory.
The hooks need a knossos binary
The hooks look for knossos in a fixed, short order:
KNOSSOS_BIN, when it is set and executable.- The
bin/knossosof the checkout that raninstall-agent-plugin. The installer writes its path into the plugin. knossosonPATH.~/.local/bin/knossos,/usr/local/bin/knossos.
A project's own bin/knossos is never run: opening a repository must not execute code it ships.
An installed plugin finds knossos in every project through the path the installer wrote in, so it needs nothing else. The exception is a --plugin-dir session from a checkout that never ran the installer: its scripts still hold the placeholder, so they fall through to PATH and the fixed locations. Every failure is silent by design, so such a session simply gets no brief, with nothing to say why. One symlink into a directory on that list makes it work:
ln -s /absolute/path/to/knossos/bin/knossos ~/.local/bin/knossosTry it for one session with --plugin-dir
Claude Code can load a plugin from a directory for one session, without installing it:
claude --plugin-dir /home/me/knossos/.pluginThat loads the plugin straight from .plugin/, which install-agent-plugin --execute writes. This is how the stills on the pane page were captured, in a Claude Code configuration of their own. Use it where the plugin is not also installed, so it loads once.
What .plugin/ holds
.plugin/ is what Claude Code is pointed at, and the whole of what it copies:
.claude-plugin/plugin.json, the manifest, rewritten with the running CLI's version;.claude-plugin/marketplace.json, the marketplace descriptor, generated;hooks/hooks.json, theSessionStarthook and the mod's module;hooks/register.tsx,hooks/lib/*.tsandhooks/mod/*, the mod, found by walkinghooks/; specs and tests (.spec.ts(x),.test.ts(x),__tests__/), declaration files andtsconfigfiles beside them are never copied, and the walk does not enter hidden directories,node_modules/or a symlinked directory;hooks/scripts/, the hook and wrapper scripts and their shared library, with the data directory and the path of theknossosbinary written in;skills/graph/SKILL.md, the routing skill;types/index.d.ts, the mod's types.
The checkout itself is never registered. Claude Code also keeps a copy of a local marketplace in its plugin cache, so registering the repository root would copy the whole working tree with it: vendor/, node_modules/, build caches, the graph database, and any stray config file. A directory holding only the plugin copies only the plugin.
.plugin/ is git-ignored, deliberately: most of it is copies of files already in the repository, and committing them would let the copies drift from their sources. Anything that deletes ignored files removes it. git clean -xdf in particular leaves the plugin failed to load: cache-miss. The same install command puts it back.
Update
An installed release updates its plugin with knossos self-update; see updating. The rest of this section is for a checkout.
Claude Code reads a plugin installed from a local directory in place: claude plugin list --json shows .plugin/ as its readFromFolder. After you update your checkout, or change a hook script, the skill or the mod, rewrite .plugin/ with the same --data-dir you installed with, because an update without it writes hooks that fall back to the project's own .knossos/:
knossos install-agent-plugin --data-dir="$HOME/.knossos" --executeThe change takes effect at the next session start, or at once with /reload-plugins.
If claude plugin list --json shows no readFromFolder for knossos@knossos, your Claude Code runs the copy in its plugin cache instead, cached by the version in the manifest (the install writes the running CLI's version there). Then a new release needs claude plugin update knossos@knossos and a restart, and a change within one version needs a fresh copy:
claude plugin uninstall knossos@knossos --scope user
knossos install-agent-plugin --data-dir="$HOME/.knossos" --executeAn install over an earlier one deletes the files the earlier one left in the plugin's own directories that this one no longer ships, such as a renamed module, and only those: never a subdirectory, never the plugin directory's root, never through a linked directory. It also removes the skill directories earlier installs used, skills/knossos and skills/ask-the-graph. A failed install puts everything back. A container install with --out deletes nothing, since that directory is whatever you named.
Remove
claude plugin uninstall knossos@knossos --scope user
claude plugin marketplace remove knossos
rm -rf /home/me/knossos/.pluginUse the scope you installed with. claude plugin uninstall also removes the plugin's data directory under ~/.claude/plugins/data/ unless you pass --keep-data. Your graph, in your Knossos data directory, is untouched, and so is the MCP server's registration.
Why there is no public marketplace route
claude plugin marketplace add AraneaDev/knossos fails with Marketplace file not found, on purpose. The descriptor is generated into .plugin/ and never committed.
A clone from a public marketplace would have no vendor/, so its own bin/knossos could not run, and the hooks fail silent on every error. Such an install would produce nothing, forever, with nothing to diagnose. The plugin needs a working binary beside it: the installer writes one into the plugin as the launcher, and from a checkout the one that already runs the server is the source.
The plugin and the MCP server are separate installs
Registering the server with an MCP client (see installation) does not need the plugin, and installing the plugin does not register a server.
A containerised installation you run by hand does not have a local knossos binary at all, so folding server registration into the plugin install would either duplicate an existing registration or assume one that is not there. The installer registers the server and installs the plugin as two steps.