How it works

Sinatra works like a teammate you hand a ticket to. You trigger it, it investigates and writes code, it opens a pull request, and it responds when you leave review feedback. This page walks through that loop.

Triggering the agent

From Linear:

• Assign an issue to Sinatra.
• @-mention it in a comment on the issue.

The person delegating must be a Sinatra workspace member with a linked Linear identity.

From GitHub:

• Add the Sinatra label to an issue. The label is named after the GitHub App, so it is sinatraai on the hosted app. Sinatra provisions it on the repos you enable — pick it from the existing label list rather than typing a new one, since the name has to match exactly.

The label is the only way to start a run from GitHub. Once a task exists, comment on the issue to continue it.

Whoever adds the label or comments must be a member of the Sinatra workspace, and their Sinatra account must use that GitHub account, by signing in with it or linking it.

You do not need Linear. Sinatra runs the full loop on a GitHub issue alone, opens a PR that closes the issue on merge, and posts its updates on the issue. Connect Linear if you want the agent to live in your Linear workflow instead.

Once triggered, the agent lets you know it picked the work up: a 👀 reaction on GitHub or on your Slack message, or a Received task, starting work… activity on the Linear agent session. On Linear, the issue moves to In Progress when new work starts.

From Slack:

• Mention @Sinatra in a channel it has been invited to, in a new message or inside an existing thread. It works in that thread.

An owner or admin connects Slack from workspace Settings first. The person mentioning Sinatra must be a Sinatra workspace member with a linked Slack identity, which Sinatra usually matches by email. A Slack thread doesn't name a repository, so include repo: owner/name when it could be ambiguous; see Choosing a repository.

From your terminal, Claude Code or Cursor

• Run sinatra "fix the flaky retry test" with the sinatra CLI.
• Ask Claude Code, Cursor, claude.ai, ChatGPT or another client connected to Sinatra's MCP server to start a task. It uses the start_task tool.
• Send POST /v1/workspaces/{workspaceId}/tasks to the HTTP API from your own scripts.

The CLI, Claude Code, Cursor, claude.ai and ChatGPT sign in with your Sinatra account; the HTTP API uses a personal access token from the dashboard's CLI & API page. A task started this way has no ticket: its conversation lives in Sinatra, where you read the agent's replies and answer them. It runs like any other task, gets a sandbox, and can open a pull request. See CLI, MCP and API.

From request to pull request

A task is a conversation. Each time you ask, the agent reads the conversation and decides whether the request needs an answer, a question back, a plan, or code changes. A question or plan does not require code changes or a pull request. There are no separate approval steps.

1. Understanding. The agent reads the complete issue or thread before deciding what to do.
2. Asking or planning. For a vague ticket, it asks questions or proposes a plan in an ordinary reply, then waits for you. Answer, adjust the plan, or tell it to go ahead.
3. Implementing. The agent writes code, verifies its changes, commits, and opens a draft PR. Sinatra then runs hooks.test_command if configured, with up to two agent attempts to fix failures.
4. Review. Sinatra runs self-review, attempts to mark the draft ready, and links it on the ticket. Read the test and review results: failures can leave a PR open and ready for a human to assess.

A PR is something the task produces, not the end of it. The task keeps taking replies while the PR is open and after it merges, and one task can open more than one PR. Merging or closing a PR changes that PR, not the task. When a PR merges or closes, Sinatra says so on the ticket; reply there if you need anything else.

When the agent asks a question or proposes a plan, reply on the ticket. On GitHub, comment on the issue; on Linear, reply in the agent session or in the thread of the comment Sinatra posted; in Slack, reply in the thread. For a task started from the CLI, MCP or API, reply in its conversation. The agent writes its own replies; Sinatra publishes one if the agent's posting fails.

When Sinatra needs your input, it can also email you that it's waiting for your reply.

Reviewing its own work

Pull requests open as drafts. Sinatra attempts to review its own diff against the ticket before marking them ready. If eligible feedback interrupts self-review, it keeps the PR as a draft and addresses the feedback first.

When the installation grants Checks write access, the sinatra / review check reports the outcome: residual P0/P1 findings fail, P2/P3 findings are neutral, and no residual findings pass. Self-review is best effort: a review error is reported and can still result in a ready PR. Neither self-review nor hooks.test_command guarantees that a ready PR is green. Your repository's required checks and human review remain the merge gate.

Watching progress

While the agent works, it streams its progress as it goes: a single rolling comment on a GitHub issue, Linear activity updates on a Linear issue, or one progress message in a Slack thread, edited in place. It updates one place instead of flooding the thread.

