How to Connect Linear to Codex With Aident Loadout

The safest way to connect Linear to Codex with Aident Loadout is to authorize Linear through Aident Vault, discover the current Linear Actions, inspect the exact Action schema and conservative risk metadata, and prove access with one bounded team-list request. Stop after the intended team appears. Do not create, update, comment on, assign, or archive an issue during the connection check.

This guide is for developers, product leads, and operators who want Codex to work with Linear without placing an API key in a prompt or giving the first task broad authority over a live workspace. A successful first check proves one connected account and returns the expected immutable team ID or key. It does not authorize a later issue mutation.

The safe Linear connection boundary

Connection and authorization are different decisions. OAuth proves which Linear account is connected. It does not prove that every visible workspace, team, project, or Action is in scope.

Prerequisites

You need:

• the installed public aident CLI;

• access to the intended Linear workspace;

• authority to approve its OAuth connection;

• one expected team name or key for the bounded check;

• a trusted local session for reviewing returned workspace metadata; and

• a human reviewer for any later Linear write.

Install or update Aident from the canonical guide:

Follow https://aident.ai/SETUP.md

Then confirm the current Aident identity and Vault inventory:

aident account auth status
aident vault vault --action status

Stop if the signed-in Aident account is not the intended one. Do not substitute a Linear personal API key, copied bearer token, or credential file. The credential-safety guide for AI agents explains why provider secrets should remain outside the agent conversation.

1. Discover the current Linear Action

Search by the job and target staging when the command supports it:

aident capabilities search \
  --targetEnv staging \
  --types '["action"]' \
  --query "Linear list teams without changing issues" \
  --limit 5

On September 3, 2026, the staging catalog returned version 4 of the active Linear List Teams Action. Its description says it retrieves teams with members and projects, supports pagination, and expects callers to use stable team IDs or keys rather than non-unique display names.

Copy the full canonical Action name from your own search result. Catalog versions and contracts can change. The same search surface exposes issue, project, state, label, cycle, comment, and mutation Actions; that breadth is useful later, but it is not permission to load or execute them during connection setup.

2. Inspect the exact Action contract

Load the selected metadata before connecting or executing:

aident capabilities get \
  --name "<current Linear team-list Action>"

Review all of these fields:

• required integration ID and connected account aliases;

• required and optional input fields, defaults, and bounds;

• output fields that may contain members or projects;

• pagination fields such as hasNextPage and endCursor;

• operation type and risk level; and

• pricing and credit behavior.

The inspected September 3 schema accepted first from 1 to 250, defaulted it to 50, and optionally accepted after and project_id. Its response can include teams, members, projects, and page information. That means even a team-list check may return more workspace data than the reader needs. Start with first: 5, review locally, and retain only the minimum team identity needed for the next step.

The live catalog conservatively marked this retrieval Action as operation type write and risk level 2. Do not silently relabel it read-only because its name begins with list. A read-shaped provider operation and a platform-enforced read-only credential scope are not the same thing. If a hard provider-enforced read-only boundary is the main requirement, compare Linear's official MCP route with Aident Loadout before proceeding.

3. Connect Linear through Aident Vault

If Vault does not show a ready Linear account, start the browser authorization flow with the exact integration ID returned by discovery:

aident vault vault \
  --action connect \
  --integrationId "<current Linear integration ID>"

Open the Aident-hosted URL, choose the intended Linear workspace and identity, and review the provider consent screen. Linear documents OAuth 2.0 for third-party applications and requires the redirect URI and requested scopes to match the registered application. The actual consent screen and current Aident integration contract are authoritative for the connection you are approving.

After consent, verify only that integration:

aident vault vault \
  --action status \
  --integrationId "<current Linear integration ID>"

Expected result: one ready connected user account. Stop if the account alias, provider identity, or workspace choice is unexpected. Do not replace an existing connection until its owner reviews the change.

4. Preflight the smallest verification

Validate the exact bounded input before executing it:

aident capabilities preflight \
  --name "<current Linear team-list Action>" \
  --input '{"first":5}'

In the September 3 contract check, this input was valid and the exact estimate was 0 Aident credits, or $0.00 at the returned conversion. Check your own result. If preflight rejects the input, reports an unavailable estimate outside your ceiling, or requires a risk acknowledgement, resolve that exact gate instead of bypassing Aident or guessing a different payload.

Preflight proves only that the selected input matches the current Aident contract and exposes the available price estimate. It does not prove that the connected Linear account is correct or that every returned team is in scope.

5. Verify Linear access without changing an issue

After the account, schema, metadata, and preflight are reviewed, execute only the inspected team-list Action:

aident capabilities execute \
  --name "<current Linear team-list Action>" \
  --input '{"first":5}'

Expected result: a successful response containing the intended team and stable team ID or key, plus pagination state. Do not paste the raw response into an issue, pull request, reusable prompt, or repository file because the Action can also return member and project data.

