Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.praison.ai/llms.txt

Use this file to discover all available pages before exploring further.

Linear tools provide comprehensive issue management capabilities through Linear’s GraphQL API, enabling agents to search, create, update, and comment on issues across teams.

​
Authentication

Linear tools support both OAuth tokens and personal API keys with automatic precedence: 
# Environment variables (recommended)
os.environ["LINEAR_OAUTH_TOKEN"] = "your-oauth-token"     # Takes precedence
os.environ["LINEAR_API_KEY"] = "your-personal-api-key"    # Fallback

# Or pass directly to agent
from praisonaiagents import Agent

agent = Agent(
    name="Linear Assistant",
    tools=["linear_search_issues", "linear_get_issue"],
    auto_approve_tools=True
)
OAuth tokens are sent as Bearer <token> while API keys are sent raw. OAuth tokens take precedence if both are configured.

​
Issue Management

​
linear_search_issues

Search Linear issues by text, status, team, or other criteria. Parameters:
  • query (str): Search query text
  • team_id (str, optional): Filter by specific team ID
  • state_id (str, optional): Filter by issue state
  • assignee_id (str, optional): Filter by assignee
  • limit (int, optional): Maximum results to return (default: 20)
Returns: List of issue objects with ID, title, description, status, and metadata. 
from praisonaiagents import Agent

agent = Agent(
    name="Issue Searcher",
    instructions="Help users find relevant Linear issues",
    tools=["linear_search_issues"]
)

# Agent can search like: "Find open bugs assigned to me"
result = agent.start("Find all high priority issues in the API team")

​
linear_get_issue

Get detailed information about a specific Linear issue. Parameters:
  • issue_id (str): Linear issue ID or identifier (e.g., “ENG-42”)
Returns: Complete issue object with title, description, comments, attachments, and relationships. 
from praisonaiagents import Agent

agent = Agent(
    name="Issue Reader",
    instructions="Analyze Linear issues and provide detailed summaries",
    tools=["linear_get_issue", "linear_search_issues"]
)

result = agent.start("Get details for issue ENG-42")

​
linear_add_comment

Add a comment to an existing Linear issue. Parameters:
  • issue_id (str): Issue ID to comment on
  • comment (str): Comment text (supports Markdown)
Returns: Created comment object with ID and URL. 
from praisonaiagents import Agent

agent = Agent(
    name="Progress Updater", 
    instructions="Provide status updates on Linear issues",
    tools=["linear_add_comment", "linear_get_issue"]
)

result = agent.start("Add a progress update to issue ENG-42")

​
linear_update_issue

Update issue properties like status, assignee, priority, or description. Parameters:
  • issue_id (str): Issue ID to update
  • title (str, optional): New issue title
  • description (str, optional): New description
  • state_id (str, optional): New state/status ID
  • assignee_id (str, optional): New assignee user ID
  • priority (int, optional): Priority level (1-4)
  • estimate (int, optional): Story point estimate
Returns: Updated issue object. 
from praisonaiagents import Agent

agent = Agent(
    name="Issue Manager",
    instructions="Manage Linear issue lifecycle and assignments", 
    tools=["linear_update_issue", "linear_list_issue_states"]
)

result = agent.start("Mark issue ENG-42 as completed")

​
Team and Workflow

​
linear_list_teams

Get all teams in the Linear workspace. Parameters: None Returns: List of team objects with IDs, names, and metadata. 
from praisonaiagents import Agent

agent = Agent(
    name="Team Explorer",
    instructions="Help users navigate Linear team structure",
    tools=["linear_list_teams", "linear_search_issues"]
)

result = agent.start("Show me all teams and their current workload")

​
linear_list_issue_states

Get available issue states for workflow management. Parameters:
  • team_id (str, optional): Filter states for specific team
Returns: List of state objects with IDs, names, colors, and workflow positions. 
from praisonaiagents import Agent

agent = Agent(
    name="Workflow Assistant",
    instructions="Help manage issue states and transitions",
    tools=["linear_list_issue_states", "linear_update_issue"]
)

result = agent.start("What are the available states for engineering issues?")

​
Complete Linear Agent Example

Here’s a comprehensive agent that combines multiple Linear tools: 
from praisonaiagents import Agent

linear_agent = Agent(
    name="Linear Project Manager",
    instructions="""
    You are a Linear project management assistant. You can:
    
    1. Search and analyze issues across teams
    2. Create detailed issue reports and summaries
    3. Update issue status and assignments
    4. Provide team workload insights
    5. Comment on issues with progress updates
    
    Always provide clear, actionable information and suggest next steps.
    """,
    llm="gpt-4o-mini",
    tools=[
        "linear_search_issues",
        "linear_get_issue", 
        "linear_add_comment",
        "linear_update_issue",
        "linear_list_teams",
        "linear_list_issue_states"
    ],
    memory=True,
    auto_approve_tools=True
)

# Example usage
result = linear_agent.start(
    "Find all high-priority bugs assigned to the API team and provide a summary"
)
print(result)

​
Integration with LinearBot

These tools work seamlessly with the LinearBot for automated issue management: 
from praisonaiagents import Agent
from praisonai.bots import LinearBot

# Create agent with Linear tools
agent = Agent(
    name="Autonomous Issue Manager",
    instructions="""
    When assigned or mentioned on Linear issues:
    1. Analyze the issue requirements
    2. Search for related issues or dependencies  
    3. Break down complex tasks into smaller issues
    4. Update status and add progress comments
    5. Coordinate with team members via comments
    """,
    tools=[
        "linear_search_issues", "linear_get_issue", "linear_add_comment",
        "linear_update_issue", "linear_list_teams", "linear_list_issue_states",
        "github_create_branch", "github_commit_and_push"
    ],
    memory=True,
    auto_approve_tools=True
)

# Connect to Linear via webhooks
bot = LinearBot(
    token=os.getenv("LINEAR_OAUTH_TOKEN"),
    signing_secret=os.getenv("LINEAR_WEBHOOK_SECRET"),
    agent=agent
)
Use Linear tools alongside the LinearBot for complete issue-to-code automation workflows.

​
Error Handling

Linear tools handle common API errors gracefully:
  • Authentication errors → Clear messages about token configuration
  • Rate limiting → Automatic retry with exponential backoff
  • Invalid IDs → Helpful suggestions for finding correct identifiers
  • Permission errors → Specific guidance on required scopes
# Tools will provide helpful error context
agent = Agent(
    name="Robust Linear Agent",
    instructions="Handle Linear API errors gracefully and guide users",
    tools=["linear_search_issues", "linear_get_issue"],
    auto_approve_tools=True
)

# Even with invalid input, get helpful responses
result = agent.start("Get issue INVALID-123")  # Will suggest search instead

Linear Bot

Webhook-based Linear integration

GitHub Tools

Combine with GitHub for complete workflows

Tool Profiles

Organize tools into reusable profiles

Agent Configuration

Agent setup and tool selection