Rensei docs

Quickstart

First agent in under 10 minutes using Linear and the default SDLC.

This guide connects Rensei to your Linear workspace and GitHub repository, then triggers the default SDLC workflow on a real issue - all in under 10 minutes.

What you will have at the end: a running agent session that picks up a Linear issue, writes code against your repository, and reports back to Linear as a native Linear Agent.

Prerequisites

Step 1 - Authenticate

Open a terminal and authenticate with Rensei:

rensei auth add --user

Your browser opens. Complete the login flow and return to the terminal.

Verify authentication and select your active project:

rensei setup

The wizard lists available projects. Select the one you want to use for this quickstart. If you do not yet have a project, the wizard offers to create one.

Step 2 - Connect Linear

From the terminal, connect your Linear workspace to the active project:

rensei project trackers connect linear

Your browser opens the Linear OAuth consent page hosted by Rensei. Approve the connection. The CLI waits for the platform to confirm, then registers a webhook subscription with your Linear team so Rensei receives issue events.

The OAuth credential is stored at the org level - agents never need LINEAR_API_KEY in their environment; authentication flows through the platform proxy.

Confirm the connection:

rensei project trackers list
# → linear  connected  <your-workspace-name>

Rensei uses a platform OAuth proxy for Linear. Agent workers authenticate through your stored org credential - no API keys are passed to individual agents. See integrations/linear for the full OAuth scope and AgentSession configuration.

Step 3 - Set up your Linear statuses

The default SDLC drives every issue through a fixed set of Linear workflow statuses, and the platform matches them by exact, case-sensitive name. If a status name does not match, the matcher emits no event and the issue silently stalls - so configure these before you create your first issue.

There is no automatic provisioning: you create and rename these statuses by hand, on the Linear team connected to your project, under Settings → Teams → [your team] → Issue statuses & automations (Triage is enabled on its own page - see the list below). Linear groups statuses into categories - Triage, Backlog, Unstarted, Started, Completed, Canceled - and you can rename a status or add new ones within a category, but categories themselves cannot be reordered.

Work through these in order:

  1. Backlog - already exists in the Backlog category. Confirm it is still named exactly Backlog.
  2. Triage - enable Triage under Settings → Teams → [your team] → Triage, then confirm the team's triage status reads exactly Triage.
  3. Icebox - add a new status in the Backlog category named Icebox, and drag it above Backlog so it sorts first.
  4. Started - rename the stock In Progress status to Started (keep it in the Started category).
  5. Finished - add a new status in the Started category named Finished.
  6. Delivered - add a new status in the Started category named Delivered.
  7. Accepted - rename the stock Done status to Accepted (keep it in the Completed category).
  8. Rejected - add a new status in the Unstarted category named Rejected.
  9. Canceled - already exists in the Canceled category. Confirm it is named exactly Canceled. Recommended.
  10. Duplicate - already present; Linear applies it automatically when you mark an issue a duplicate. No action.

Status reference

StatusLinear categoryStock or customRole in the SDLC
IceboxBacklogCustomIntake. Research runs here; pass → Triage, fail → Rejected.
TriageTriageStock (off by default)Backlog-writing runs here; pass → Backlog.
BacklogBacklogStockDevelopment picks up here and moves the issue to Started.
StartedStartedCustomActive-development marker while the agent works.
FinishedStartedCustomQA runs here; pass → Delivered. Must stay active.
DeliveredStartedCustomAcceptance runs here; pass → Accepted. Must stay active.
AcceptedCompletedCustomTerminal success.
RejectedUnstartedCustomUniversal fail state; refinement reworks it back to Backlog.
CanceledCanceledStockTerminal cancel. Optional.
DuplicateCanceledStock (reserved)Terminal; Linear auto-applies it. Optional.

Eight statuses are required (Icebox, Triage, Backlog, Started, Finished, Delivered, Accepted, Rejected); the pipeline breaks without them. Canceled and Duplicate are optional.

The pipeline flows Icebox → Triage → Backlog → Started → Finished → Delivered → Accepted, with Rejected as the kicked-back rework state at every stage. For the stage-by-stage trigger and exit mapping, see Default SDLC Template.

Two things fail silently if you get them wrong:

  • Names are exact and case-sensitive. It is Started, not In Progress; Accepted, not Done. A mismatch produces no event and the issue stalls with no error.
  • Finished and Delivered must stay in the Started (active) category - never Completed or Canceled. A completed- or canceled-category status makes Linear treat the issue as resolved and closes it mid-pipeline, before QA and acceptance can run. Rejected must likewise stay active so the rework loop can re-dispatch it.

