# Agents

> Delegate issues to coding agents or @mention them, and follow each piece of work as a session.

Source: https://docs.linefold.app/agents

Agents are workspace members. **Delegate** an issue to one, or **@mention** it in a comment, and the work becomes an
**agent session** you follow and steer by replying, right on the issue.

## Coding agents

Claude Code, Codex and Cursor write code. Their sessions run in an environment:

- **A device you paired**, in folders you shared: see [Pair a device](/pair-a-device).
- **A cloud environment** an admin sets up in **Settings › AI & Agents › Coding sessions**.

Either way they use **your** connected accounts ([Quickstart](/quickstart#4-connect-claude)). The composer's
**Environment** menu moves a session elsewhere.

## Which agents a team may use

Set it in the team's settings and in **Settings › Agents**.

## Related

- [Loops](/loops): agents started by a schedule, an event or a webhook.
- [MCP connectors](/mcp-connectors): give agents tools from other services.
- [Coding tools](/coding-tools): hand an issue to your editor or terminal instead.

# API

> Linefold's GraphQL API, compatible with Linear's schema and SDK.

Source: https://docs.linefold.app/api

Linefold serves a GraphQL API at `https://app.linefold.app/graphql`, with Linear's schema: Linear's SDK and tools work with
it when pointed at this address.

Authenticate with a personal API key (**Settings › Account › Security & access**) or an [OAuth application](/oauth)'s token:

```sh
curl https://app.linefold.app/graphql \
  -H "Authorization: Bearer lin_api_…" \
  -H "Content-Type: application/json" \
  -d '{"query":"{ viewer { id name } }"}'
```

The workspace's keys and applications are listed in **Settings › API**.

# Asks

> Turn requests from Slack, a web form or an email address into issues in triage.

Source: https://docs.linefold.app/asks

Asks turn requests from people outside your teams into issues. Each request lands in the team's triage, and the requester
hears back when it's done. Set them up in **Settings › Asks**.

## Slack channels

Requests posted in a connected channel become issues. See [Slack](/slack).

## Web forms

Your templates become forms anyone in your organization can fill in. They sign in through your identity provider (a custom
SAML app pointing at the form's address) and get email updates.

## Email intake

An intake address files each email it receives as an issue. To use your own address, forward it to the intake address
Linefold shows, and set a domain to send replies from.

# Coding tools

> Open an issue in your editor or a terminal agent with a prompt made from it.

Source: https://docs.linefold.app/coding-tools

**Open in…** on an issue hands it to a coding tool with a prompt built from the issue:

- an editor or app (Cursor, Zed, VS Code…) by its link;
- a terminal tool (Claude Code, Codex…) through the desktop app;
- a custom script: a command of yours, given the issue's details.

Choose the tools you see, and edit the prompt, in **Settings › Code & reviews › Coding tools**.

# Discord

> Add the Linefold bot to your Discord server.

Source: https://docs.linefold.app/discord

An admin enables Discord in **Settings › Integrations › Discord**, which adds the Linefold bot to a server. Everyone then
links their own Discord account in **Settings › Connected accounts › Discord**: Linefold only acts for people who linked
theirs. **Disable** removes the bot.

# Documents

> Pages written together, private or shared, with nested pages and a workspace wiki.

Source: https://docs.linefold.app/documents

A document is a page with a rich body that several people write at once. It lives in one place: a team, project,
initiative, issue, cycle, the workspace, or your private space. **Documents** in the sidebar shows pinned documents,
**My documents**, **Shared with me** and recent ones. Deleted documents stay in **Recently deleted** for 30 days.

## Private documents and sharing

**Create private document** makes one only you can see, not even admins. **Share** adds people as **Can edit**,
**Can comment** or **Can view**. Only the owner shares and changes roles; removing someone takes the document off their
devices at once. Guests can't be added.

## Access to team and workspace documents

Everyone who can see the place can read and edit its documents, unless the owner, a team owner or an admin lowers
**Everyone in …** to **Can comment** or **Can view**. **Move to…** shows who gains and loses access before a document moves.

## Pages

A document can hold pages, up to three levels deep. Add one with **Add page** beside the title, or type `/page`. Pages
follow their document when it moves, is shared or deleted.

## Workspace documents

**Home** in the sidebar's Workspace section is a wiki every member can read (not guests). Use **Create workspace document**,
or **Move to… › Workspace**.

# Importing issues

> Copy issues from Jira or Linear, once or kept in sync.

Source: https://docs.linefold.app/imports

**Settings › Import & export** copies issues into teams here, with comments, relations, and people mapped to members:

- **Jira**: a project, with a Jira API token, into an existing team or a new one.
- **Linear**: the teams you pick, with a Linear personal API key.

Imported issues get a removable **Migrated** label. Turn on **Keep in sync** to copy new and changed issues every few minutes
(one way: changes here aren't sent back). An import can be deleted in full within 14 days.

# Introduction

> Linefold is an issue tracker with code review and coding agents built in. Plan the work, hand it to an agent, review the pull request, all in one place.

Source: https://docs.linefold.app/

Linefold keeps your team's issues, projects and documents together with the pull requests that close them, and the coding
agents (Claude Code, Codex, Cursor) that write them. Agents run on your own computer or a cloud environment, with your own
accounts.

<Cards>
<Card title="Quickstart" href="/quickstart">
Sign in, create a workspace, connect GitHub and Claude.
</Card>

<Card title="Pair a device" href="/pair-a-device">
Let coding agents run on your computer.
</Card>

<Card title="Agents" href="/agents">
Delegate an issue and follow the session.
</Card>

<Card title="Reviews" href="/reviews">
Pull requests, diffs and review threads next to the issue.
</Card>

<Card title="MCP server" href="/mcp">
Use Linefold from Claude, ChatGPT, Cursor or any MCP client.
</Card>

<Card title="API" href="/api">
GraphQL, OAuth applications and webhooks.
</Card>
</Cards>

## For agents

Every page is also plain Markdown: add `.md` to its address (`/quickstart.md`), or ask for `text/markdown`. The index
is <a href="/llms.txt">/llms.txt</a> and every page in one file is <a href="/llms-full.txt">/llms-full.txt</a>.

# Issues and teams

> Team views, triage, cycles, estimates, templates and recurring issues.

Source: https://docs.linefold.app/issues

## Team views

Each team has **Triage** (when it is on), **Active**, **Backlog** and **All issues**, plus its projects, cycles and
documents. Filters and display options (grouping, ordering, properties) are kept per view.

A **custom view** saves filters and display options under a name. Create one from **Views** in the sidebar or **Save view**
on any filtered list, and share it with a team or keep it personal.

## Triage

An inbox for the team: issues from people outside the team, integrations or agents land here first. Accept, decline, merge
or snooze each one. Turn it on in the team's settings under **Triage**.

## Cycles

A team's repeating time boxes, one to several weeks long. Unfinished issues roll over. The cycle graph compares scope with
started and completed work, day by day. Set length and start day in the team's settings under **Cycles**.

## Estimates

Size issues on an exponential, Fibonacci, linear or t-shirt scale; they feed a cycle's capacity. Choose the scale under
**Estimates** in the team's settings.

## Templates

Templates prefill new issues, projects and documents: title, description, properties, sub-issues. Workspace templates live in
**Settings › Templates**, a team's in its settings. Pick one when creating, or set a team default.

## Recurring issues

A template the team creates on a schedule (daily, weekly, monthly…) for chores that come back. Set them up under
**Recurring issues** in the team's settings.

# Loops

> Agent workflows started by a schedule, a change in the workspace or a webhook call.

Source: https://docs.linefold.app/loops

A loop starts an agent on its own: on a schedule, when something changes in the workspace (an issue created or moved…), or
when its webhook is called. Each run is an agent session you can open and follow.

Manage loops in **Settings › Loops**.

## Limits

Limits cap how many runs a workspace, and each loop, may start in a period, so a loop that triggers too often stops instead
of running away. Set them in **Settings › Usage & limits › Spend limits**.

# MCP connectors

> Give agents tools from other services through their MCP servers.

Source: https://docs.linefold.app/mcp-connectors

An MCP connector is an MCP server's URL and, when it needs one, a sign-in. Agents then use that service's tools in their
sessions. Connections you make are yours.

Administrators decide whether connectors are allowed, and which servers, in **Settings › Security › MCP connectors**.

Looking for the opposite, using Linefold from an AI client? See [MCP server](/mcp).

# MCP server

> Connect Claude, ChatGPT, Cursor, VS Code, Codex or any MCP client to your Linefold workspace.

Source: https://docs.linefold.app/mcp

Linefold's hosted MCP server lets AI clients find, create and update your issues, comments, projects, documents and reviews,
as you. Nothing to install.

**Server URL:** `https://app.linefold.app/mcp` (Streamable HTTP, OAuth 2.1 or an API key)

The first time a client connects, approve it, then pick the workspace it acts in.

## Claude Code

```sh
claude mcp add --transport http linefold https://app.linefold.app/mcp
```

Then run `/mcp`, pick `linefold` and **Authenticate**.

## Claude (web, desktop, mobile)

**Settings › Connectors › Add custom connector**: name `Linefold`, URL `https://app.linefold.app/mcp`, then **Connect**.

## ChatGPT

**Settings › Apps & Connectors › Advanced settings**: turn on **Developer mode**, then **Create** with the server URL and
authentication **OAuth**.

## Cursor

In `~/.cursor/mcp.json`:

```json
{ "mcpServers": { "linefold": { "url": "https://app.linefold.app/mcp" } } }
```

## VS Code

```sh
code --add-mcp '{"name":"linefold","type":"http","url":"https://app.linefold.app/mcp"}'
```

## Codex

```sh
codex mcp add linefold --url https://app.linefold.app/mcp
codex mcp login linefold
```

## Other clients

Clients that only run local servers connect through `mcp-remote`:

```json
{ "mcpServers": { "linefold": { "command": "npx", "args": ["-y", "mcp-remote", "https://app.linefold.app/mcp"] } } }
```

## Read-only and API keys

`https://app.linefold.app/mcp/readonly` lists only the read tools. Instead of signing in, send a personal API key
(**Settings › Account › Security & access**) as a header:

```sh
claude mcp add --transport http linefold https://app.linefold.app/mcp --header "Authorization: Bearer lin_api_…"
```

The full tool list is at [app.linefold.app/docs/mcp](https://app.linefold.app/docs/mcp).

# Members and roles

> Invite people, approve email domains and set roles.

Source: https://docs.linefold.app/members

Members are **owners**, **admins**, **members** or **guests**. Invite people from **Settings › Members**, and change a
member's role from their row's menu.

With **approved email domains** (**Settings › Security**, each verified by a code mailed to an address at the domain), anyone
with an address there can join without an invite.

<Callout type="warn" title="Guests and private teams aren't enforced yet">
Every member and guest can see every team's issues, comments, projects and documents, private teams' included. Don't rely
on either to keep data from someone. Guests don't see initiatives.
</Callout>

A workspace's data region is set when it's created and can't be changed.

# OAuth applications

> Let your service act for people who authorize it, or as an agent of its own.

Source: https://docs.linefold.app/oauth

Create an application in **Settings › API** to get a client ID and secret, then set its redirect URIs and scopes.

- **For people**: OAuth 2.0 authorization code flow with PKCE.
- **As an agent**: `actor=app`, with the `app:assignable` and `app:mentionable` scopes, so it can be delegated issues and
  mentioned.
- **Refresh tokens**: short-lived access tokens with a refresh token.
- **`client_credentials`**: a token for the application itself.

Revoke a token with `POST https://app.linefold.app/oauth/revoke`.

# Pair a device

> Install the linefold CLI so coding agents run their sessions on your own computer.

Source: https://docs.linefold.app/pair-a-device

Coding agents run their sessions in an **environment**: a device you pair, or a cloud environment an admin sets up in
**Settings › AI & Agents › Coding sessions**. A device needs macOS or Linux, Node 22 or later, and the agent CLIs you want
(for example `claude`).

```sh
npm install -g @linefold/cli
linefold pair
linefold add ~/code
linefold service install
```

1. Install the `linefold` command.
2. `pair` opens Linefold: approve the code it shows.
3. `add` shares a folder (your home is shared already).
4. `service install` keeps it running in the background on a Mac (elsewhere: `linefold start`).

The device then shows under **This device** in **Settings › Account › Environments**, with these commands to copy.

- `linefold status` says whether it is paired and running.
- Run the install command again to update.
- Try it without installing: `npx @linefold/cli pair`, then `npx @linefold/cli start`.

The daemon keeps one outbound connection to Linefold: no open port, no tunnel. A session's **Environment** menu moves it to
another device or environment.

# Phone app

> Install Linefold from the browser on iPhone or Android and get push notifications.

Source: https://docs.linefold.app/phone-app

- **iPhone or iPad**: open Linefold in Safari, tap **Share › Add to Home Screen**, then open it from the Home Screen.
- **Android**: open Linefold in Chrome and tap **Install app** in the menu.

Then turn on push in **Settings › Notifications › Mobile**, on that device, and send a test notification. On iPhone,
notifications only work in the app opened from the Home Screen.

There is no hover on a phone: a long press on a row opens its menu.

# Projects and initiatives

> Group issues into projects with milestones, and projects into initiatives.

Source: https://docs.linefold.app/projects

## Projects

A project groups issues, across teams if needed, toward a deliverable: a lead, members, dates, a status and updates. Create
one from **Projects** in the sidebar, or press `N` then `P`.

## Milestones

Milestones split a project into stages with target dates. Each issue can belong to one, and progress shows per milestone.
Add them in the project's details panel.

## Initiatives

Initiatives group projects toward a company goal, with an owner, a target date, health updates and sub-initiatives. Create
one from **Initiatives** in the sidebar; settings are in **Settings › Initiatives**.

# Quickstart

> From your first sign-in to an agent working on an issue, in five steps.

Source: https://docs.linefold.app/quickstart

## 1. Sign in

Open [app.linefold.app](https://app.linefold.app) and choose **Continue with email**. Linefold sends you a code, so there
is no password. Add a passkey later in **Settings › Account › Security & access**, or use **Continue with Google**.

## 2. Join or create a workspace

- **Invited?** Open the invite and sign in with that address.
- **Your company's domain is approved?** Pick your workspace from the list after sign-in.
- **Starting fresh?** Choose **Create a workspace**, pick its address and invite your team from **Settings › Members**.

You can belong to several workspaces and switch from the workspace menu at the top left.

## 3. Connect GitHub

**Settings › Connected accounts › GitHub › Connect.** Your pull requests then show under **Reviews**, and issues named in a
branch or pull request (`JAR-12`) link to it. If your organization hasn't installed Linefold's GitHub App, Linefold asks you
to install it (or to ask an owner).

## 4. Connect Claude

Agents run on **your own** Claude account: a Pro or Max plan, or an Anthropic API key. In **Settings › Connected accounts**,
under Claude, choose **Connect** and sign in. Add several and Linefold moves to the next when one hits its usage limit.
Codex (ChatGPT) and Cursor connect the same way.

<Callout title="Your keys stay sealed">
Credentials live in Linefold's credentials vault, a separate process. The app server and your paired computers only ever
see a placeholder valid for one run.
</Callout>

## 5. Pair a device and delegate

[Pair your computer](/pair-a-device), then delegate an issue to Claude Code (or @mention it in a comment). Its session
runs in a folder you shared, and you follow and steer it from the issue.

# Reviews and GitHub

> Pull requests with their diffs and review threads, linked to the issues they close.

Source: https://docs.linefold.app/reviews

Connect GitHub in **Settings › Connected accounts**. **Reviews** then lists your pull requests with their diffs and review
threads.

## Linking pull requests to issues

A branch name, title or description that names an issue (`JAR-12`) links the pull request to it.

| You write | What happens |
|---|---|
| `Fixes JAR-12`, `Closes JAR-12` | The issue moves to Done when the pull request merges |
| `Part of JAR-12` | Linked, without closing the issue |

Diffs use your own GitHub connection: reconnect it if Linefold asks.

# Security

> SAML single sign-on, SCIM provisioning, the audit log and third-party application controls.

Source: https://docs.linefold.app/security

## SAML

Members sign in through your identity provider (Okta, Google Workspace, Microsoft Entra ID…). Set it up in
**Settings › Security › SAML authentication & SCIM provisioning** with your provider's metadata.

## SCIM

Your identity provider creates, updates and deactivates members, and syncs groups to teams. Turn it on after SAML, on the same
page, and give your provider the URL and token it shows.

## Audit log

Security events (sign-ins, member and role changes, settings, API keys, applications) with who, when and from where. Owners
read and export it in **Settings › Audit log**, or stream it to a webhook.

## Third-party applications

An application you authorize acts in your workspace within the scopes you grant; what it does with the data is governed by
its own terms. Admins can require **approval** before members connect one, and revoke any connection in
**Settings › Applications**. You revoke your own in **Settings › Account › Security & access**.

# Slack

> File issues from Slack, unfurl links, get notifications as DMs and ask Linefold Agent.

Source: https://docs.linefold.app/slack

An admin connects Slack in **Settings › Integrations › Slack**. Then, in Slack:

- A message's **⋯ › Create new issue…** or `/linefold` files an issue. Its thread can sync both ways with the issue's comments.
- A pasted Linefold link shows a card you can act on.
- **@Linefold**, or a DM to the Linefold app, asks Linefold Agent.

A team's or project's channel gets updates from **Team settings › Slack** or the project's bell. For your own notifications
as DMs, link your Slack account in **Settings › Connected accounts** and turn Slack on in **Settings › Notifications**.
Private teams never show in a channel.

# Support

> How to reach the Linefold team and check whether Linefold is up.

Source: https://docs.linefold.app/support

- Write to [support@linefold.app](mailto:support@linefold.app).
- In the app: **Contact Linefold** from the command menu (`⌘K`), or **Contact us** in the Help menu (the **?** at the bottom
  of the sidebar).
- Is Linefold up? [Status](https://app.linefold.app/docs/status).

Legal: [Terms](https://app.linefold.app/docs/terms) · [Privacy](https://app.linefold.app/docs/privacy) ·
[DPA](https://app.linefold.app/docs/dpa)

# Webhooks

> Get an HTTP POST when issues, comments, projects and other data change.

Source: https://docs.linefold.app/webhooks

A webhook sends a POST to your URL when issues, comments, projects and other data are created, updated or removed. Create
them in **Settings › API**.

## Verify each request

Every request is signed. Compare the `Linear-Signature` header with the HMAC-SHA256 of the **raw** body under the webhook's
signing secret, and reject old `webhookTimestamp`s:

```ts
import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(rawBody: Buffer, signature: string, secret: string) {
  const expected = createHmac('sha256', secret).update(rawBody).digest();
  const received = Buffer.from(signature, 'hex');
  if (received.length !== expected.length || !timingSafeEqual(received, expected)) return false;
  const { webhookTimestamp } = JSON.parse(rawBody.toString());
  return Math.abs(Date.now() - webhookTimestamp) < 60_000;
}
```