Skip to content

About

Self-hosted, unofficial Claude Code agent for your Linear workspace: delegate issues to Claude Code on the web sessions on each person's own Claude account

Resources

Stars

0 stars

Watchers

0 watching

Forks

 
 

Repository files navigation

Claude Code Linear Agent (unofficial)

A self-hosted Linear agent for your own workspace. Delegate a Linear issue to Claude Code, and a Claude Code on the web session starts on the delegating person's own Claude account. The session works in your repository and opens a pull request as that person. Its plan, progress and result appear in the issue's agent session, the way Linear's built-in agents do.

An unofficial integration, not made or supported by Anthropic or Linear. It relies on the Claude Code routines fire API, which is experimental.

How it works

Linear issue delegated to "Claude Code"
  -> AgentSessionEvent webhook  -> this app (Vercel)
  -> fires the delegator's Claude Code routine (scheduled task) over its API trigger
  -> cloud session clones your repo, does the work, opens a PR
  -> session curls progress back to /api/runs/<id>/events
  -> app relays it to Linear as plan updates, thoughts, actions, PR link, final response
  • Per-user accounts. Everyone connects their own Claude account at /connect: a read-only Linear sign-in, then the fire URL and token of a Claude Code task they create. Tokens are stored AES-256-GCM encrypted.
  • Follow-ups in the same session. A reply in the issue's agent thread reaches the same session. A running session gets it with its next progress report. A finished session keeps long-polling /api/runs/<id>/wait for IDLE_WINDOW_MINUTES (default 60), so it answers with full context. After that, a reply starts a continuation session that carries the earlier conversation. Chatting with the session directly in claude.ai also works: its reports reopen the run.
  • Stop. Linear's Stop makes the next callback return stop/410, and the session halts.
  • Watchdog. A cron job posts a note when a session goes quiet (for example, while it waits on an approval) and gives up after 2 hours.
  • Pull requests.
    • Branches are named feat/<issue>-… or fix/<issue>-….
    • PRs target DEFAULT_BASE_BRANCH and carry a Fixes <ID> line, so Linear's GitHub integration links them.
    • The "Generated by Claude Code" footer is stripped.
  • Issue status. Delegating moves the issue to the team's first started state.

What you need

  • Vercel: a project on the Pro plan. The watchdog cron runs every 5 minutes, and Hobby only allows daily crons.
  • Upstash Redis: from the Vercel Marketplace.
  • Linear: workspace admin rights, to create a private OAuth app.
  • Claude: each user needs a Pro, Max, Team or Enterprise plan with Claude Code on the web and GitHub connected. On Team or Enterprise, an Owner must enable scheduled tasks (routines).

Quick start: let your coding agent set it up

Clone the repo and open your coding agent in it:

git clone https://github.com/nerdimite/claude-code-linear-agent.git
cd claude-code-linear-agent
claude

Then paste this prompt:

Set up this repository end to end with the setup-claude-linear-agent skill
(.claude/skills/setup-claude-linear-agent/SKILL.md). Do every step yourself: install what's missing,
deploy to Vercel, add Upstash Redis, generate the secrets, create the Linear OAuth app with
its icon, store the app token, create my Claude Code task on claude.ai, connect it at /connect
and run the connection test. Use a browser tool for Linear and claude.ai if you have one
(Claude in Chrome first, where I'm already signed in). Ask me everything you need in one go,
get my OK once before creating anything, and stop only for steps a human must do.

The skill does each phase, checks what's already done first (so you can rerun it to resume), and keeps every secret in a gitignored .env. It's written for Claude Code, but any agent that can read the skill file and run shell commands can follow it.

What you'll still do by hand:

  • sign in to Vercel, Linear (as a workspace admin) and claude.ai
  • accept the Upstash marketplace terms once
  • without a browser tool, the Linear and claude.ai forms (the agent gives you the exact values)

Adding a teammate: they open <your-app>/connect and follow the page, or ask their agent to "run the setup-claude-linear-agent skill in connect mode for <your-app>".

Doing it by hand: follow SETUP.md. It also lists every problem found while building this, with fixes.

Configuration

Variable Purpose
PUBLIC_BASE_URL Production URL, with no trailing slash. It must be a stable public host.
LINEAR_CLIENT_ID, LINEAR_CLIENT_SECRET, LINEAR_WEBHOOK_SECRET The Linear OAuth app
BOT_SIGNING_SECRET Signs per-run callback tokens, OAuth state and session cookies
TOKEN_ENCRYPTION_KEY Encrypts stored routine tokens
CRON_SECRET Authenticates Vercel cron calls
KV_REST_API_URL, KV_REST_API_TOKEN Upstash Redis, set by the integration
DEFAULT_REPOSITORY Repo sessions work in by default, for example your-org/your-repo
DEFAULT_BASE_BRANCH Base branch for that repo's PRs (default main)
IDLE_WINDOW_MINUTES How long a finished session waits for same-session follow-ups (default 60; 0 turns it off)
WAIT_SECONDS How long each wait call holds (default 100, under Claude Code's 2-minute Bash timeout)
ROUTINES_JSON Optional admin fallback: {"<linear-user-id>": {"fireUrl", "token"}}

Development

bun run dev        # http://localhost:3000
bun run test       # vitest
bun run typecheck
bun run deploy -- <vercel-scope>   # deploys HEAD with no git metadata attached

The session-to-app callback leg only works against the deployed host. The cloud session's auto-mode safety check blocks POSTs to tunnels and other unnamed hosts.

Limits

These come from the routines API:

  • One-way: the API can start a session, but can't read, message or cancel one. Everything here works around that through the callback and wait protocol.
  • Rate limits: 30 starts per hour per routine, and 100 per hour per account.
  • Session titles: every session is titled after the routine's name.

License

MIT. See LICENSE.

About

Self-hosted, unofficial Claude Code agent for your Linear workspace: delegate issues to Claude Code on the web sessions on each person's own Claude account

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages