mantisai-cli 3.0.0 → 3.1.0

package/README.md

@@ -10,6 +10,7 @@ Full docs (VitePress):
 - [Install](https://mantis.csail.mit.edu/docs/mantis-cli/install)
 - [Claude Code](https://mantis.csail.mit.edu/docs/mantis-cli/claude-code)
 - [OpenCode](https://mantis.csail.mit.edu/docs/mantis-cli/opencode)
+- [Codex](https://mantis.csail.mit.edu/docs/mantis-cli/codex)
 
 Source: `Mantis/docs/mantis-cli/`
 
@@ -33,7 +34,7 @@ Config: `~/.mantis/config.json`
 
 | Command | Description |
 | --- | --- |
-| `mantis setup [claude\|opencode]` | API + space/thread, or sync editor skills |
+| `mantis setup [claude\|opencode\|codex]` | API + space/thread, or sync editor skills |
 | `mantis status` | Current config |
 | `mantis select [space\|thread\|both]` | Switch space/thread |
 | `mantis spaces list\|resolve\|set` | Scriptable space ops (JSON) |

package/bin/mantis.js

@@ -104,7 +104,7 @@ program
 
   .description('Mantis CLI — spaces, maps, and MCP tools for AI agents')
 
-  .version('3.0.0');
+  .version('3.1.0');
 
 
 
@@ -112,15 +112,17 @@ program
 
   .command('setup [provider]')
 
-  .description('Configure Mantis, or install skills for claude/opencode')
+  .description('Configure Mantis, or install skills for claude/opencode/codex')
 
-  .action(async (provider) => {
+  .option('--project', 'Also sync repo-scoped skills (Codex: ./.agents/skills/)')
+
+  .action(async (provider, opts) => {
 
     try {
 
       if (!provider) return setup.run();
 
-      setup.runProvider(provider);
+      setup.runProvider(provider, { project: !!opts.project });
 
     } catch (e) {
 
@@ -368,6 +370,8 @@ program
 
   .allowUnknownOption()
 
+  .allowExcessArguments()
+
   .action(async () => {
 
     try {

package/lib/constants.js

@@ -10,4 +10,17 @@ export const DISABLED_MCP_TOOLS = new Set([
   'create_space',
   'create_map_from_url',
   'modify_map_from_url',
+  // sandbox-bound: require an X-Chat-ID + live AgentSession container that the
+  // CLI has no way to provide. only usable by in-sandbox cc/oc agents.
+  'export',
+  'cite_file',
+  // notebook cell tools: hidden from cc/oc on the API side and not intended
+  // for agent/CLI use — cells round-trip through the user's notebook UI.
+  'add_cell',
+  'edit_cell',
+  'delete_cell',
+  'execute_cell',
+  'get_cell',
+  'get_cell_count',
+  'check_task_status',
 ]);

package/lib/container.js

@@ -7,12 +7,14 @@ import { FastGlobCodebaseIndexer } from './impl/fast-glob-codebase-indexer.js';
 import { FsCsvReader } from './impl/fs-csv-reader.js';
 import { ClaudeSkillsService } from './impl/claude-skills-service.js';
 import { OpencodeSkillsService } from './impl/opencode-skills-service.js';
+import { CodexSkillsService } from './impl/codex-skills-service.js';
 import { SelectionService } from './services/selection-service.js';
 import { SetupService } from './services/setup-service.js';
 import { MapService } from './services/map-service.js';
 import { QueryService } from './services/query-service.js';
 import { ContextService } from './services/context-service.js';
 import { ToolService } from './services/tool-service.js';
+import { ExportService } from './services/export-service.js';
 
 export function createContainer(overrides = {}) {
   const configStore = overrides.configStore ?? new FileConfigStore();
@@ -24,13 +26,15 @@ export function createContainer(overrides = {}) {
   const csvReader = overrides.csvReader ?? new FsCsvReader();
   const claudeSkills = overrides.claudeSkills ?? new ClaudeSkillsService();
   const opencodeSkills = overrides.opencodeSkills ?? new OpencodeSkillsService();
+  const codexSkills = overrides.codexSkills ?? new CodexSkillsService();
 
   const selection = new SelectionService({ configStore, spaces, client, ui });
-  const setup = new SetupService({ configStore, selection, claudeSkills, opencodeSkills, ui });
+  const setup = new SetupService({ configStore, selection, claudeSkills, opencodeSkills, codexSkills, ui });
   const map = new MapService({ configStore, client, spaces, csvReader, ui });
   const query = new QueryService({ configStore, spaces });
   const context = new ContextService({ configStore });
-  const tools = new ToolService({ mcp });
+  const exporter = new ExportService({ configStore, client });
+  const tools = new ToolService({ mcp, exporter });
 
   return {
     configStore,
@@ -42,12 +46,14 @@ export function createContainer(overrides = {}) {
     csvReader,
     claudeSkills,
     opencodeSkills,
+    codexSkills,
     selection,
     setup,
     map,
     query,
     context,
     tools,
+    exporter,
   };
 }
 

package/lib/impl/codex-skills-service.js

@@ -0,0 +1,19 @@
+import os from 'node:os';
+import path from 'node:path';
+
+import { SKILLS_DIR } from '../utils/package-root.js';
+import { syncSkills } from '../utils/skills-sync.js';
+
+export class CodexSkillsService {
+  sync(cwd = process.cwd(), { project = false } = {}) {
+    const globalSkillsDir = path.join(os.homedir(), '.agents', 'skills');
+    const targets = [globalSkillsDir];
+    let projectSkillsDir;
+    if (project) {
+      projectSkillsDir = path.join(cwd, '.agents', 'skills');
+      targets.push(projectSkillsDir);
+    }
+    const installed = syncSkills({ skillsDir: SKILLS_DIR, targets });
+    return { globalSkillsDir, projectSkillsDir, installed };
+  }
+}

package/lib/impl/http-mantis-client.js

@@ -75,6 +75,49 @@ export class HttpMantisClient {
     });
   }
 
+  /**
+   * Export the rows behind a Mantis URI as parquet bytes.
+   * Returns { data: Buffer, rows, fields } on success.
+   * Throws on HTTP error, surfacing the server's structured error body.
+   */
+  async exportUri({ uri, spaceStateId, fields, includeEmbedding = false }) {
+    const { apiBaseUrl, apiKey } = this._credentials();
+    if (!spaceStateId) {
+      throw new Error('No thread configured. Run: mantis setup or mantis select thread');
+    }
+    const root = normalizeBaseUrl(apiBaseUrl);
+    const url = new URL('/api/v1/me/export/', `${root}/`);
+    const body = { uri, space_state_id: String(spaceStateId), include_embedding: Boolean(includeEmbedding) };
+    if (fields && fields.length) body.fields = fields;
+
+    const res = await fetch(url, {
+      method: 'POST',
+      headers: {
+        Authorization: `Bearer ${apiKey}`,
+        'Content-Type': 'application/json',
+        Accept: 'application/vnd.apache.parquet, application/json',
+      },
+      body: JSON.stringify(body),
+    });
+
+    if (!res.ok) {
+      // error responses are JSON; reuse the shared formatter.
+      const text = await res.text();
+      let data;
+      try {
+        data = text ? JSON.parse(text) : {};
+      } catch {
+        data = { error: text || res.statusText };
+      }
+      throw new Error(formatApiError(data, res));
+    }
+
+    const buf = Buffer.from(await res.arrayBuffer());
+    const rows = Number(res.headers.get('x-mantis-rows')) || 0;
+    const fieldsHeader = res.headers.get('x-mantis-fields') || '';
+    return { data: buf, rows, fields: fieldsHeader ? fieldsHeader.split(',') : [] };
+  }
+
   async createMapInSpace(spaceId, { file, mapName, dataTypes, selectedFields, fieldWeights }) {
     const { apiBaseUrl, apiKey } = this._credentials();
     const root = normalizeBaseUrl(apiBaseUrl);

package/lib/impl/mcp-client-service.js

@@ -24,7 +24,7 @@ export class McpClientService {
     const transport = new StreamableHTTPClientTransport(new URL(mcpUrl(cfg)), {
       requestInit: { headers: this._headers(cfg) },
     });
-    const client = new Client({ name: 'mantisai-cli', version: '3.0.0' });
+    const client = new Client({ name: 'mantisai-cli', version: '3.1.0' });
     await client.connect(transport);
     try {
       return await fn(client);

package/lib/interfaces/mantis-client.js

@@ -8,6 +8,7 @@
  * @property {(spaceId: string, name?: string) => Promise<Thread>} createSpaceState
  * @property {(opts: { name: string, isPublic?: boolean }) => Promise<Space>} createSpace
  * @property {(spaceId: string, opts: object) => Promise<object>} createMapInSpace
+ * @property {(opts: { uri: string, spaceStateId: string, fields?: string[], includeEmbedding?: boolean }) => Promise<{ data: Buffer, rows: number, fields: string[] }>} exportUri
  */
 
 export {};

package/lib/services/export-service.js

@@ -0,0 +1,54 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const EXPORT_SUBDIR = 'mantis_data';
+
+/** Local sandbox dir for exported parquet files: ~/.mantis/mantis_data/ */
+export function exportDir() {
+  return path.join(os.homedir(), '.mantis', EXPORT_SUBDIR);
+}
+
+function suggestFilename(uri, nRows) {
+  const tail = String(uri).replace(/\/+$/, '').split('/').pop() || 'export';
+  const safe = tail.replace(/[^a-zA-Z0-9_-]/g, '_').slice(0, 40);
+  return `${safe}_${nRows}rows.parquet`;
+}
+
+/**
+ * Fetches the parquet behind a Mantis URI from the API and writes it under
+ * ~/.mantis/mantis_data/. The CLI-local twin of the in-sandbox `export` MCP
+ * tool — same parquet, written to the user's own machine instead of a
+ * container.
+ */
+export class ExportService {
+  constructor({ configStore, client }) {
+    this.configStore = configStore;
+    this.client = client;
+  }
+
+  async exportUri(uri, { fields, out, includeEmbedding = false } = {}) {
+    if (!uri) throw new Error('A Mantis URI is required (e.g. mantis://map/<id>).');
+    const cfg = this.configStore.requireAuth();
+    if (!cfg.spaceStateId) {
+      throw new Error('No thread configured. Run: mantis setup or mantis select thread');
+    }
+
+    const { data, rows, fields: cols } = await this.client.exportUri({
+      uri,
+      spaceStateId: cfg.spaceStateId,
+      fields,
+      includeEmbedding,
+    });
+
+    let name = out ? path.basename(out) : suggestFilename(uri, rows);
+    if (!name.endsWith('.parquet')) name += '.parquet';
+
+    const dir = exportDir();
+    fs.mkdirSync(dir, { recursive: true });
+    const outPath = path.join(dir, name);
+    fs.writeFileSync(outPath, data);
+
+    return { path: outPath, rows, fields: cols, format: 'parquet', size_bytes: data.length };
+  }
+}

package/lib/services/setup-service.js

@@ -1,14 +1,15 @@
 import { DEFAULT_API_BASE, DEVELOPER_PORTAL_URL } from '../constants.js';
 import { normalizeBaseUrl, mcpUrl } from '../utils/url.js';
 
-const PROVIDERS = new Set(['claude', 'opencode']);
+const PROVIDERS = new Set(['claude', 'opencode', 'codex']);
 
 export class SetupService {
-  constructor({ configStore, selection, claudeSkills, opencodeSkills, ui }) {
+  constructor({ configStore, selection, claudeSkills, opencodeSkills, codexSkills, ui }) {
     this.configStore = configStore;
     this.selection = selection;
     this.claudeSkills = claudeSkills;
     this.opencodeSkills = opencodeSkills;
+    this.codexSkills = codexSkills;
     this.ui = ui;
   }
 
@@ -51,14 +52,14 @@ export class SetupService {
     this.ui.info(`Thread: ${cfg.spaceStateName || '-'} (${cfg.spaceStateId || '-'})`);
     this.ui.info(`MCP:    ${mcpUrl(cfg)}`);
     this.ui.info('Explore with: mantis tools && mantis use get_space_context');
-    this.ui.info('Editor skills: mantis setup claude | mantis setup opencode');
+    this.ui.info('Editor skills: mantis setup claude | opencode | codex');
     console.log('');
   }
 
-  runProvider(provider) {
+  runProvider(provider, { project = false } = {}) {
     const p = String(provider || '').toLowerCase();
     if (!PROVIDERS.has(p)) {
-      throw new Error(`Unknown provider "${provider}". Use: claude, opencode`);
+      throw new Error(`Unknown provider "${provider}". Use: claude, opencode, codex`);
     }
 
     if (p === 'claude') {
@@ -70,12 +71,28 @@ export class SetupService {
       return { provider: p, skillsDir, installed };
     }
 
-    const { globalSkillsDir, projectSkillsDir, installed } = this.opencodeSkills.sync();
-    this.ui.banner('Mantis skills → OpenCode');
+    if (p === 'opencode') {
+      const { globalSkillsDir, projectSkillsDir, installed } = this.opencodeSkills.sync();
+      this.ui.banner('Mantis skills → OpenCode');
+      this.ui.success(`Synced ${installed.length} skill(s)`);
+      this.ui.info(`Global:  ${globalSkillsDir}`);
+      this.ui.info(`Project: ${projectSkillsDir}`);
+      for (const s of installed) this.ui.info(`${s.slash}  ← skills/${s.source}`);
+      return { provider: p, globalSkillsDir, projectSkillsDir, installed };
+    }
+
+    const { globalSkillsDir, projectSkillsDir, installed } = this.codexSkills.sync(undefined, { project });
+    this.ui.banner('Mantis skills → Codex');
     this.ui.success(`Synced ${installed.length} skill(s)`);
-    this.ui.info(`Global:  ${globalSkillsDir}`);
-    this.ui.info(`Project: ${projectSkillsDir}`);
-    for (const s of installed) this.ui.info(`${s.slash}  ← skills/${s.source}`);
+    this.ui.info(`USER:  ${globalSkillsDir}`);
+    if (projectSkillsDir) {
+      this.ui.info(`REPO:  ${projectSkillsDir}`);
+      this.ui.info('Same skill names in USER + REPO may appear twice in Codex; disable one via /skills if needed.');
+    } else {
+      this.ui.info('Repo copy skipped. Re-run with --project to also write ./.agents/skills/ for team commit.');
+    }
+    for (const s of installed) this.ui.info(`$${s.name}  ← skills/${s.source}`);
+    this.ui.info('Invoke with $mantis or /skills. Restart Codex if new skills do not appear.');
     return { provider: p, globalSkillsDir, projectSkillsDir, installed };
   }
 }

package/lib/services/tool-service.js

@@ -1,25 +1,94 @@
 import { DISABLED_MCP_TOOLS } from '../constants.js';
 
+const NOTEBOOK_TOOLS = new Set([
+  'add_cell',
+  'edit_cell',
+  'delete_cell',
+  'execute_cell',
+  'get_cell',
+  'get_cell_count',
+  'check_task_status',
+]);
+
+// Synthetic tool entry for `export`. The server-side MCP `export` needs an
+// agent sandbox the CLI can't provide, so it's filtered from the raw list;
+// this local variant resolves the URI via REST and writes parquet under
+// ~/.mantis/mantis_data/ on the user's machine instead.
+const LOCAL_EXPORT_TOOL = {
+  name: 'export',
+  description:
+    'Export every row behind a Mantis URI to a local parquet file under '
+    + '~/.mantis/mantis_data/. Use for bulk-row analysis (correlations, '
+    + 'distributions, top-K, outliers) instead of paging inspect(). Read it '
+    + "back with pandas: pd.read_parquet(<path>). Always adds _point_id, "
+    + '_cluster_id, _cluster_label. Capped at 200,000 rows.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      uri: {
+        type: 'string',
+        description: 'Mantis URI resolving to a point set (map, cluster, bag, point, selection).',
+      },
+      fields: {
+        type: 'array',
+        items: { type: 'string' },
+        description: 'Column names to project. Omit to export all fields.',
+      },
+      filename: {
+        type: 'string',
+        description: 'Output filename (basename only). Defaults to <uri-tail>_<n>rows.parquet.',
+      },
+      include_embedding: {
+        type: 'boolean',
+        description: 'Add _embedding (1536-d) and _embedding_2d columns.',
+      },
+    },
+    required: ['uri'],
+  },
+};
+
+function normalizeFields(fields) {
+  if (fields == null) return undefined;
+  if (Array.isArray(fields)) return fields;
+  // `--fields title,rating` arrives as a comma string via parseToolArgs.
+  return String(fields).split(',').map((s) => s.trim()).filter(Boolean);
+}
+
 function disabledToolError(name) {
   if (name === 'create_space') {
     return 'create_space is disabled in the CLI. Use: mantis setup or mantis select space';
   }
+  if (name === 'cite_file') {
+    return `${name} is unavailable in the CLI — it needs an agent sandbox (X-Chat-ID + live container) that the CLI cannot provide. It only works for in-sandbox claude_code/opencode agents.`;
+  }
+  if (NOTEBOOK_TOOLS.has(name)) {
+    return `${name} is unavailable in the CLI — notebook cell tools round-trip through the user's notebook UI and are not intended for agent/CLI use.`;
+  }
   return `${name} is disabled in the CLI. Use: mantis create map or mantis create codebase`;
 }
 
 export class ToolService {
-  constructor({ mcp }) {
+  constructor({ mcp, exporter }) {
     this.mcp = mcp;
+    this.exporter = exporter;
   }
 
   async listTools() {
     const data = await this.mcp.listTools();
-    return {
-      tools: (data.tools || []).filter((t) => !DISABLED_MCP_TOOLS.has(t.name)),
-    };
+    const tools = (data.tools || []).filter((t) => !DISABLED_MCP_TOOLS.has(t.name));
+    // inject the local export variant so it's discoverable via `mantis tools`.
+    tools.push(LOCAL_EXPORT_TOOL);
+    return { tools };
   }
 
   useTool(name, args = {}) {
+    if (name === 'export') {
+      return this.exporter.exportUri(args.uri, {
+        fields: normalizeFields(args.fields),
+        out: args.filename ?? args.out,
+        includeEmbedding: args.include_embedding ?? args.includeEmbedding ?? false,
+      });
+    }
     if (DISABLED_MCP_TOOLS.has(name)) throw new Error(disabledToolError(name));
     return this.mcp.callTool(name, args);
   }

package/lib/utils/skills-sync.js

@@ -23,6 +23,9 @@ export function prepareSkillContent(content, installName) {
   yaml = /^name:\s/m.test(yaml)
     ? yaml.replace(/^name:\s.*$/m, `name: ${installName}`)
     : `name: ${installName}\n${yaml}`;
+  if (!/^description:\s/m.test(yaml)) {
+    yaml = `${yaml}\ndescription: Mantis CLI skill (${installName}).`;
+  }
   return `---\n${yaml}\n---${body}`;
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mantisai-cli",
-  "version": "3.0.0",
+  "version": "3.1.0",
   "description": "Mantis CLI — spaces, maps, and MCP tools for AI coding agents",
   "type": "module",
   "license": "MIT",

package/skills/mantis/SKILL.md

@@ -33,6 +33,7 @@ Install editor skills (CLI-only workflow, no MCP plugin):
 ```bash
 mantis setup claude     # ~/.claude/skills/
 mantis setup opencode   # ~/.config/opencode/skills/ + .opencode/skills/
+mantis setup codex      # ~/.agents/skills/ (add --project for ./.agents/skills/)
 ```
 
 ## MCP tools via CLI
@@ -42,13 +43,38 @@ Every Mantis MCP tool is available through the CLI — no editor MCP plugin requ
 ```bash
 mantis tools
 mantis use get_space_context
-mantis use get_cluster_children --map-id <uuid> --cluster-id <id>
-mantis use general_search --query "your search"
+mantis use search --query "your search"
+mantis use inspect --uri "<mantis-uri>"
 ```
 
 Use `--args '{"key":"value"}'` for complex arguments. Kebab flags map to snake_case (`--map-id` → `map_id`).
 
-Use map IDs, field types, and cluster names from the `get_space_context` output — do not guess them.
+Use map IDs, field types, and URIs from the `get_space_context` output — do not guess them.
+
+Common tools: `get_space_context`, `search`, `inspect`, `compare`, `union`/`intersect`/`diff`, the bag mutators (`create_bag`, `add_to_bag`, `filter_to_bag`, …), `set_plot_variables`, `legend_command`, `create_page`.
+
+Not available via `mantis use`:
+- `create_space`, `create_map_from_url`, `modify_map_from_url` — use `mantis setup` / `mantis create map` instead.
+- `cite_file` — needs an agent sandbox the CLI can't provide; in-sandbox agents only.
+- the notebook cell tools (`add_cell`, `execute_cell`, …) — not intended for agent use.
+
+## Bulk export (local parquet)
+
+`mantis use export` resolves a URI to its rows and writes a local parquet file under `~/.mantis/mantis_data/`. Use it when a question needs MANY rows (correlations, distributions, top-K, outliers) instead of paging `inspect`:
+
+```bash
+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:
+
+```bash
+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)