A task started from the CLI, MCP or API doesn't stream progress. Its conversation holds the agent's answer or question for each turn, plus Sinatra's own notices. Read it with sinatra show, the get_messages MCP tool, GET .../messages, or on the task's page in the dashboard. See How replies work.

Review and rework

After the PR is ready, the loop keeps going:

• Request changes on the PR, or comment with what you want different. The agent pushes revisions to the same branch.
• A failed GitHub check suite on Sinatra's PR gets a fix as its own turn, after any work people asked for. Sinatra explains on the PR how it classified the failure and what it did: a fix on the branch, a rerun of the failed jobs when the failure looks flaky, or a note that the failure is pre-existing or unrelated. It stops after ci.max_rework fixes in a row (two by default, set in .sinatrarc.json) with no message from a person, and says so on the PR. A person's message resets the count. If your queue is full, Sinatra says on the PR that it didn't start a fix. This is separate from the two retries of hooks.test_command inside an implementation turn.

The workflow preserves the task's durable state across worker restarts. Sinatra can reuse a recoverable sandbox and conversation, but a missing or unrecoverable sandbox requires a fresh environment. Committed work can be recovered from the branch; uncommitted files and agent context are not guaranteed to survive sandbox loss.

Steering a run

You direct Sinatra by replying in the thread it's working in. A few behaviors are worth knowing.

A message you send while the agent is running reaches the running agent, with both Claude Code and oh-my-pi. Sinatra decides when it applies: right away, before the run finishes, or as its own next turn once the current one ends. A reply after the run has ended starts the next turn, which is queued if your plan's tasks-at-a-time limit is reached.

A task started from the CLI, MCP or API works differently: a message sent while the agent is working doesn't change the current turn. It waits and runs as the next turn.

With oh-my-pi, an idle agent process stays warm for up to 45 minutes after a run, so a quick reply continues without a cold start; later replies resume the retained session. Workspace membership, repository access, and billing checks still apply.

Continue vs. restart

An actionable reply normally continues the current work: a correction, an extra requirement, or a different approach. Sinatra reuses the existing branch and available sandbox. Acknowledgements that ask for no action can be ignored.

Send the literal command restart to request a destructive restart: Sinatra abandons the sandbox, deletes its branch, closes the existing PR (including one already ready for review), and begins the ticket again. The command is case-insensitive. In Slack, mention Sinatra with only the word restart. Other messages continue the conversation.

Which comments wake it on a PR

Once a PR is open, leave code feedback on the PR. Sinatra acts on a PR comment only when it comes from a member of the Sinatra workspace, @-mentions Sinatra (@sinatraai), and actually asks for something — "fix the failing lint", "please re-review", "handle the empty case". Acknowledgements like "thanks" or "lgtm" are ignored. A 👀 reaction confirms it picked the comment up. A formal review that requests changes sends it back to rework; an approval doesn't trigger anything.

Reply in the right place

On Linear, reply in the issue's agent session, reply in the thread of a comment Sinatra posted, or mention Sinatra in a new comment. On GitHub, reply in an ordinary comment on the issue, or mention Sinatra on the PR. In Slack, reply in the task's thread: a reply that mentions Sinatra always reaches it, and one without a mention reaches it when Sinatra judges it's meant for it. For a task started from the CLI, MCP or API, reply with sinatra reply, the follow_up MCP tool or POST .../messages, or on the task's page in the dashboard.

Stopping and resuming

• GitHub — remove the Sinatra label or close the issue to cancel an in-flight run. Reopen a still-labeled issue to trigger a resume attempt; recovery depends on the retained branch and sandbox.
• Linear — the agent session's Stop control stops the current work and preserves the workstream for follow-ups. Reply or mention Sinatra again to continue. Moving the issue to a terminal state such as Cancelled, Done, or Duplicate cancels active work; return it to an active state before delegating again. If you mark the issue Done while its PR is open, Sinatra replies "Issue marked Done. Reply here if you need anything else."
• Slack — there's no stop control in Slack. Stop the task with Stop in the Running and queued list on the dashboard's overview, or with one of the commands below, then mention Sinatra in the thread to continue.
• CLI, MCP or API — sinatra stop <task-id>, the stop_task MCP tool, or POST .../stop stops the current turn and keeps the task for follow-ups. Send a message to continue. These work on any task in the workspace, wherever it started.

A stop that finds nothing running or waiting to run still keeps the task, and replies "Nothing was running; the task is idle." instead of "Stopped."

What the states mean

The dashboard shows each task in one of four states, and a Merged filter finds tasks whose PR merged:

Merging a PR doesn't end the task. It keeps taking replies, and it can open another PR.

Raw statuses

Each task's record also carries a lower-level status. Some messages and these docs mention it; you don't need it day to day.