Pocket-Relay docs

Getting started

Pocket-Relay runs as a hosted service. Your team works in a web dashboard, your customers reach you through a widget on your site, and Pocket-Relay connects to your GitHub organization to open issues and pull requests. It isn't open to new teams yet — email us to request a demo.

What works today

Every workflow in these docs runs end to end in testing. Some parts are not live yet:

• AI analysis uses a simple stand-in; the live AI model is built in but not switched on.
• The GitHub connection is built but not yet connected to any real repository.
• The AI coding agent that writes draft changes is still being built. Until it lands, an agent run commits a clearly labeled analysis and test plan instead of code.
• Team sign-in through your company's identity provider isn't wired into the dashboard yet.
• Gmail, Outlook, Slack, and Teams connections, and notifications sent by email or Slack, are built but not yet connected to live accounts.

What you need

A GitHub organization where you can install a GitHub app, and any current web browser. For the channels you choose: a Gmail or Outlook support mailbox, Slack, Microsoft Teams, or Chrome 102 or later for the staff extension.

Set up a product

A product is one thing you support. Only administrators can create or change products.

1. Open Products. In Connect a product, fill in Name, Slug (lowercase letters, digits, and dashes), Description, and GitHub organization, then click Create product. Request keys use the first six letters and digits of the slug — acme gives keys like ACME-1001.
2. Open the product. In Connect repository, enter the GitHub organization, Repository name, and Default branch, then click Connect repository.

