Skip to content

Commit a368c8d

Browse files
NathanFlurryNathanFlurry
authored
feat: linear-coding-agent example (#933)
1 parent 24abf65 commit a368c8d

File tree

16 files changed

+4031
-13
lines changed

16 files changed

+4031
-13
lines changed

‎examples/linear-coding-agent/.env.example

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# GitHub Configuration
2+
GITHUB_TOKEN=your_github_token
3+
REPO_OWNER=your_github_username_or_organization
4+
REPO_NAME=your_repository_name
5+
BASE_BRANCH=main
6+
7+
# Linear Configuration
8+
LINEAR_API_KEY=your_linear_api_key
9+
LINEAR_WEBHOOK_SECRET=your_linear_webhook_signing_secret
10+
11+
# OpenAI Configuration
12+
OPENAI_API_KEY=your_openai_api_key
13+
14+
# Server Configuration
15+
PORT=3000
16+
ACTOR_SERVER_URL=http://localhost:8787

‎examples/linear-coding-agent/.gitignore

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,2 @@
1+
.actorcore
2+
node_modules

‎examples/linear-coding-agent/README.md

Lines changed: 228 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,228 @@
1+
# Linear AI Agent with GitHub Integration
2+
3+
This project implements an AI agent that automatically manages GitHub code changes based on Linear issues. The agent handles the full development workflow from issue creation to PR merging.
4+
5+
## Features
6+
7+
- **Issue-Driven Development**:
8+
- When an issue is created in Linear, the agent creates a branch and PR automatically
9+
- Uses LLM to analyze and implement the required changes
10+
- Links PRs back to Linear issues
11+
12+
- **Continuous Feedback Loop**:
13+
- Responds to comments on Linear issues by making additional code changes
14+
- Updates the PR with the new changes
15+
- Provides detailed summaries of changes made
16+
17+
- **End-to-End Workflow**:
18+
- Handles Linear issue status transitions
19+
- Merges or closes PRs based on issue status changes
20+
- Maintains consistency between GitHub PRs and Linear issues
21+
22+
## Getting Started
23+
24+
### Prerequisites
25+
26+
- Node.js (v18 or later)
27+
- GitHub repository access
28+
- Linear workspace
29+
- Anthropic API key (for Claude)
30+
31+
### Installation
32+
33+
1. Clone this repository
34+
2. Install dependencies:
35+
```
36+
npm install
37+
```
38+
3. Copy the environment variables:
39+
```
40+
cp .env.example .env
41+
```
42+
4. Fill in your configuration details in the `.env` file
43+
44+
### Running the Agent
45+
46+
You can run the agent in several ways:
47+
48+
#### Option 1: Running Everything at Once
49+
50+
Using concurrently to run both the actor server and webhook server:
51+
52+
```
53+
npm run start
54+
```
55+
56+
To also expose your local server to the internet via ngrok:
57+
58+
```
59+
npm run start:ngrok
60+
```
61+
62+
The ngrok URL can be used to configure a Linear webhook.
63+
64+
#### Option 2: Running Services Separately
65+
66+
##### Starting the Actor Core Server
67+
68+
This starts the ActorCore server that hosts the coding agent:
69+
70+
```
71+
npm run dev
72+
# Or using the ActorCore CLI
73+
npx @actor-core/cli dev src/actors/app.ts
74+
```
75+
76+
##### Running the Webhook Server (for Linear integration)
77+
78+
In a separate terminal, run the HTTP server that receives Linear webhooks and forwards them to the agent:
79+
80+
```
81+
npm run server
82+
```
83+
84+
The webhook server will be available at:
85+
- HTTP endpoint for Linear webhooks: `http://localhost:3000/api/webhook/linear`
86+
- Queue status endpoint: `http://localhost:3000/api/queue/:issueId`
87+
- Health check: `http://localhost:3000/health`
88+
89+
The webhook endpoint includes signature verification for added security. When configuring your Linear webhook, make sure to:
90+
1. Copy the webhook secret provided by Linear
91+
2. Add it to your `.env` file as `LINEAR_WEBHOOK_SECRET`
92+
93+
#### Monitoring and Debugging
94+
95+
The agent provides several API endpoints for monitoring and debugging:
96+
97+
##### Queue Status API
98+
99+
Check the status of the request queue for a specific issue:
100+
101+
```bash
102+
# Replace ISSUE-ID with your Linear issue ID
103+
curl http://localhost:8080/api/queue/ISSUE-ID
104+
```
105+
106+
This returns details about the queue including:
107+
- Number of pending, processing, completed, and failed requests
108+
- Whether the queue is currently being processed
109+
- Timestamp of the last processed request
110+
111+
##### Debug Information API
112+
113+
Get detailed debug information about a specific issue:
114+
115+
```bash
116+
# Replace ISSUE-ID with your Linear issue ID
117+
curl http://localhost:8080/api/debug/ISSUE-ID
118+
```
119+
120+
This provides comprehensive debug information including:
121+
- Current operation and processing stage
122+
- Queue status and statistics
123+
- Linear issue details
124+
- GitHub repository and branch information
125+
- Code changes and modifications
126+
- LLM processing status
127+
- Actor metadata
128+
129+
##### LLM Conversation History API
130+
131+
View the complete conversation history with the LLM for a specific issue:
132+
133+
```bash
134+
# Replace ISSUE-ID with your Linear issue ID
135+
curl http://localhost:8080/api/history/ISSUE-ID
136+
```
137+
138+
This returns the full sequence of messages exchanged with the LLM, including:
139+
- System prompts
140+
- User messages
141+
- Assistant responses
142+
- Tool invocations and results
143+
144+
##### Exposing Webhooks to the Internet (for Linear integration)
145+
146+
To expose your local webhook server to the internet:
147+
148+
```
149+
npm run ngrok
150+
```
151+
152+
#### Local Testing
153+
154+
For local testing without actual webhooks, you can use the debugging CLI tools:
155+
156+
```bash
157+
# Check the status of a specific issue
158+
yarn cli status <ISSUE-ID>
159+
160+
# Get debug information for a specific issue
161+
yarn cli debug <ISSUE-ID>
162+
163+
# View conversation history with the LLM
164+
yarn cli history <ISSUE-ID>
165+
```
166+
167+
This allows you to monitor and debug the agent's behavior for specific issues.
168+
169+
### Configuration
170+
171+
Set the following environment variables:
172+
173+
- `GITHUB_TOKEN`: GitHub Personal Access Token
174+
- `REPO_OWNER`: GitHub username or organization
175+
- `REPO_NAME`: Repository name
176+
- `BASE_BRANCH`: Base branch name (defaults to 'main')
177+
- `LINEAR_API_KEY`: Linear API Key
178+
- `ANTHROPIC_API_KEY`: Anthropic API Key
179+
180+
## Architecture
181+
182+
The agent is built using the ActorCore framework and consists of:
183+
184+
- **Coding Agent**: Main actor that handles Linear webhook events
185+
- **GitHub Integration**: API client for branch, PR, and file operations
186+
- **Linear Integration**: API client for issue management
187+
- **LLM Service**: Integration with Anthropic Claude for code generation
188+
- **Request Queue**: Durable, persistent queue for processing Linear events
189+
190+
### Request Queue System
191+
192+
The agent implements a durable queue system to ensure reliable processing of Linear events:
193+
194+
- All incoming requests (issue creation, comments, updates) are added to a persistent queue
195+
- The queue is processed asynchronously, with each request handled in order
196+
- If the agent crashes or restarts, it automatically resumes processing pending requests
197+
- Request status is tracked (pending, processing, completed, failed) and can be monitored via API
198+
- Each request has a unique ID for tracking and correlation
199+
200+
This ensures that even during high load or if the agent experiences issues, no webhook events are lost and all will eventually be processed.
201+
202+
## Workflow
203+
204+
1. **On Issue Creation**:
205+
- Create a new branch
206+
- Use LLM to implement changes
207+
- Create a PR linked to the Linear issue
208+
- Update issue status to "In Review"
209+
210+
2. **On Issue Comment**:
211+
- Update existing branch with new changes
212+
- Push changes to the PR
213+
- Comment with summary of changes
214+
215+
3. **On Issue Status Change**:
216+
- If "Done": Merge the PR
217+
- If "Canceled": Close the PR
218+
- For other statuses: Maintain consistency
219+
220+
## Development
221+
222+
For local development, use:
223+
224+
```
225+
npm run check-types # Type checking
226+
npm run test # Run tests
227+
```
228+

‎examples/linear-coding-agent/package.json

Lines changed: 44 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,44 @@
1+
{
2+
"name": "linear-coding-agent",
3+
"version": "0.8.0",
4+
"private": true,
5+
"type": "module",
6+
"scripts": {
7+
"dev": "concurrently --raw \"yarn dev:actors\" \"yarn dev:server\" \"yarn dev:ngrok\"",
8+
"dev:actors": "npx @actor-core/cli@latest dev src/actors/app.ts",
9+
"dev:server": "tsx --watch src/server/index.ts",
10+
"dev:ngrok": "ngrok http 3000",
11+
"check-types": "tsc --noEmit"
12+
},
13+
"devDependencies": {
14+
"@actor-core/cli": "workspace:*",
15+
"@types/dotenv": "^8.2.3",
16+
"@types/express": "^5",
17+
"@types/node": "^22.13.9",
18+
"@types/prompts": "^2",
19+
"actor-core": "workspace:*",
20+
"concurrently": "^9.1.2",
21+
"prompts": "^2.4.2",
22+
"tsx": "^3.12.7",
23+
"typescript": "^5.5.2",
24+
"vitest": "^3.1.1"
25+
},
26+
"dependencies": {
27+
"@ai-sdk/anthropic": "^1.2.10",
28+
"@hono/node-server": "^1.14.1",
29+
"@linear/sdk": "^7.0.0",
30+
"@octokit/rest": "^19.0.13",
31+
"ai": "^4.3.9",
32+
"body-parser": "^2.2.0",
33+
"dotenv": "^16.5.0",
34+
"express": "^5.1.0",
35+
"hono": "^4.7.7",
36+
"linear-webhook": "^0.1.3",
37+
"zod": "^3.24.3"
38+
},
39+
"example": {
40+
"platforms": [
41+
"*"
42+
]
43+
}
44+
}

‎examples/linear-coding-agent/src/actors/app.ts

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,14 @@
1+
import { setup } from "actor-core";
2+
import dotenv from "dotenv";
3+
import { codingAgent } from "./coding-agent/mod";
4+
5+
// Load environment variables from .env file
6+
dotenv.config();
7+
8+
// Create and export the app
9+
export const app = setup({
10+
actors: { codingAgent },
11+
});
12+
13+
// Export type for client type checking
14+
export type App = typeof app;

0 commit comments

Comments
 (0)