Mantis

Mantis is a spatial data workspace. It embeds records — rows of a dataset, documents, code files, anything with text — into a 2D semantic map where proximity means similarity. Related records land near each other, and Mantis groups them into labelled clusters so the shape of a dataset is visible at a glance.

The core entities:

• Space — a workspace. Contains one or more maps and the threads (saved states) over them.
• Map — a single embedded dataset: points (records) laid out in 2D, with typed fields (semantic / categoric / numeric / date) and a cluster hierarchy.
• Cluster — an auto-generated, labelled group of nearby points. Clusters nest (a cluster has child clusters and, at the leaves, points).
• Bag — a named, user-defined set of points you build by filtering or hand-picking. The unit of "save this subset to come back to."
• Point — one record on the map.
• Thread (space state) — a saved view/state of a space; the active one scopes what your commands operate on.
• Extension — a trusted, portable package that adds sandboxed workspace panels, background commands or subscriptions, and optionally Python-backed actions through a permission-gated SDK.

You explore a map by reading its clusters and field schema, narrow to the points you care about with search and filters, save them as bags, and pull rows out only when a question needs the underlying data.

First step

Run this before any other Mantis command or tool (skip only if you already ran it this turn):

mantis use get_space_context

If it fails with no thread configured, run mantis setup or mantis select, then retry.

Companion skills

This /mantis skill is the hub for exploring and reshaping existing maps. Four companion skills cover the build, extension, and switch workflows — reach for one when the task matches, then come back here to work the map:

Extensions are scoped to the installing user in a space. A package may contribute one or more panels, a background host for durable behavior, and an optional Python backend. Panel and host code access Mantis only through window.mantis / mantis; protected SDK calls require explicit manifest permissions. Treat installation like installing an IDE extension: review its source, requested permissions, backend dependencies, and network access.

/mantis-select and /mantis-extensions are safe to invoke directly. /mantis-createmap and /mantis-codebase are user-facing slash commands that won't auto-trigger — when you're driving the flow yourself, just run the underlying mantis create map / mantis create codebase commands (documented under REST via CLI below). Either way, run mantis use get_space_context first.

Setup

mantis setup          # API key + space + thread (only prompts what's missing)
mantis status
mantis select         # switch the active space and/or thread

Config lives at ~/.mantis/config.json.

Install editor skills (CLI-only workflow, no MCP plugin):

mantis setup claude       # ~/.claude/skills/
mantis setup opencode     # ~/.config/opencode/skills/ + .opencode/skills/
mantis setup codex        # ~/.agents/skills/ (add --project for ./.agents/skills/)
mantis setup cursor       # ~/.cursor/skills/
mantis setup windsurf     # ~/.codeium/windsurf/skills/
mantis setup copilot      # ~/.copilot/skills/
mantis setup antigravity  # ~/.agents/skills/ + ./.agents/skills/

MCP tools via CLI

Every Mantis MCP tool is available through the CLI — no editor MCP plugin required:

mantis tools                                  # list every tool + its args
mantis use get_space_context                  # active space + maps (URIs + names)
mantis use inspect --uri "<mantis-uri>"

Mantis data lives on the server, not on disk — all work on a map happens through mantis use <tool>. Reach for a tool to inspect, search, and mutate Mantis entities; the data layer is the tools, addressed by mantis:// URIs.

Passing arguments

• Simple scalars can be flags: --uri "...", --kind cluster, --depth 1. Kebab flags map to snake_case (--map-id → map_id).
• Lists and objects MUST go through JSON — the CLI only coerces flag values to string/number/bool, so scope, uris, category_filters, etc. cannot be passed as --flag.

For any JSON payload, pipe it in with --args-stdin — this is the default and the form you should reach for. The JSON travels through stdin, so the shell never parses it and cannot strip its quotes. No escaping, no shell-specific quoting, works the same everywhere:

echo '{"query":"System Performance","kind":"cluster","scope":["mantis://map/<id>"]}' | mantis use search --args-stdin

echo '{"uris":["mantis://map/<id>"],"on":"distribution","field":"<field>"}' | mantis use compare --args-stdin