If the runtime requires an acknowledgement, confirm that the Action name and input are identical to the reviewed preflight before rerunning with --acknowledgementScope once. Do not use a persistent acknowledgement to turn a single connection check into standing approval.

Verify all of the following before continuing:

1. The intended team appears exactly once.

2. The returned team ID or key is retained for later exact targeting.

3. hasNextPage is understood; no silent full-workspace pagination ran.

4. No issue, project, state, label, comment, assignment, attachment, or cycle changed.

5. The selected Action, identical input, connected account alias, and result summary are preserved in the run record.

The first-party September 3 research stopped after schema inspection and a free preflight. It confirmed a ready Linear connection and a valid bounded request without reading or persisting customer workspace contents. Run the provider read only when the connected workspace and data handling boundary have been reviewed for your task.

6. Resolve immutable Linear IDs before any write

Names such as Engineering, In Progress, or Bug are not sufficient write targets. Teams, workflow states, labels, projects, users, cycles, and issues can be scoped differently and can share display names.

Before proposing a mutation:

1. Discover the current Action for the exact read or write job.

2. Inspect its live schema, risk, required account, output, and pricing.

3. Resolve the team first, then fetch team-scoped state and label IDs as needed.

4. Identify the issue by immutable ID and re-read its current state.

5. Produce a before-and-after patch without executing it.

6. Review the title, description, assignee, state, labels, priority, project, cycle, notifications, and rollback.

7. Preflight the exact mutation payload.

8. Execute only after a human approves that exact Action and input.

9. Read the issue back and compare the observed state with the approved patch.

Approval for a team list is not approval to create an issue. Approval for one issue comment is not approval to change its status, assignee, labels, or project.

A safe end-to-end prompt for Codex

Follow https://aident.ai/SETUP.md

Connect Linear through the installed public aident CLI. First run account auth
status and Vault status. Search the staging capability catalog for the current
Action that lists Linear teams. Inspect the exact schema, required integration,
connected account alias, operation type, risk, pagination, output fields, and
pricing. If no intended Linear account is connected, stop and return the Aident
Vault browser authorization URL. Do not accept or reveal a provider credential.

After the account is reviewed, preflight an input limited to five teams. Execute
only that identical Action and input after the risk and price are accepted.
Return the intended team name and immutable ID or key plus pagination state.
Do not create, update, assign, comment on, archive, or delete any Linear object.
Do not persist member, project, or provider payload details. Stop before any
issue read or mutation and show the next proposed Action and input for review

This prompt separates connection proof from later project work and names an observable success condition: one intended team with a stable identifier and no mutation.

Common Linear connection failures

Vault is ready, but the expected team is missing

Check the connected Linear identity, workspace membership, team visibility, and consent before reconnecting. A successful OAuth state does not mean the user can see every private team. Do not page through the whole workspace simply to find a team that may be outside the account's permissions.

The Action input is rejected

Reload the live Action metadata and use its current field names and bounds. Do not copy a dated payload or switch to a raw provider call. A catalog version may have changed after this article was published.

The Action returns too much data

Reduce first, stop pagination, and summarize only the approved team identity. The inspected response can include member and project objects. A connection test should not become a workspace export.

A write Action needs a team, state, or issue ID

Resolve the identifier with the current team-scoped read Action. Do not use a display name as an immutable target, and do not reuse a state ID from another team.

You need a hard read-only Linear boundary

Linear documents a dedicated read-only MCP endpoint and OAuth read scope. Use that provider-native route when a hard Linear-only read boundary is more important than a shared cross-application execution layer. The Linear MCP versus Aident Loadout comparison owns that selection decision; this page owns the Aident connection procedure.

Why this setup works

The sequence reduces four different risks independently:

• Vault keeps provider credentials out of prompts and repository files.

• Live discovery avoids stale Action names and unreviewed catalog breadth.

• Schema inspection and preflight make the exact input, risk metadata, and price visible before execution.

• A bounded team lookup creates an observable connection proof before any issue-level authority is considered.

This same control pattern can extend from Linear to GitHub, Slack, or another connected system. The guide to connecting Codex and Claude Code to real-world tools shows the wider multi-application pattern, while the AI agent approval workflow explains how to keep provider risk and spend approval separate.

The next step

Use one non-sensitive team to run the bounded verification. If it returns the intended immutable team identifier without changing any Linear object, the connection check is complete. Start a separate reviewed task for an issue read or mutation.

Connect Linear with a verified first read.

Sources

• Aident setup guide

• Aident: Linear MCP vs Aident Loadout for Codex

• Aident: Give AI Agents API Access Without Exposing Keys

• Linear OAuth 2.0 authentication

• Linear GraphQL API

• Linear pagination

• Linear API rate limits

• Linear MCP documentation

Refresh this guide when the Aident Linear Action version, required integration, schema, risk metadata, pricing, or Vault flow changes, or when Linear changes its OAuth scopes, API pagination, or official read-only MCP boundary.