You do not need a Done or Closed status; the canonical pipeline ends at Accepted. Statuses are per-team, so repeat this map on every Linear team that runs the default SDLC.

Step 4 - Connect GitHub

Authenticate your GitHub account with Rensei. This opens the GitHub OAuth consent page (or GitHub App install page) in your browser:

rensei project trackers connect github

Approve the Rensei GitHub App installation for the repositories you want agents to access. The platform records the OAuth credential at the org level - this step only needs to happen once per org.

Bind your repository to the active project:

rensei project repo add github.com/owner/my-repo

This creates a project-level binding that tells Rensei which repository agents should clone and push changes to.

Confirm the repo is linked:

rensei project repo list
# → github  owner/my-repo  default

Step 5 - Install compute (local daemon)

Rensei runs agent sessions on compute workers. The quickest path is your local machine.

rensei host install
rensei host status
# → daemon: running  version: v0.x.x  capacity: idle

rensei host install provisions an rsp_live_... worker registration token automatically when an rsk_ API key is present in your config. The daemon starts as a background service (launchd on macOS, systemd on Linux). To use a cloud sandbox instead of local compute, see sandbox providers.

Step 6 - Subscribe your project to the default SDLC

Every new Rensei project can subscribe to the built-in SDLC workflow. From the dashboard:

  1. Open app.rensei.ai and navigate to your project.
  2. Go to Workflows and select the Default SDLC template.
  3. Click Subscribe - this installs the workflow and configures it to trigger on Linear issue creation and @rensei mentions.

Alternatively, from the CLI:

rensei project workflow subscribe sdlc-default

The default SDLC template is the sdlc-v2-authored workflow. It runs five phases - research, backlog-writer, development, QA, and acceptance - with a fresh agent session per phase. Each phase hands off its output to the next. See Default SDLC template for the full canvas layout and configuration options.

Step 7 - Create a Linear issue and watch it run

In your Linear workspace, create an issue in the team that is connected to your Rensei project. Give it a clear title, e.g. Add a /health endpoint to the Express server.

Wait a few seconds. Return to the Rensei dashboard and navigate to Sessions under your project. You should see a new session appear with status queued or running.

Click the session to open the activity stream. Watch the agent's thoughts, tool calls, and progress in real time.

Back in Linear, the agent posts progress as a native Linear Agent thread - you can read thoughts, reply with instructions, or stop the session directly from the Linear issue.

What just happened

Linear issue created
       │
       ▼
Rensei webhook receiver
  (verifies HMAC signature, routes to project)
       │
       ▼
Orchestrator dispatches default SDLC workflow
       │
       ├── Research phase    → agent reads issue + codebase
       ├── Backlog-writer    → produces structured work plan
       ├── Development       → agent writes code, opens PR
       ├── QA                → agent runs tests, checks diff
       └── Acceptance        → final review, marks issue done
       │
       ▼
Linear AgentSession thread updated throughout

The agent runs on your local daemon (or the next available sandbox), uses memory from previous sessions to understand your codebase, and routes through your model profile (defaulting to the org-level setting).

Interact with a running session

You can prompt a running agent from the CLI:

# List active sessions
rensei session list --project my-project

# Send a message to a running session
rensei session prompt <session-id> "Please also update the README with the new endpoint"

# Stop a session
rensei session stop <session-id>

Troubleshooting

The session does not appear after creating a Linear issue.

Check that the Linear webhook was received:

rensei observability events tail --filter "providerId=linear"

If no events appear within 30 seconds of creating the issue, the webhook may not be reaching your project. Verify the webhook subscription is active: open app.rensei.ai → Settings → Integrations → Linear and confirm the subscription is active for your Linear team. If you recently re-connected Linear, run rensei project trackers connect linear again to refresh the webhook registration.

The agent stops with No capacity available.

Your local daemon may not be running:

rensei host status
rensei host install   # if not installed

The agent 401s against Linear.

The org OAuth token may need to be reconnected. Run:

rensei project trackers connect linear

The session appears but no Linear Agent thread is created.

This usually means the Linear OAuth scopes are incomplete. Disconnect and reconnect to re-authorize with the full required scope set (including app:assignable and app:mentionable):

rensei project trackers connect linear

Next steps

Key Concepts

Key concepts and glossary: layered model, project, workflow, agent.

On this page

PrerequisitesStep 1 - AuthenticateStep 2 - Connect LinearStep 3 - Set up your Linear statusesStatus referenceStep 4 - Connect GitHubStep 5 - Install compute (local daemon)Step 6 - Subscribe your project to the default SDLCStep 7 - Create a Linear issue and watch it runWhat just happenedInteract with a running sessionTroubleshootingNext steps