Tessl Code Review

Tessl Code Review reviews a pull request or a local change with several reviewers running in parallel, one per lens, then merges and grades what they found into one review. It runs from the CLI as tessl code review, and on GitHub as the Tessl Review GitHub App.

This plugin holds every part a user touches:

The review-* skills are lenses. Four of them, for program code, are the default lenses; review-plugin-content and review-markdown review agent plugins and other Markdown when a profile routes them. They are reviewer instructions that tessl code review loads into its own reviewer agents. Do not activate one to review code yourself: a lens on its own has no supervisor to merge and grade findings, and the result is not a Tessl Code Review.

Route the request

Read the request and the repository before choosing. One question is usually enough when the request is ambiguous; do not interview.

1. Is this about getting Code Review running on a repository? A request to install, enable, set up, or turn on automatic review of pull requests is an install job, including one that asks for a GitHub Action or a workflow. Follow Installing on a repository. Do not read the repository's workflows to decide this, and do not treat a missing workflow as work to do.
2. Is there a review to answer? A pull request with a Tessl Code Review on it, or a pasted set of findings, and a request to deal with them is a respond job.
3. Is the complaint about what reviews catch? Missed classes of bug, noisy findings, a concern the team keeps raising by hand, or a request for a custom rule is a lens job. A request to change when or whether reviews run is not.
4. Is it about which lenses run where? Adding a lens to a repository's reviews, scoping a lens to some paths, or keeping files out of review is a change to the repository profile. Read references/repository-profile.md before writing it.
5. Otherwise, run a review. A request to look at a change now, with no installation or lens work implied, is a CLI run.

Hand off by following the named skill. Say which one you are using and why in one line. If two jobs are present, do the one that unblocks the other first: an install before a lens, since a lens changes a review that has to be running, and a respond before anything else when a review is waiting.

Installing on a repository

Tessl Code Review runs on GitHub as the Tessl Review GitHub App. Installing the App is the supported way to install Tessl Code Review, and it starts on the organization's Code reviews page in the Tessl web app. Until an installation exists, that page offers Connect GitHub. Once one does, it lists the repositories the App can reach, and a repository's row is where it is enabled and where its trigger policy and review behavior are set.

Build the link to that page. It is per-organization, so find the organization first:

tessl org list --json

Take the organization's id from the output and put it in:

https://tessl.io/orgs/<id>/code-reviews

An organization UUID in that position redirects to the organization's slug, so the link resolves without you having to know the slug. When tessl org list --json returns more than one organization, ask which one to set up rather than guessing: the link points at a single organization, and installing against the wrong one is invisible until no reviews arrive.

Not every organization has this page. If the user reports it is not there, their organization is not enabled for Tessl Code Review. Say that, and that enabling it is a change Tessl makes rather than one they can make. No other address reaches the App, and the CLI cannot install it, so there is nothing further to offer.

Give the finished link on its own line. Never construct or emit a github.com/apps/... install link: those carry signed per-user state that expires in ten minutes, so a link you produce is broken by the time anyone follows it. The page mints that link itself, in the browser, which is why the install has to start there.

The documentation covers the full setup, and is worth naming next to the link for a user who wants to read before clicking:

https://docs.tessl.io/tutorials/setting-up-agentic-code-review

Then do three things, in order:

1. Offer to open the page. Ask whether to open the link, and only open it once the user agrees. Use the platform's opener: open on macOS, xdg-open on Linux, start on Windows. If the command fails, say the page could not be opened and leave the URL on screen for the user to follow themselves. A failed opener is a failed open, not a failed install; do not report it as one.
2. Say that the App alone is not enough. After the App is installed, the repository also has to be enabled in Tessl before any review runs. State this explicitly every time. It is the most common misunderstanding, and a user who stops at the App install sees no reviews and concludes the product is broken. The Code reviews page is where enabling happens. GitHub hands the user back to it, and it lists the repositories the App can reach; enabling one means opening its row and turning it on. Tell them to finish there.
3. Stop. You cannot see whether the App was installed or whether the repository was enabled: neither is visible from this machine. Do not poll, do not check for a webhook, a workflow, or a check run, do not claim the install succeeded, and do not offer to carry on with the rest of the setup. End the turn with the URL and the two steps the user owns.

The App is the only install path. A user who asks for a GitHub Action or a workflow, or says they cannot install a GitHub App, gets the same link and an explanation of what the App requires and who in their organization can approve it. Do not write a workflow as a substitute.

Running a review from the CLI

tessl code review reviews the working tree's change against the default branch when given nothing. It takes a range with --base and --head, or a pull request with --pr.

tessl code review
tessl code review --base origin/main --head HEAD
tessl code review --pr 42

The default lens set is six lenses in this plugin, pinned to a version of this plugin: four code lenses, plus review-plugin-content and review-markdown, each change file going to exactly one group by its kind. A plain run needs no lens selection. --skill replaces that set with the complete ordered set you name; it does not add to it. A reference is a local path, an installed skill name, or a registry ref workspace/plugin[@version]#skill. A registry ref without a version follows the newest published version; a ref with one stays fixed until someone edits it. Choose per ref. A plain run uses the lens version the CLI pins, which can be older than the newest published one, so an unversioned tessl/code-review#... ref can review differently from a plain run.

tessl code review --skill ./review-lenses/review-test-reliability
tessl code review --skill tessl/code-review#review-security-and-privacy

--json writes one document to stdout on success and failure alike. Count findings only when status is ok: a failed or skipped run with no findings otherwise looks like a clean review.

Never pass --publish unless the user asked for the review to be posted to the pull request. A local run is a preview.

What not to do here

• Do not hand-write a lens. create-code-review-lens knows the contract the CLI enforces.
• Do not write a profile without reading references/repository-profile.md. The CLI rejects unknown fields and malformed patterns.
• Do not write a GitHub Actions workflow to install Code Review, and do not offer to. The App is the install path.
• Do not answer findings for the user without reading respond-to-code-review. Fix, refute, and decline are distinct dispositions with distinct consequences.
• Do not describe the plugin's internals when asked what Code Review does. Say what it reviews, where it runs, and offer the four jobs.