Write the JSON normally inside the single quotes — don't escape the inner ". The --args-stdin flag is required to read stdin (a bare mantis use <tool> never reads stdin, so it can't hang in an interactive terminal).

Avoid inline --args '{...}': on PowerShell/cmd the shell mangles the quotes before the CLI sees the blob (it can collapse {...} down to {\}), and once that happens the data is gone — escaping harder won't help. The CLI still accepts --args and recovers what it can (quote-stripping, BOM/UTF‑16), and it detects unrecoverable mangling and stops with a clear error rather than forwarding garbage — but --args-stdin sidesteps the whole problem, so prefer it. For very large payloads, --args-file <path> is an equivalent quote-proof alternative.

Never pass empty args — the CLI rejects an empty blob, because on a mutating tool like filter_to_bag "no filter" means match everything and would bag the whole map.

Use map IDs, field types, and URIs from get_space_context / tool output — never guess them.

The URI substrate

Every Mantis entity has a stable mantis:// URI you copy from one tool's output into the next tool's input:

mantis://space/<space_id>
mantis://map/<map_id>
mantis://map/<map_id>/cluster/<cluster_id>
mantis://map/<map_id>/bag/<bag_name>
mantis://map/<map_id>/point/<point_id>
mantis://map/<map_id>/dimensions          # the real, available field names
mantis://map/<map_id>/selection           # the user's current selection

Tools come in tiers — read first, reason next, then mutate

Tier 1 — orient (read):

• inspect --uri <uri> [--depth 1] — universal read. On a map → top clusters + bags + stats; on a cluster → child clusters (and its points); on .../dimensions → the real field names. This answers "what's this map about?" without touching row data.

Tier 2 — reason (read, no mutation):

• search with kind: point (default — searches record text, honors mode = hybrid|vector|lexical), cluster (fuzzy-match a cluster by its label), bag (fuzzy-match a bag by name). In a multi-map space, always pass scope=["mantis://map/<id>"] or search returns scope_required.
• compare --args '{"uris":[...],"on":"distribution","field":"<field>"}' — per-URI stats on a field; single-URI is the canonical "summarize this set on this field" (e.g. "what departments are in this cluster?"). on:"cluster_labels" with 2+ map URIs → shared vs unique themes.
• intersect / diff / union — set algebra over point sets (--args '{"uris":[...]}').
• export — bulk rows to local parquet (see Bulk export below).

Tier 3 — act (mutate):

• create_bag (--from-uri <uri> — cluster sources are recursive — or --args '{"point_uris":[...]}'), add_to_bag, remove_from_bag, rename_bag, delete_bag.
• filter_to_bag — structured filters → saved bag (see its own section below).
• set_plot_variables, legend_command, create_page.
• install_extension — install a local .mantisx, .zip, or JSON package for the current API-key user in an owned space.

Field names are validated. Any tool taking a field/dimension/value (compare, filter_to_bag, legend_command, set_plot_variables) returns {error:"unknown_field", available_fields:[...]} for a bad column. Before filtering or comparing on a field, run inspect --uri "mantis://map/<id>/dimensions" to get the real field names and their values — do not invent them, and do not export just to discover what a column's values look like.

Resolve names → URIs the fast way

To act on "the X cluster" or "the Y bag", resolve the name with search, then drill in — don't walk the tree with repeated inspect calls:

# "Bag the Agent-Platform Integration cluster"
mantis use inspect --uri "mantis://map/<id>"                                                   # confirm the map
echo '{"query":"Agent-Platform Integration","kind":"cluster","scope":["mantis://map/<id>"]}' | mantis use search --args-stdin   # → cluster_uri
mantis use create_bag --from-uri "<cluster_uri>" --name "Agent-Platform"

For making bags, see Building bags below — pick filter_to_bag vs create_bag first.

Scale the tool to the question. Descriptive questions ("what's this map about?", "what's in it?") are answered by get_space_context + one or two inspect calls — name, counts, field schema, cluster themes. Don't pull row-level data to describe shape. Reach for export only when the answer needs many actual rows (distributions, correlations, top-K, outliers).

Building bags — filter_to_bag vs create_bag

