Skip to content
Workspace
Docs

Connect a coding agent

Cortex plugins connect supported coding agents to your Account's knowledge and work. Each plugin loads Cortex guidance when a session starts and lets the coding agent use Cortex tools.

Cortex supports Codex, Claude Code, Cursor, and GitHub Copilot CLI.

The plugin contains the SessionStart hook and hosted MCP configuration. You do not need to install either component separately.

The hosted MCP surface includes operations that can create, update, and delete Cortex resources. Review the security model before changing your agent host's approval policy.

Required: Approve or trust the Cortex SessionStart hook when a coding agent asks. Without the hook, Cortex tools remain available, but the coding agent does not receive Cortex guidance automatically when a session starts.

Open guided setup to choose Plugin (preferred), CLI, or MCP and follow one step at a time. For the store installation, follow Connect ChatGPT.

Install automatically

Use the Socra CLI to detect and configure every supported coding agent installed on your computer.

Install the Socra CLI

macOS and Linux

Run these commands:

Bash
curl -fsSL https://cli.socra.cloud/install.sh | sh

Open a new terminal after the installer completes.

Install Cortex, sign in to your Account, and configure every detected coding agent:

Bash
socra install cortex
socra account login
socra cortex setup

The command detects supported coding agents, installs or updates each Cortex plugin, trusts the verified Codex SessionStart hook, and starts supported authentication flows. Follow the command's next steps to finish any authorization that the other hosts perform inside their own interfaces.

Authentication required: Each coding agent stores its own Cortex authorization. socra cortex setup may start a browser login or report that authorization needs to be completed in the host. If Codex authentication is incomplete, run:

Bash
codex mcp login cortex

For Claude Code, start claude, run /mcp, select the Cortex server, and follow its browser sign-in. If setup reports an unsupported Claude login command, complete authentication this way.

For Cursor, open Customize → MCPs (older versions: Settings → Tools & MCP), select Cortex, and connect. For GitHub Copilot CLI, start copilot, run /mcp, select Cortex, and sign in. Complete Account selection in the browser that opens. If setup already connected the intended Account, continue without signing in again.

When a configured coding agent asks whether to allow the Cortex SessionStart hook, approve it.

You can run socra cortex setup again. It updates outdated installations and does not create duplicate installations.

Install manually

Use the instructions for your coding agent when you do not want the Socra CLI to manage plugin installation.

Codex

Add the Socra marketplace and install Cortex:

Bash
codex plugin marketplace add socra/agent-plugins --ref main
codex plugin add cortex@socra

Authenticate the MCP connection:

Bash
codex mcp login cortex

Approve the bundled Cortex SessionStart hook if Codex asks, then start a new Codex session.

Claude Code

Add the Socra marketplace and install Cortex for your user profile:

Bash
claude plugin marketplace add socra/agent-plugins --scope user
claude plugin install cortex@socra --scope user

Authenticate the MCP connection:

Start claude, run /mcp, select the Cortex server, and follow the browser sign-in. Select the same Socra Account that you use in Cortex.

Approve the bundled Cortex SessionStart hook if Claude Code asks, then start a new Claude Code session.

Cursor

Clone the public plugin repository and link the Cursor provider directory:

Bash
git clone https://github.com/socra/agent-plugins.git
mkdir -p ~/.cursor/plugins/local
ln -s "$(pwd)/agent-plugins/providers/cursor/cortex" ~/.cursor/plugins/local/cortex

Restart Cursor or run Developer: Reload Window. Confirm that Cortex appears under Customize. Approve the bundled Cortex SessionStart hook if Cursor asks. Open Customize → MCPs (older versions: Settings → Tools & MCP), select Cortex, and sign in if prompted. Turn on every Cortex tool in the tools list above chat.

GitHub Copilot CLI

Add the Socra marketplace and install Cortex:

Bash
copilot plugin marketplace add socra/agent-plugins
copilot plugin install cortex@socra

Start copilot, approve the bundled Cortex SessionStart hook if GitHub Copilot CLI asks, then run /mcp. Select Cortex and sign in if prompted. Start a new session after authorization completes.

Other coding agents

Cortex does not currently provide a plugin for other coding agents. Configure the hosted Cortex MCP server if the agent supports remote HTTP MCP. An MCP-only connection provides Cortex tools but does not install the Cortex SessionStart context.

Allow the plugin instructions

The plugin supplies the suggested instructions at the start of a session. They teach your agent to Flash the right knowledge before acting and create or update Modules when you share useful knowledge or preferences. You do not need to add them to an AGENTS.md file. Installing tools alone is not enough: a host can skip an untrusted hook.

In Codex, type /hooks, open SessionStart, and select the hook whose source is cortex@socra. Review the command that reads the plugin's hooks/session-start.md, then press t to trust it. Confirm it is enabled and start a new session. Other supported hosts may ask to trust the Cortex SessionStart hook during installation or startup; approve that hook and restart the session.

See Codex hook review and the canonical Cortex instructions.

Enable Cortex tools

Make all Cortex tools available in your agent:

  • Codex: run /mcp and check that Cortex is connected with its tools available. The plugin enables all Cortex tools by default.
  • Claude Code: run /mcp, select Cortex, and check that its server and tools are enabled.
  • Cursor: open Customize → MCPs and confirm the connection. Turn on every Cortex tool in the tools list above chat.
  • GitHub Copilot CLI: run /mcp and check that Cortex is enabled. The plugin includes all Cortex tools. If its MCP server was disabled, run copilot plugins enable cortex --mcp.

Next, allow Cortex tools to run without repeated approval buttons. Use the Cortex-scoped setting for your provider:

  • Codex: set default_tools_approval_mode = "approve" under [plugins."cortex@socra".mcp_servers.cortex] in your Codex config. If you previously restricted tools there, set enabled = true, clear disabled_tools, and remove an enabled_tools allowlist.
  • Claude Code: in /permissions, add the Allow rule mcp__plugin_cortex_cortex__* for the Cortex plugin to your user settings, so it applies in future sessions. Existing deny rules still apply.
  • Cursor: add cortex:* to the MCP allowlist under Settings → Agents → Approvals & Execution, preserving existing entries.
  • GitHub Copilot CLI: start with copilot --allow-tool='cortex' to allow Cortex tools for that session. Use this command each time you start Copilot, including the verification session below.

These settings skip tool confirmations for Cortex. The agent can save useful knowledge and tell you what changed and why. The plugin's session instructions supply this workflow without requiring an AGENTS.md file. Instructions guide behavior but do not enforce it, and existing deny rules or organization policy may still require confirmation or block a tool. You can retain normal confirmations instead.

Current provider references: Codex MCP, Claude Code permissions, Cursor permissions, and Copilot CLI.

Verify the installation

Start a new session and ask:

Text
Use Cortex to list the Modules I can access. Make a real Cortex tool call; an empty list is valid. Separately, report whether this new conversation received persistent Cortex guidance and what it requires. Do not change anything.

Check both results: the coding agent makes a real Cortex call and returns the Module list, and the new session reports receiving Cortex guidance and explains what it requires. A new Account can return an empty list. If the connection works but guidance is missing, check that the SessionStart hook is trusted and enabled, then start another session. Tool access alone does not confirm that the instructions loaded.

Next step

Complete your first Cortex workflow.