Linear Integration

Overview

Linear is a first-class execution surface for Praxiom AI. Beyond OAuth + recommendation push, the agent has nine tools for live querying and writing — it can answer "what's Alex working on this sprint?" by querying the Linear GraphQL API directly, surface duplicates before creating a new issue, and push state/assignee/cycle updates through the HITL approval layer.

Connecting

POST /api/integrations/linear/connect

{ "workspace_id": "your-workspace-uuid" }

GET /api/integrations/linear/teams?workspace_id={id}

POST /api/integrations/linear/teams/select

{
  "workspace_id": "your-workspace-uuid",
  "team_id": "team-uuid",
  "team_name": "Engineering",
  "project_id": "optional-project-uuid",
  "project_name": "Onboarding rewrite"
}

Agent Tools

All nine tools live in app/core/sdk/tools/integration.py. Four tools are @gated — they queue in pending actions rather than executing immediately.

Error shape

Tools translate LinearServiceError into structured responses:

{
  "success": false,
  "error": "No user matched 'alx'. Ask the user to clarify.",
  "error_code": "user_not_found"
}

Common error_code values: integration_not_connected, no_team_selected, not_found, validation_error, user_not_found, project_not_found, label_not_found, no_active_cycle, rate_limited, token_expired.

Cycle resolution

query_linear_issues and update_linear_issue both accept cycle as a string. The handler resolves:

• "active" → the current cycle for the selected team (via service.get_active_cycle(team_id)). If there's no active cycle, query_linear_issues returns an empty list with a friendly message.
• "none" (only update_linear_issue) → unset the cycle.
• any other value → treated as a cycle UUID.

Creating Issues (API)

POST /api/integrations/linear/issues

{
  "workspace_id": "your-workspace-uuid",
  "recommendation_id": "rec-uuid",
  "title": "Improve onboarding flow",
  "body": "Based on user research...",
  "project_id": "optional-project-id",
  "label_ids": ["label-id-1"],
  "priority": 2
}

Requires a selected team (else NO_TEAM_SELECTED). Falls back to selected_project_id from config if project_id is omitted. Returns issue_url, issue_identifier (e.g. ENG-42), and link_id. Persists a RecommendationLinearLink with the issue's current state + state type for sync.

Status Sync

POST /api/integrations/linear/sync

For every link in the workspace, calls LinearService.get_issue and refreshes linear_issue_state + linear_issue_state_type. When state_type transitions to completed or cancelled, the linked Recommendation.status is updated to implemented (unless already implemented or rejected).

Response: { synced_count, updated_count }.

Management Endpoints

Key Concepts

• Name-based resolution — agents work in human names ("Alex", "In Progress", "Onboarding") and the tool resolves them to Linear IDs server-side. If resolution fails, the agent gets a structured error with the available set.
• HITL on every write — create_linear_issue, update_linear_issue, create_linear_comment, plus recommendation-sourced issue creation go through pending actions. The preview captures the intended change set (field + new value) before execution.
• Read tools are free — query_linear_issues, search_linear_issues, get_linear_cycle, get_linear_project, get_linear_issue, list_linear_issues all run immediately with no user approval. Use them liberally to ground recommendations in the current team state.
• Priority mapping — the API matches Linear's native integer scheme (0=none, 1=urgent, 2=high, 3=medium, 4=low). The execution-ticket pipeline maps Praxiom's P0/P1/P2/P3 to 1/2/3/4.

What's Next

• GitHub Integration — 7 read tools for grounding in code.
• Pending Actions — how @gated write tools queue for approval.
• Execution Tickets — bulk push a whole spec, priority-mapped, to Linear.