How to Manage Linear Issues Through Codex: A Step-by-Step Guide

Codex provides a dedicated Linear skill that connects to the Linear MCP to create, update, and triage issues using natural language commands.

The ComposioHQ/awesome-codex-skills repository includes a fully specified Linear integration that turns conversational requests into concrete Linear API operations. By leveraging the Linear MCP (Managed Connect Platform), Codex guides users through a structured workflow to manage issues, projects, and teams without leaving the terminal.

Prerequisites and Setup

Before executing any Linear commands, you must configure the Linear MCP. According to linear/SKILL.md (lines 14-17), the MCP must be installed, enabled, and authenticated via OAuth.

Installing the Linear MCP

If the MCP is not present, Codex instructs you to add it using:

codex mcp add linear

Then enable the remote client and authenticate:

codex mcp login linear

This setup flow is documented in linear/SKILL.md (lines 22-33).

The Linear Workflow Architecture

The Linear skill implements a deliberate five-step workflow defined in linear/SKILL.md (lines 40-54). This structure ensures Codex collects required context before making mutating API calls.

Step 1 – Goal Clarification

Codex first asks what you want to achieve—whether triaging bugs, planning sprints, or auditing documentation. During this phase, the assistant gathers required identifiers such as team keys, project IDs, and issue IDs (lines 40-42).

Step 2 – Tool Selection

Based on your stated goal, Codex selects the appropriate MCP tools. The skill supports operations for issues, projects, teams, documents, comments, and cycles (lines 44-46).

Step 3 – Batch Execution

Reads execute first to build context, followed by creates and updates issued in logical groups. The skill explicitly separates read operations from write operations to prevent accidental mutations (lines 47-50).

Step 4 – Result Summarization

Codex returns a concise summary of changes, flags any remaining gaps in the data, and proposes next actions (lines 52-54).

Available Toolset and Operations

The complete list of available tools is enumerated in linear/SKILL.md (lines 55-62). These include:

• list and get operations for issues, projects, teams, documents, comments, and cycles
• create and update operations for the same entities

Specific workflows such as Sprint Planning, Bug Triage, and Documentation Audit provide concrete templates in lines 63-73.

Practical Code Examples

The following examples demonstrate the read-first, then-write pattern recommended in the skill specification.

List open bugs for a specific team:

# Example 1 – List open bugs for a specific team

codex execute linear --list_issues \
    --filter '{"team":{"key":"ENG"},"state":{"type":"unstarted"},"label":["bug"]}'

Create a new issue in a specific sprint:

# Example 2 – Create a new issue in the "Q2 Planning" sprint

codex execute linear --create_issue \
    --payload '{"title":"Add dark‑mode toggle","teamKey":"ENG","projectId":"proj_ABC","cycleId":"cycle_123","labels":["feature","ui"]}'

Update and assign high-priority bugs:

# Example 3 – Move high‑priority bugs to “In Progress” and assign them

codex execute linear --update_issue \
    --filter '{"label":["bug"],"priority":"high","state":{"type":"unstarted"}}' \
    --payload '{"stateId":"state_in_progress","assigneeId":"user_456"}'

Integration with Broader Workflows

For teams using multiple issue trackers, the issue-triage/SKILL.md file demonstrates how Linear integrates with broader triage workflows, including cross-tool synchronization with Jira or Sentry. The repository-level README.md provides the master index linking to these components.

Summary

• Install and authenticate the Linear MCP using codex mcp add linear and codex mcp login linear before executing commands.
• The workflow follows five distinct phases: Setup, Goal Clarification, Tool Selection, Batch Execution, and Result Summarization.
• Available operations cover full CRUD functionality for issues, projects, teams, documents, comments, and cycles.
• Codex enforces a read-before-write pattern to prevent accidental data mutations.
• Reference linear/SKILL.md for the complete specification and practical workflow templates like Sprint Planning and Bug Triage.

Frequently Asked Questions

What is the Linear MCP in Codex?

The Linear MCP (Managed Connect Platform) is the connection layer that allows Codex to communicate with Linear's API. It must be installed and authenticated via OAuth before any issue management commands can execute, as specified in linear/SKILL.md (lines 14-17).

How does Codex prevent accidental changes to Linear issues?

Codex implements a structured workflow that performs all read operations before any writes. According to linear/SKILL.md (lines 47-50), the model builds context through reads first, then groups mutations logically, explaining bulk operations before executing them.

Can I manage multiple Linear projects simultaneously through Codex?

Yes. The toolset supports cross-project operations. You can specify different projectId values in your payloads or filters, and the Batch Execution phase (lines 47-50) handles multiple updates in logical groups.

Where can I find templates for common Linear workflows?

Practical workflow templates including Sprint Planning, Bug Triage, and Documentation Audit are documented in linear/SKILL.md (lines 63-73). For integrations with other tools like Jira or Sentry, see issue-triage/SKILL.md.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}