What it does for you
MCP tells an agent which tools exist. plexus tells it how their outputs plug into each other's inputs. Each tool ships a small manifest; plexus builds the wiring graph, plans the pipeline that feeds the tool you want, and reports what does not connect. A plan carries a receipt tied to the exact manifests it came from, so a changed tool shows up as drift.
- Wiring from declarationsAn edge A to B forms when B consumes a capability A emits. Each edge cites the producer's own source pointer.
- Honest gapsInputs nothing emits, outputs nothing consumes, feedback loops and duplicate tool ids are all named.
- Plans for a goal
plexus plan --goalorders the tools that feed one target and names its sources. - Plans you can re-check
plexus verifyre-derives a plan's receipt from the current manifests and exits 1 on drift.
Source: README.md at d889be9 (release 0.4.0)
Watch
No concept film fits this tool closely yet. The walkthrough below covers it in text, with real commands and output.
Video walkthrough: coming with the next release.
How it works, one step at a time
Scroll, or use the step buttons. The first steps use two small manifests written for this page, notes and review. The last uses the ten built-in manifests that ship with plexus. Every line is output from plexus at commit d889be9.
- 01
Two tools declare their ports
notesemitsnotes.summary/1.reviewconsumesnotes.summary/1and astyle.guide/1, and emitsreview.verdict/1. Each port names the module behind it, such assrc/notes/summary.py:build.A manifest is plain JSON. A tool ships one and it joins the mesh.
Source: README.md, "How a tool plugs in"; src/plexus/manifest.py
- 02
Discover the edge
plexus discovermatches capability strings.reviewconsumes whatnotesemits, so one edge forms: notes to review vianotes.summary/1.The edge is tagged
evidence: declared. plexus copies the producer's module pointer intoviabut never imports or runs it. The citation is a claim for you to check.Source: src/plexus/mesh.py; README.md, "Declared, not probed"
- 03
Name what does not connect
Nothing in the set emits
style.guide/1, so it is an unmet input: an external or human input, or a tool that is not here. Nothing consumesreview.verdict/1, so it is a terminal output.Both come from the same comparison. An unmet input means only that no manifest in this set produces it.
Source: src/plexus/mesh.py,
orphans - 04
Plan the pipeline, with a receipt
plexus plan --goal revieworders the tools that feed review: notes, then review. Its receipt records the SHA-256 of each manifest and a hash over the derived plan, under a method version.Source: src/plexus/plan.py, src/plexus/receipt.py
- 05
Verify against the manifests you have now
plexus verifyre-derives the plan from the current manifests and rebuilds its receipt. Unchanged, it matches and exits 0.Now change
notesto emitnotes.summary/2. The manifest hash changes, the wiring changes, and verify exits 1. Pick each case in the panel.Source: src/plexus/receipt.py,
verify_plan - 06
The built-in mesh
plexus ships manifests for ten tools. Its tour wires them: gather feeds crucible through
gather.digest/1, mneme and crucible feed each other replay packs, and the plan for crucible reports its feedback loop as a loop.Source: examples/tour.py; src/plexus/registry.py
Walkthrough
Install it, run it once, then use the main feature. Each command below is real, and so is its output.
Install
Install from PyPI. Python 3.11 or newer; discovery runs no tool.
$ python -m pip install plexus-meshFirst run: is there a route?
Ask whether one tool's output can reach another's input through the built-in manifests.
$ plexus route --from gather --to crucible --builtin "connected": true, "hops": 1,Discover your own tools
Point plexus at a folder of manifests to see each tool's ports.
$ plexus discover --dir m producer notes consumer review capability notes.summary/1 self_loop false via src/notes/summary.py:build evidence declaredPlan and verify a pipeline
Plan a pipeline toward a goal, then verify the plan against the manifests you have now.
$ plexus plan --dir m --goal review order notes -> review sources notes cyclic [] receipt plexus.plan-receipt/1, method plexus-plan/1 notes 53ab6c24d374afa4... review 0d50accb0759561e... plan_sha256 aeb01289ea823d89...
Output from plexus at d889be9 run from source; plexus-mesh 0.4.0 is the current PyPI release.
What it does not do
- Edges come from declarations. Discovery never runs a tool, so an edge says two manifests agree. Whether the tools work together is a separate test.
probe_lanechecks that a lane's server is live. - An unmet input means no manifest in the set you gave produces it. plexus reasons about nothing outside that set.
verifychecks a saved plan's receipt against one re-derived from the current manifests. Act on the re-derived plan it reports, not on a saved file you have not re-derived.- The built-in manifests are kept in plexus. Their presence does not show that each tool publishes its own manifest.
Source: README.md at d889be9, "Declared, not probed" and "How a tool plugs in"; src/plexus/receipt.py
Check what stuck
Answer each one in your head before you open it.
When does an edge from A to B form?
When B consumes a capability that A emits, directly or through A's consumable_as list.
What does evidence: declared mean on an edge?
The edge comes from what the manifests say. plexus copied the producer's module pointer but did not follow or run it.
style.guide/1 shows up as an unmet input. Does that mean no such tool exists?
No. It means no manifest in the set plexus was given emits it.
A tool's manifest changes after you saved a plan. What does verify do?
It re-derives the receipt from the current manifests, the hashes no longer agree, and it exits 1.