Introduction

Managing project tasks often feels like a constant battle against context switching. Developers and product managers frequently jump between chat applications and issue trackers, losing focus and momentum. Linear Agent is an open-source chat-based assistant that integrates directly with your Linear account, allowing you to manage tasks through natural language conversations without leaving your current workflow. Built as a reference implementation for LangGraph best practices, it transforms the way teams interact with their project management data by turning conversations into actionable tickets.

What Is Linear Agent?

Linear Agent is a chat-based assistant that manages tasks for Linear users by leveraging an LLM-powered interface. It is written in Python and licensed under the MIT License, allowing users to create, update, and query their Linear workspace data through a conversational interface. The project serves as both a functional tool for productivity and a high-quality reference implementation for developers looking to build complex agentic workflows using LangGraph.

The tool integrates the Linear API with a conversational front-end, meaning users can simply state their needs—such as “Create a task to fix the login bug”—and the agent handles the API calls to the Linear workspace. It is designed to eliminate the “I’ll add that to Linear later” moments that often lead to forgotten tasks.

Why Linear Agent Matters

Traditional project management requires users to interrupt their workflow, navigate to a separate application, fill out forms, and switch contexts completely. This is a massive productivity killer for high-velocity engineering teams. Linear Agent solves this by bringing the task management interface into the conversation, allowing the user to stay in their flow state.

Beyond its utility as a tool, the project’s significance lies in its architecture. By using LangGraph, it demonstrates how to design clean, maintainable graph-based workflows. It provides a real-world example of how to separate specialized nodes with clear responsibilities, manage conversation state, and manage intelligent routing between workflow steps. For developers, this makes Linear Agent a valuable learning resource for building reliable AI agents.

As AI agents move from simple chatbots to “artificial teammates,” Linear Agent provides a bridge between the two, showing how a specialized agent can act on a user’s behalf to maintain a clean and accurate project board.

Key Features

• Natural Language Task Creation: Users can create Linear tickets directly from chat messages. The agent understands the intent and maps it to the required Linear API parameters.
• Real-Time Workspace Querying: The agent can check the status of tasks, list current assignments, and provide updates on what teammates are working on without the user needing to open the Linear app.
• Conversation Memory: Using Chroma as a vector store, the agent maintains context over time, remembering previous discussions and referring back to them in subsequent interactions.
• LangGraph Orchestration: The entire conversation flow is managed by a stateful graph, ensuring that the agent follows a logical sequence of steps to resolve a user’s request.
• Customizable LLM Integration: While it defaults to Google Generative AI, the architecture allows for easy swapping of the underlying language model to fit team preferences.
• Reference Implementation: The codebase is structured to showcase optimal graph structure, proper node separation, and robust state management patterns for agentic applications.

How Linear Agent Compares

Linear Agent differs from the native AI features provided by Linear because it is a standalone, open-source implementation. While Linear’s own AI agents are integrated into the workspace, Linear Agent allows developers to own the infrastructure, choose their own LLM, and customize the logic of how tasks are managed. This is particularly useful for teams that require strict control over their data flow or those who want to build their own specialized internal tools on top of the Linear API.

Compared to enterprise tools like Jira AI, Linear Agent is significantly more lightweight and focused on the developer experience. It avoids the bloat of enterprise project management and focuses on the core loop of creating and querying tasks. For teams already using Linear, this open-source agent provides the way to extend the platform’s capabilities without being locked into a specific vendor’s AI implementation.

Getting Started: Installation

To install Linear Agent, you will need Python 3.9 or higher. Ensure you have a Linear API key and a Google Generative AI API key.

Prerequisites

• Python 3.9+
• Linear API Key
• Google API Key (for Gemini)

Local Installation

Clone the repository and set up your environment:

git clone https://github.com/maxxxara/linear-agent.git
cd linear-agent
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -r requirements.txt

Configuration

Create a .env file in the root directory and add your credentials:

LINEAR_API_KEY=your_linear_api_key
LINEAR_TEAM_NAME=your_team_name
GOOGLE_API_KEY=your_google_api_key

Launching the Agent

Run the Streamlit interface to start chatting with your workspace:

python run_streamlit.py

How to Use Linear Agent

Once the Streamlit app is running, you can interact with the agent using natural language. The simplest way to start is by asking the agent to create a task for you. For example, try typing: "Create a task to update the API documentation". The agent will process this request, call the Linear API, and confirm the creation of the ticket.

You can also use the agent to get a snapshot of your current workload. Try asking: "What are my tasks for today?". The agent will query your Linear workspace, filter for tasks assigned to me, and return a list of in-progress and todo tasks. This workflow allows you to stay in the chat interface while keeping your project board up to date.

The agent’s memory system allows for iterative refinement. If the agent creates a task and asks if you want to assign it to someone, you can simply reply "Yes, assign it to Alex". The agent remembers the context of the current ticket and performs the update without you needing to re-specify the ticket ID.

Code Examples

The core logic of Linear Agent is found in the src/graph/ directory. The project uses LangGraph to define the workflow. Here is how the agent’s state is managed:

# Example of state management in state.py
from typing import TypedDict, Annotated
from langgraph.graph import add_messages

class AgentState(TypedDict):
    messages: Annotated[list, add_messages]

This state object is passed between nodes in the graph, allowing the agent to maintain a history of the conversation and the results of API calls. The individual nodes in nodes.py handle the specific logic for interacting with the Linear API and the LLM.

Another key example is the Linear API module in src/modules/linear/, which abstracts the the API calls to Linear’s GraphQL API. The agent uses these modules to perform actions like creating issues and fetching user tasks.

Real-World Use Cases

• Rapid Ticket Entry: A product manager during a meeting can quickly type "Add a bug report for the CSS layout on mobile" into the chat, ensuring the task is captured immediately without interrupting the meeting flow.
• Bailout Standup Preparation: A developer can ask "What is my current status on the API refactor?" to quickly get a summary of their assigned tasks and their status, preparing for a standup meeting without navigating through multiple Linear projects.
• Teammate Coordination: A lead engineer can ask "What is Alex working on right now?" to identify potential blockers or overlap in work across the team, providing a quick visibility layer over the Linear workspace.
• Contextual Task Refinement: After a long discussion about a feature, a user can say "Create a ticket based on our last three messages", leveraging the agent’s memory to synthesize a ticket description from the conversation history.

Contributing to Linear Agent

Linear Agent is an open-source project and welcomes contributions from the community. If you find a bug or want to add a feature, the standard GitHub flow is used. You can report bugs by opening an issue in the repository. To contribute code, fork the repository, create a feature branch, make your changes, and submit a pull request.

The project maintains an MIT license, meaning contributions are encouraged to encourage the rest of the community to build more specialized agents for other project management tools.

Community and Support

Support for Linear Agent is primarily handled through GitHub. For those looking to build their own agents, the project recommends referring to the LangGraph guides and Streamlit tutorials for the rest of the stack.

The community is active in the GitHub Discussions and Issues sections, where users can share their implementation details or report problems with the Linear API integration.

Conclusion

Linear Agent provides a powerful way to reduce the friction of task management by bringing the interface into the chat. For teams that value speed and minimalism, it is an ideal tool for ensuring that no task is forgotten and that project boards remain accurate. It is also a high-quality reference for anyone wanting to learn how to build reliable AI agents using LangGraph.

If you are a developer looking to improve your team’s productivity or a student of agentic AI, we recommend starring the repository, trying the quickstart guide, and exploring the codebase to see how LangGraph is implemented in a real-world scenario.

Resources

• Linear Agent GitHub Repository
• Linear API Documentation
• LangGraph Documentation
• Streamlit Documentation