Each repository lists its agent branches (ai/**) and allowed pull request types. Some settings aren't in the dashboard yet and are set by a Pocket-Relay administrator: the support email address, the Slack and Teams channels, the release signal, product categories, a daily request limit, and which GitHub reviewers cover each review area.

Connect GitHub

Pocket-Relay works through its own GitHub app, installed only on the repositories you choose. Installation isn't open yet. When it is, the app will ask for:

It asks for no organization or account permissions. Pocket-Relay refuses to write outside its ai/ branches or to touch .github/workflows and .github/actions, and it has no way to merge. We recommend two rulesets on each connected repository (Settings → Rules → Rulesets) so GitHub enforces the same limits:

1. On the default branch: require a pull request before merging, block force pushes, and restrict deletions, with no bypass for the app.
2. On every other branch: restrict creations, updates, and deletions, excluding the default branch and both ai/** and ai/**/**. Put your own people on the bypass list, never the app. GitHub's ** doesn't cross a /, so without the second pattern the app is refused on its own branches.

Widget and channels

Every channel creates the same kind of request: a key, a conversation, and an automatic triage.

Add the support widget

Each product has a widget key, issued by a Pocket-Relay administrator. Add one regular script tag (not a module) to the pages where you want the widget:

<script src="WIDGET-SCRIPT-ADDRESS" data-shc-key="YOUR-WIDGET-KEY" data-shc-api="YOUR-POCKET-RELAY-ADDRESS" data-shc-mode="chat"></script>

The widget adds a round button to the bottom-right corner. Its header tells customers that your team uses AI to analyze requests, that any AI-written reply is labeled as one, and that the conversation will say when a person takes over. Every mode asks for Your email; then:

• chat opens Support and asks How can we help?
• bug opens Report a bug and asks What went wrong?, What did you expect to happen?, and Steps to reproduce (one per line). The request arrives typed as a bug.
• feature opens Request a feature and asks What would you like to do? and What outcome are you looking for? The request arrives typed as a feature request.

After Send, the customer sees the conversation with the request key and status at the top. They can reply, attach an image (PNG, JPEG, GIF, or WebP, up to 10 MB), or start again with new request; the panel checks for new messages every few seconds while open. Replies are labeled Support team member, AI assistant, or Automated message.

A visitor's browser keeps one conversation per widget key. An administrator can replace a widget key; embeds that still use the old one can no longer open new requests.

Email

Mail sent to your product's support address becomes a request. Pocket-Relay can watch a Gmail or Outlook mailbox: about once a minute it files unread messages and marks each one read once handled, so connect a mailbox used only for support. A reply joins an existing request when it belongs to an email thread already on file, or when its subject carries the request key in square brackets, like [ACME-1042] — and the key only counts when the mail comes from that request's customer. Mailbox connections are set up on the hosted service and aren't live yet.

Slack and Microsoft Teams

These channels are for your colleagues. An administrator maps a Slack channel and a Teams channel to each product. In Slack, a new message in that channel opens a request; in Teams, a new message to Pocket-Relay in the mapped channel does. Replies in the thread are added to the same request. Both connections are set up on the hosted service and aren't live yet.

The Chrome extension for your staff

The extension lets your staff file a request from any page. It isn't in the Chrome Web Store yet.

1. Open the extension's options page, Pocket-Relay — Extension settings, and enter the API base URL you were given and Your email, the contact email on every request you file. Under Products, click + Add product for each product, with a name and its widget key.
2. Click Save, and allow Chrome's prompt to reach that one address.
3. To file, click the extension's button (File a support request), choose the Product and Request type, add an optional Summary and a Description, and click Send. The popup confirms with Filed as and the new key.

Attach current page URL and title is off by default and applies to one submission at a time. The extension never reads anything else from the page — no content, form fields, cookies, or screenshots.

From the dashboard and GitHub

To log a request by hand, use New request (dashboard intake) on Requests: choose the Product, add a Summary and Details, optionally set Type (optional — AI classifies later) and Customer email (optional), and click Create request. Comments people leave on the issues and pull requests Pocket-Relay created are copied back to the request as internal notes, which customers never see.

Triage requests

Every new request is triaged automatically: sorted, prepared for GitHub with personal details removed, compared with earlier requests, and given a recommended next step. A type set by a form or a person is never overwritten.

The queue

Requests lists every request with its Key, Summary, Product, Type, and Status. Change All products to one product to narrow the list, and click a key to open a request.

Read the AI analysis

The AI analysis card shows the categories, the customer's sentiment, and the classification confidence, plus:

• Recommended action — the suggested next step, from the table below.
• Related requests — similar requests for the same product, linked automatically.
• Engineering prompt (generated) — a brief written from the request's structured details with personal information removed. It's the starting point for a draft change.

If the card says Triage has not run yet., wait a moment and reload the page.

Answer the customer

Click Suggest customer reply for a draft answer, edit it, then click Post to customer — or discard it. The AI never writes to a customer on its own, and a reply a person posts appears to the customer as Support team member. You can also type in the Conversation card and click Post message.

The audit trail

The Audit trail card lists every recorded action on the request — who or what did it, and when — including each automation decision and, when Pocket-Relay declined to act, its reasons. It shows the latest eight; click Show all … events for the rest.

Issues, specs, and draft changes

The GitHub actions card on each request turns it into engineering work and refreshes on its own. Which buttons work for you depends on your role — see Roles, privacy, and data.

Create an issue or a specification

Click Create GitHub issue for an issue with the summary, problem, evidence, reproduction steps, priority, and related requests filled in and personal details removed. There's one issue per request and repository, so a second click doesn't duplicate it.

Click Create specification PR to have Pocket-Relay write a structured specification to docs/features, docs/bugs, or docs/product-requirements on a new branch and open it as a draft pull request. The request then moves to awaiting_approval; for a feature, your product owner is also requested as a reviewer.

Approve a feature

A feature request needs a product manager's approval before any implementation work. On requests from the widget's feature form, the card shows Feature approval with Approve for implementation and, while pending, reject. Whoever filed the request can't approve it.

Start a draft change

1. Click Create code PR (agent)…. The generated brief opens in an editor.
2. Review and edit it. The coding agent receives exactly this text.
3. Click Approve prompt & start agent, or cancel.

The agent works in a disposable, sealed workspace with no network access and hard limits on time and usage; if it hits a stop condition or a limit, the run ends stopped for review instead of retrying. Its work lands on a branch such as ai/bug/ACME-1042-export-fails as a draft pull request whose description covers the customer problem, changes, files, tests, risks, rollback plan, and required reviewers. Structured notes follow as comments, reviewers are requested, and labels such as pocket-relay and risk:medium are added.

If a change touches files a risk rule blocks, Pocket-Relay pushes the branch but doesn't open the pull request; an engineer can inspect it and open one by hand. A request can have one agent run in progress at a time.

Record a bug reproduction

On requests from the widget's bug form, the Bug reproduction card records whether the bug reproduces — meaning a failing automated test in your repository. Add a note, such as which test fails, then click Reproduced or Could not reproduce. Choosing Reproduced re-checks the product's automation policy.

Follow the work

The card lists the request's Issues, Pull requests (with type, review status, CI, risk, reviewers, and structured notes), and Agent runs. If this request, or one linked to it, already has an open pull request, a banner says so before you create more work.

The Pull requests page lists everything Pocket-Relay has opened, with risk, CI, reviewers, review status, and release status. Narrow it with All PR types, All risk, All CI, All review states, and All release states, or click Clear filters.

Automation and risk rules

Automation decides what Pocket-Relay may do without a click. Only administrators see and change these settings, and every change is recorded.

Choose an automation policy

1. Open the product from Products and find the Automation policy card.
2. Choose a Mode, and set the Minimum classification confidence (0.9 unless you change it).
3. Click Create policy, or Update policy if one exists.

In every mode, automation acts only when every condition holds, and anything unknown counts as a no. The defaults are strict:

• Only requests classified as bugs, at or above your confidence setting, and never critical or unknown severity.
• Never requests from public channels — the widget, the support mailbox, or the staff extension; a person has to act on those.
• For automatic draft pull requests: a bug reproduced by a failing test, a repository that allows the pull request type and has risk rules of its own, and a change of no more than 20 files.
• Feature requests always need a product manager's approval first.

No setting can merge, deploy, or run a database migration. Conditions other than confidence are changed by a Pocket-Relay administrator outside the dashboard.

Set risk rules for a repository

Under each repository, Path risk policies map file patterns to a risk level and reviewers. A change's risk is the highest level among the rules its files match, and its reviewers come from every rule it matches. No AI is involved in setting risk.

1. Enter a pattern such as src/payments/**. ** matches any depth; * stays within one folder.
2. Choose low, medium, high, or critical.
3. List review areas, separated by commas: security, payments, accounting, tax, backend_lead, platform, privacy, accessibility, or product_owner.
4. Leave blocks auto-PR checked if Pocket-Relay should stop short of opening a pull request for matching changes, leaving the branch for an engineer. Click Add; use remove to delete a rule.

Built-in rules apply to every repository: changes under .github/, database migrations, lockfiles, and container build files are high or critical risk, and Pocket-Relay never opens a pull request for them itself. A repository with no rules of its own can't receive automatic draft pull requests at all.

Follow-up and release

The customer's conversation stays linked to the work until the fix ships.

Follow-ups reach the pull request

When a customer adds a message or an image to a request with pull requests, Pocket-Relay removes personal details, sorts it as new evidence, changed requirements, clarification, scope expansion, possible regression, duplicate report, or resolution confirmation, and posts it to each pull request as a Conversation update comment. In the dashboard, the message shows its kind as a badge.

How a request moves

The widget shows customers the same status, with spaces instead of underscores.

Release and customer notification

Each product has a release signal — a merge to the default branch (the default), a published GitHub release, or a successful deployment — shown on the product page. When it fires, Pocket-Relay marks the pull request released, adds a Release note, moves the request to released, and drafts one customer notification saying the fix is live and asking the customer to confirm.

Review the draft in the request's Customer notifications card and click Send to customer; nothing is sent until a person does. It appears in the customer's widget conversation as an Automated message, and customers who wrote in by email or Slack will also get it there once those connections are live. When the customer replies that it works, the request moves to verified; a report that the problem is back is recorded as a possible regression.

Measure the results

Metrics shows Deflection rate, Time to draft PR, Agent PR merge rate, and Classifications corrected, filtered by Product and Since (optional). With nothing to measure, a figure reads no data rather than zero, and a small sample is flagged sample too small.

Roles, privacy, and data

Roles

Pocket-Relay has six roles, and each person can be limited to certain products. The service itself enforces them, not just the dashboard's buttons.

Where your data goes

• Conversations and attachments are stored by the Pocket-Relay service, with attachments in private storage. Your team sees the original messages.
• Before anything goes to GitHub — issue and pull request text, branch and file names, the coding agent's brief, and follow-up notes — Pocket-Relay removes email addresses, phone numbers, card numbers, account numbers, and the customer's known name.
• Comments imported from GitHub stay internal and are never shown to customers.
• Live AI processing isn't switched on. When it is, each request's text will go to the AI provider to classify it and find related requests; the removal of personal details applies to GitHub-bound text, not to this step.

What the widget and extension store

The widget keeps one item in a visitor's browser: a private token for their conversation, so a returning visitor lands back in it. Pocket-Relay stores only a fingerprint of it. By default the token stops working after 30 days without use, it travels only in a request header — never in a web address — and the widget talks only to https:// addresses.

The staff extension keeps its settings, including your products' widget keys, in your Chrome profile, and reads the current page's address and title only when you turn on Attach current page URL and title.

Troubleshooting and help

Known limits

• You can't close or resolve a request from the dashboard yet; requests move forward on their own as work is created, merged, released, and confirmed.
• Notification drafts can't be edited, or resent once failed, from the dashboard. A notification whose text looks like code, a file path, a branch name, or a pull request reference is marked failed and not sent.
• Customer images appear in the dashboard conversation as a file name and can't be opened there yet.
• The widget's header line, “We usually respond within a business day,” can't be changed yet.
• Feature approval appears only on requests from the widget's feature form, so a feature request from another channel can get a specification but not an implementation pull request.
• If a customer's widget shows an empty form again, their conversation token expired or the widget key was replaced. The conversation is still in the dashboard.

Messages you might see

Getting help

Questions about Pocket-Relay, or want to see it working? Email us.