Codex

mantis setup codex writes the CLI’s bundled skills into Codex’s skills directories. Invoke one with $mantis, or let Codex match your task against each skill’s description.

Install skills

mantis setup codex
# also write repo-scoped skills your team can commit
mantis setup codex --project

Per Codex Agent Skills, skills live in two scopes:

Scope	Path	When
USER	~/.agents/skills/<name>/SKILL.md	Always
REPO	./.agents/skills/<name>/SKILL.md	Only with --project, relative to your current directory

Without --project the CLI skips the repo copy and tells you so. Each skill is a folder holding a SKILL.md with name and description frontmatter. Codex discovers them automatically; restart Codex if new skills do not appear.

If the same name exists in both USER and REPO, Codex may show it twice. Disable one through /skills or a [[skills.config]] block.

Invoking skills

Codex reaches a skill two ways: explicitly, by typing $<name> or using /skills, and implicitly, by matching your task against the skill’s description.

Invocation	What it covers
$mantis	The hub skill: mantis:// URIs, the read-reason-mutate tool tiers, argument passing, bag building, bulk export.
$mantis-select	Switching the active space or thread by UUID, without opening the blocking interactive picker.
$mantis-extensions	Building, modifying, validating, packaging, and installing Mantis extensions and vertical panels.
$mantis-createmap	mantis create map from a local CSV, including how to type each column.
$mantis-codebase	mantis create codebase to index a repo into a searchable map.

$mantis-createmap and $mantis-codebase are explicit-invoke only. The other three Codex can select on its own.

Every skill tells Codex to run mantis use get_space_context before any other Mantis call.

Typical flow

1. Install and configure the CLI. npm install -g mantisai-cli, then mantis setup. See Install.
2. Sync the skills. mantis setup codex, adding --project from the repo root if you want to commit .agents/skills/.
3. Start Codex. Type $mantis, or ask about your Mantis workspace and let the description match.
4. Let it orient itself. Codex runs mantis use get_space_context, then other mantis use and mantis create commands.

Example prompts:

$mantis What maps are in my active space?
$mantis-select Switch me to the Repo Index space.
Search my Mantis map for papers about transformers.

To verify credentials, run mantis status in a terminal rather than asking a skill to do it.

MCP versus CLI

Do not add a Mantis MCP server to Codex. The CLI sends the auth header and X-Space-State-ID on every mantis use call, reading both fresh from ~/.mantis/config.json.

To disable a synced skill without deleting it, add a block to ~/.codex/config.toml and restart Codex:

[[skills.config]]
path = "/Users/you/.agents/skills/mantis/SKILL.md"
enabled = false

Antigravity uses the same directory

mantis setup antigravity also writes to ~/.agents/skills/. The contents are identical, so running both is harmless, but the second run overwrites the first.

Refresh after CLI updates

npm install -g mantisai-cli@latest
mantis setup codex

Skills are copied rather than linked, so this step is required after every upgrade.

Troubleshooting

Skills missing in Codex. Confirm ~/.agents/skills/mantis/SKILL.md exists, then restart Codex.

Codex does not use Mantis. Check mantis status in a terminal, then invoke $mantis explicitly.

Wrong thread. Run mantis select thread in a terminal, then have Codex call mantis use get_space_context again.

Reference: Agent Skills, Codex

Read nextOther editorsCursor, Windsurf, Copilot and Antigravity get the same skills.