Docs

Linear

Connect FlyDocs to Linear for automated issue management and project tracking.

FlyDocs connects to Linear through an active skill, a set of Python scripts that call the Linear GraphQL API directly. No MCP server, no running process. The AI runs deterministic scripts and gets structured JSON back.

This integration powers the full workflow lifecycle: creating issues, transitioning statuses, adding comments, assigning work, and querying your backlog, all from within your AI coding session.

Setup

1. Add your API key

Generate a personal API key from Linear Settings → API, then add it to your environment:

.env 
LINEAR_API_KEY=lin_api_xxxxx

Store this in .env or .env.local. Neither is committed to git. FlyDocs adds them to .gitignore during setup.

2. Configure the provider

The provider section in .flydocs/config.json maps your Linear team and project:

.flydocs/config.json 
{
  "tier": "cloud",
  "provider": {
    "type": "linear",
    "teamId": "your-team-uuid"
  },
  "workspace": {
    "activeProjects": ["project-uuid"],
    "product": {
      "name": "My Product",
      "labelIds": ["label-uuid"]
    }
  },
  "statusMapping": {
    "BACKLOG": "Backlog",
    "READY": "Todo",
    "IMPLEMENTING": "In Progress",
    "BLOCKED": "On Hold",
    "REVIEW": "Internal Review",
    "TESTING": "QA",
    "COMPLETE": "Done"
  }
}

The teamId is a UUID, not the URL slug you see in Linear's interface. FlyDocs detects it automatically during cloud setup. The statusMapping translates FlyDocs' internal lifecycle stages to your Linear workflow's actual status names.

Available Operations

All scripts live in .claude/skills/flydocs-cloud/scripts/ and follow the same contract: exit 0 with JSON on stdout for success, exit 1 with an error message on stderr for failure.

Script Purpose
create_issue.py Create a new issue with title, type, priority, estimate
transition.py Move an issue to a new status with a required comment
comment.py Add a comment to an existing issue
list_issues.py List issues filtered by status, assignee, or activity
get_issue.py Get full details for a specific issue
assign.py Assign an issue to a team member
update_description.py Update an issue's description (where acceptance criteria live)
update_issue.py Update priority, estimate, assignee, or state in one call

Example Script Calls

Create an issue

Terminal 
python3 .claude/skills/flydocs-cloud/scripts/create_issue.py \
  --title "Add user avatar upload" \
  --type feature \
  --priority 2 \
  --estimate 3

Transition an issue

Every status transition requires a comment. No silent moves. This is enforced by the script, not just convention.

Terminal 
python3 .claude/skills/flydocs-cloud/scripts/transition.py \
  ENG-123 REVIEW "Ready for review — all acceptance criteria met"

List active issues

Terminal 
python3 .claude/skills/flydocs-cloud/scripts/list_issues.py \
  --status IMPLEMENTING,REVIEW --mine

Add a comment

Terminal 
python3 .claude/skills/flydocs-cloud/scripts/comment.py \
  ENG-123 "Discovered edge case with empty arrays — adding validation"

How It Works

The Linear integration is implemented as an active skill, part of the cloud mechanism. The workflow skill references scripts by name ("call transition.py to move to Review") without knowing the implementation details. The mechanism skill provides those scripts.

Scripts authenticate using the LINEAR_API_KEY environment variable and call Linear's GraphQL API directly. They read team ID, project scope, and status mappings from .flydocs/config.json. Network errors are retried with exponential backoff (3 retries, 2-second base delay).

Extended Operations

Beyond the core issue operations, the cloud mechanism includes scripts for broader project management:

  • project_update.py: Post a project health update (used during session wrap)
  • estimate.py / priority.py: Set estimate or priority directly
  • link.py: Link related issues together
  • assign_cycle.py / list_cycles.py: Manage Linear cycles
  • assign_milestone.py / list_milestones.py: Manage milestones

Future: Relay API

The current implementation calls Linear's API directly from your machine. The relay API (in development) will route these calls through app.flydocs.ai, adding team-level permissions, audit logging, and support for additional providers (Jira, GitHub Issues). The script interface stays the same. Only the transport changes.

Related