Setting up agentic code review
Set up the Tessl Agent to review pull requests against your team's skills, locally and in CI.
Takeaways: After reading this page you will understand how the tessl change command group works, how to use the tessl agent to create a code review skill for your repository, how to set up a policy-based risk gate that decides when PRs need a human reviewer, and how to wire verifiers as CI checks that enforce code invariants.
Agents write code faster than human reviewers can keep up with. The tools described here handle three distinct problems: catching obvious issues before human reviewers see them, deciding which PRs actually need human review, and enforcing structural invariants automatically.
Throughout this tutorial the tessl agent does the heavy lifting. It ships with the tessl/harness-engineering plugin pre-bundled, so the skills that drive code-review setup — change-review, change-risk, change-verify, and plugin-creator — are available without installing anything. You describe what you want; the agent runs the underlying tessl change commands and shows you what it ran.
Prefer your own coding agent? Install the plugin into it with tessl install tessl/harness-engineering and the same skills become available there. The rest of this tutorial assumes the tessl agent as the base case.
How the tessl change command group works
tessl change groups three commands, each covering a separate concern:
tessl change review— runs a readonly agent against the current diff using the skills you specify, and emits a structured review (summary and inline comments keyed to GitHub hunk positions). The command never posts to GitHub; a separate publisher step does that.tessl change risk— scores the current diff against a checked-in policy and outputs a gate decision: does this PR require human review? The agent's risk judgment is advisory; the policy decides whether the PR is clearly low-risk enough to skip review, and requires a human whenever it is uncertain.tessl change verify— runs verifiers against changed files. Verifiers are LLM-as-judge checks for targeted, observable invariants — things a linter cannot express but a reviewer can score by reading the file. They run like linting checks in CI, and you can generate them from skills already in your repo (see Step 5).
Each command can be tried locally before you automate anything.
Concepts
Skills are the unit of code review knowledge. A skill contains instructions that guide the agent's analysis of a diff. Any skill in your repo can act as a review lens — not only ones explicitly built for review — and one call to tessl change review can run several skills in parallel and interlace their findings into one review.
Risk policy is a set of checked-in files under .github/pr-review-gate/ that define what makes a PR low-risk enough to skip human review. The agent's risk judgment is advisory; the policy decides the gate, and when in doubt it requires a human reviewer.
Verifiers are checks that describe binary, observable invariants about committed files — things like "API response handlers must use typed helpers" — that are hard to express as a lint rule but judgeable from the file. A verifier targets a glob of files, so new files added later are covered too. They are the right tool when a reviewer keeps flagging the same structural pattern and no deterministic check can own it.
Prerequisites
Tessl installed and initialized (
tessl init)Authenticated (
tessl login)Access to a workspace
Step 1: Try a code review locally
Before setting up automation, run a review on the current diff to see what output looks like.
The tessl agent already bundles the tessl/code-review skills, which provide several focused review lenses. Ask the agent to run a review:
Run a code review on my current diff using the code-legibility lens.
Under the hood the agent runs:
The --skill flag accepts three formats:
Registry ref:
workspace/plugin[@version]#skill-name— the#skill-nameselector is optional when the plugin has exactly one skillLocal path: a path to a
SKILL.mdfile or skill directory in this repoInstalled skill name: a bare name resolved against installed skills
To run multiple lenses in one call, repeat --skill. The CLI executes them in parallel and interlaces their findings into one structured output:
Available skills in tessl/code-review:
review-code-legibility
Whether names, types, return shapes, and abstractions are clear from the code alone
review-test-risk
Changed behaviour without meaningful tests, or brittle/uncovered async and error paths
review-contract-boundaries
API schemas, generated clients, CLI flags, event payloads, database migrations
review-security-risks
Auth, untrusted input, injection, secrets, crypto, sensitive logging
review-local-precedent
Whether new code should have reused an existing helper, component, or convention
To compare against a specific base commit, pass --base origin/main. To capture the structured data, add --json --output review.json.
Step 2: Create your own code review skill
The published skills are a starting point. Once you know what signals matter for your codebase, create a focused skill that captures project-specific patterns.
Ask the tessl agent to build it. The agent uses its plugin-creator skill to scaffold the plugin, interview you about scope, and validate the result:
Create a code review skill for this repo that flags breaking changes to our API schemas, generated clients, and route contracts. Put it in a plugin under the engteam workspace.
As it works, the agent runs the underlying CLI commands and reports them back. The ones you will see most often:
tessl plugin new— scaffolds the plugin and skill directory (reference)tessl plugin lint— checks packaging and schema (reference)tessl review— reviews the SKILL.md quality and can gate CI (reference)tessl plugin publish— publishes to the registry when the skill is stable (reference)
To iterate, ask the agent to run the skill against the current diff and tune the SKILL.md based on what the review misses or gets wrong:
Run my new review skill on the current diff, then sharpen the instructions for anything it flagged incorrectly.
Old PRs make good test cases. The tessl agent can check out or reconstruct a past PR's diff, run the skill against it, and compare the findings to what reviewers actually cared about — repeating until the skill is stable:
Backtest this review skill against PRs #1189 and #1201 and tell me where its findings differ from the human review comments.
Step 3: Wire the review into every PR
The tessl change review command emits structured review data only — it never posts to GitHub. To run it on every PR you need a GitHub Actions workflow that runs the command plus a publisher step that posts the single review with inline comments.
Rather than copy a fixed workflow file, ask the tessl agent to set it up. It reads how your repo is configured and calibrates the workflow accordingly:
Set up a code review for every new PR.
The agent (via its change-review skill) chooses sensible defaults. The ones worth knowing — and how you might change them:
One reviewer lens to start — it wires a single
--skill, because trust builds faster with one focused lens. Add more--skillvalues to the same run once you trust the output.An explicit base ref — a detached PR checkout often has no
origin/maintracking ref, so the workflow fetches it and passes--base. Without this the default base is unresolvable and the run fails.A gated manual re-run trigger — an
@tessl-change-reviewPR comment, restricted to repository insiders (owner, member, collaborator, admin) so external contributors cannot start a secret-backed run. Drop it if you only want automatic runs.One automatic review per PR — a starting cadence, not a rule. Move to every-push only when the added cost and noise are worth it.
Set TESSL_TOKEN (and ANTHROPIC_API_KEY) as repository secrets; GITHUB_TOKEN is provided automatically.
Step 4: Set up the risk gate
The risk gate decides whether a PR requires human review based on a checked-in policy, combining git measurements with an advisory agent judgment.
Ask the tessl agent to set it up — it uses its change-risk skill to initialize the policy, design it with you, and trial it before you rely on it:
Set up a PR risk gate for this repo.
The agent runs tessl change risk init, which writes starter files under .github/pr-review-gate/. Two starters are available:
conservative-starter(default) — requires human review for most changes; gradually relax as you verify the gate behaviorofficial-review-policy-parity— matches your existing branch protection rules more closely
Read and edit the policy files before relying on the gate. To score the current diff against the policy, the agent runs tessl change risk (add --base origin/main to compare against a base, --json for CI-friendly output). In CI, --fail-if-review-required exits non-zero when the gate decides a human reviewer is needed:
Add this to GitHub Actions as an advisory status check first. Watch it on real PRs for a few weeks before making it required. When the signal is trusted, enable it as a required status check in branch protection settings.
Step 5: Author and deploy verifiers
Verifiers check binary, observable invariants about committed files. Use them when a reviewer keeps flagging the same structural pattern and no linter can own it. Drive the whole flow through the tessl agent, which uses its change-verify skill.
Create a first verifier. Ask the agent for one targeted check:
Create a verifier that checks every Fastify route file returns via our typed response helpers.
The agent authors the verifier JSON and wires it into the verify block in tessl.json (see the verify block reference for the full schema). Before any broad judge run it previews the scope — tessl change verify lint <file> to check the structure, then tessl change verify --dry-run --all --show-files to confirm which files match.
Run that first verifier. Have the agent run just the new check on changed files and sample a few outputs so you can confirm the failures are real violations:
Generate more, then run them all. Once the first verifier earns trust, ask the agent to propose additional ones — often mined from your reviewer skills or recurring review feedback — and run the full set:
Suggest a few more verifiers from the patterns my reviewers keep flagging, then run them all on the current diff.
Put them into PR review. Finally, ask the agent to add verification as a CI gate:
Run verifiers on every PR.
The agent fetches the base ref and runs tessl change verify --base origin/main --github. The --github flag emits GitHub Actions annotations for warn-level findings so they appear in the PR UI even when the run exits 0. Start with verifiers set to warn severity in tessl.json while calibrating; promote to error (which makes the check blocking) only after you have confirmed the verifier avoids false positives on real PRs.
Next steps
Mine your PR review history for recurring patterns and turn them into new verifier rules or reviewer skill improvements with the Improving agent code quality tutorial.
Improve the quality of your reviewer skills with the
tessl/skill-optimizerplugin (pre-bundled with thetessl agent): ask the agent to review a SKILL.md, generate eval scenarios, run evals, and re-run until scores improve. See Improving your skills for the underlying review and eval capabilities.Once a verifier is validated, publish it alongside your reviewer skills as a single plugin so the whole review setup can be distributed across repositories.
Last updated