How do I get Claude Code to ship docs updates from tickets in a Linear project?

Tares keeps a Linear project’s issues as a project’s tickets, so you write docs updates as issues and the crew builds them into merged pull requests. Link the Linear project once, and Tares reads each issue’s title, status, order, identifier, milestone and blockers about once a minute. Builders work the tickets one at a time, the reviewer checks every pull request, and nothing merges until it passes.

How it works

A docs update is a ticket like any other. The software factory for Claude Code is a crew of Claude Code sessions on your machine: an orchestrator, a reviewer and builders. Tares holds the plan, the tickets, the reviews and your answers, so a crew that restarts carries on where it stopped. For the full picture, see Get started.

When a project keeps its tickets in Linear, this is what happens:

• Each issue in the Linear project becomes a ticket, keyed by its identifier such as ENG-123.
• Tares keeps title, status, order and identifier in step, about once a minute. Sync now on the Tickets page reads at once.
• Linear workflow states map to Tares statuses: backlog, unstarted and triage are todo, started is in_progress, completed is done, and canceled and duplicate are canceled.
• The Linear project’s milestones, and which tickets belong to each, come across too.
• When one issue blocks another, the blocked ticket depends on it. A blocked ticket names the tickets it waits for.
• A builder takes a ticket, works on its own branch, opens a pull request, and merges it once the reviewer passes it and CI is green. It works the tickets one at a time.
• Each ticket has a working doc that sits with it in Tares. If an issue leaves the Linear project, the ticket becomes canceled and its working doc stays reachable.

Tares only reads from Linear. Sessions create and change the tickets in Linear itself.

Set it up

1. Check that Claude Code is signed in, that gh is signed in with write access to the repos the crew works in, and that git, jq and curl are installed.

2. Install the CLI and start Tares. Run tares up, then in a second terminal run tares mcp --transport streamable-http so every crew session can reach Tares. On Tares Cloud, run tares login instead and skip the MCP step.

   uv tool install tares     # or: brew install glassflow/tap/tares
   tares up                  # console on http://127.0.0.1:8787
   tares mcp --transport streamable-http

3. Give Tares access to GitHub: Connect GitHub on Tares Cloud, or a token or App under Settings > GitHub on a local Tares. Tares reads each ticket’s pull request, CI and merge state with it.

4. Connect Linear in Settings > Linear. On Tares Cloud, click Connect Linear and approve the Tares app. On your own Tares, paste a personal API key from Linear (Settings, Security and access, Personal API keys). Read access is enough.

5. Write the docs updates in Linear, one issue per change, with a title that names the page or section. Group related issues under a Linear milestone. In a Tares project, milestones show with their acceptance checks in the Tickets fold. Mark an issue as blocking another when one docs change must land first.

6. On the Tickets page of the Tares project, click Use a Linear project and pick it. A project that already has tickets of its own cannot be linked, so link one that has none.

7. Bring up the crew. The first run asks how far the crew may go, such as whether it merges on its own after review and green CI.

   tares factory crew up

8. Plan the work if you have not yet, and say yes when it asks whether to hand the project to the crew.

   tares factory spec "what you want to build"

9. Check the result. The Tickets page shows “Tickets live in Linear project …” and when it last synced. Change an issue in Linear and the ticket follows within a minute. The source’s Recent events shows the change.

To answer the crew’s questions, run tares factory crew attach orchestrator. A project, end to end shows what this looks like on a real project. The Linear connector page covers the sync in detail.

What you get

• Docs issues you write in Linear turn into pull requests, each reviewed to a fixed bar before it merges.
• The project page records each ticket with the builder that held it, its pull request and its review rounds.
• Linear stays your tracker. Status changes in Linear reach the ticket list, and every change is an event on the linear source: ticket_created, ticket_renamed, ticket_status, ticket_reordered or ticket_removed. Triggers and agents can react to them.
• Choices the crew makes on its own are written down as assumptions, and the orchestrator brings them to you at the end of each milestone.
• If a sync fails, for example after a revoked key, the Tickets page says why and the tickets stay as they were. Connect again in Settings > Linear.

When something else fits

• If you want Tares to hold the tickets itself, skip the Linear link and let tares factory spec write them. Stop using Linear on the Tickets page keeps the tickets as Tares tickets.
• If your tickets are GitHub issues, the GitHub Issues connector fits better.
• For a one-off edit, tares factory session works on a project in your own Claude Code session without the crew.

Related