To make a bag, first decide which tool fits — getting this wrong is the most common bag mistake:

• All members share a field value ("only markdown files", "score > 0.7", "from 2022") → filter_to_bag in one call. Do NOT export rows and collect point IDs by hand.
• Arbitrary set with no common field (a specific .md plus three particular .js files) → create_bag with point_uris, or create_bag --from-uri <cluster_uri> for a whole cluster.

filter_to_bag takes exactly these filter arrays (there is no --filter flag — passing {"extension":"md"} is wrong). All active filters are ANDed; scope is applied first. Field names are validated — a typo returns available_fields.

// category_filters — case-insensitive exact match on a categoric field
{"field": "<col>", "values": ["md", "mdx"]}
// numeric_filters — range; omit min or max for an open bound
{"field": "<col>", "min": 10, "max": 50}
// date_filters — ISO-8601; "after"/"before", either or both
{"field": "<col>", "after": "2022-01-01", "before": "2023-12-31"}

# "bag only the markdown files"  (one shared field value → filter_to_bag)
mantis use inspect --uri "mantis://map/<id>/dimensions"     # confirm field `extension` and that "md" is a value
echo '{"scope":"mantis://map/<id>","category_filters":[{"field":"extension","values":["md"]}],"name":"Markdown Files"}' | mantis use filter_to_bag --args-stdin

# "bag this README plus its three helper scripts"  (arbitrary mix → create_bag)
echo '{"point_uris":["mantis://map/<id>/point/<p1>","mantis://map/<id>/point/<p2>"],"name":"README + helpers"}' | mantis use create_bag --args-stdin

scope accepts a full map / cluster / bag / selection URI (cluster scope is recursive); bare names are rejected — pass the URI. Use recency_days / recency_hours as a shortcut for "last N days/hours".

Anti-patterns (don't)

• Looking on disk for Mantis data — it lives on the server; use the tools.
• Guessing IDs or URIs — always copy them from a previous tool's output.
• Walking the cluster tree with inspect to find a cluster/bag by name — use search --kind cluster|bag.
• Inventing field names — inspect .../dimensions first.
• export-ing a whole map (then crunching pandas) just to learn a column's values or to see a few example rows — that's what inspect .../dimensions and compare(distribution) are for.
• search without scope in a multi-map space — it returns scope_required.
• Looping inspect over individual points to summarize a field — one compare(..., on:"distribution", field:...) does it.

To create a space or map there's no mantis use tool — use mantis setup / mantis create map (see REST via CLI). mantis tools already lists everything callable, so trust that list.

Bulk export (local parquet)

mantis use export resolves a URI to its rows and writes a local parquet file under ~/.mantis/mantis_data/. It pulls the entire point set (no row limit — capped only at 200,000), so use it only when a question genuinely needs MANY rows: correlations, distributions, top-K, outliers. For "what is this map" / "what's in it", prefer inspect — do not export just to see example rows. Narrow the URI to a cluster when you can.

mantis use export --uri "mantis://map/<id>"                                  # all rows
mantis use export --uri "mantis://map/<id>/cluster/<cid>" --fields title,rating
mantis use export --uri "mantis://map/<id>" --include-embedding              # + _embedding (1536-d), _embedding_2d

Prints {path, rows, fields, size_bytes}. Then read it locally:

python3 -c "import pandas as pd; df = pd.read_parquet('<path>'); print(df.head())"

Always-present columns: _point_id, _cluster_id, _cluster_label (so you can df.groupby('_cluster_label')). Capped at 200,000 rows — narrow the URI if you hit too_many_rows.

REST via CLI (setup & resources)

API keys: https://mantis.csail.mit.edu/developer/#keys

Conventions

• Refer to spaces and maps by name in user-facing text; use UUIDs in tool arguments.
• To link a space for the user, build the URL yourself: https://mantis.csail.mit.edu/space/<space_id> (that's the shareable web address for any space — take the <space_id> from get_space_context / tool output). mantis create map already prints this link; for a space you looked up, construct it the same way.
• After mantis select (or mantis spaces set / mantis threads set), the next mantis use picks up the new context automatically — no reload step.