> ## Documentation Index
> Fetch the complete documentation index at: https://tesser.sh/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Working with an agent

> Install the tesser skill so Claude Code or Codex can run the boxes for you

Tesser is designed to be driven by a coding agent. The agent edits files on
your laptop as it normally does, and when it needs to run something it calls
`tesser` the same way it would call `git` or `pnpm`. You watch the result in
the browser.

## Install the skill

```sh theme={"theme":"css-variables"}
tesser skill install
```

This writes `~/.claude/skills/tesser/SKILL.md`, which Claude Code loads for
every project. If you would rather keep the skill in the repository,
`tesser skill install --project` writes it to `.claude/skills/tesser/` in the
current worktree, which is the same directory the service manifests live in.
Committing it gives every teammate's agent the same instructions. For an
agent other than Claude Code, `tesser skill print` writes the skill to stdout
so you can place it wherever that agent reads instructions.

## What the skill tells the agent

The skill is a single page describing the commands and the rules around
them. The most important rules are:

* Commands that create or select a box print only the box id on stdout, so
  the agent can capture it with `BOX=$(tesser dev web)`. Progress messages go
  to stderr.
* `tesser exec -- <cmd>` runs on the worktree's workbench, which never runs a
  dev server. Tests, typechecks, and installs belong there.
* Files are edited on the laptop and never on the box, because the next sync
  overwrites the box's copy.
* `stop` and `rm` do not ask for confirmation, and `rm` cannot be undone.

## What you do

You start `tesser daemon` once and leave it running, and you open
localhost:3000 when the agent tells you a server is up. Every page served
through the daemon has a small panel in its corner that lists your boxes, so
when the agent has several branches running you can switch between them
without using the terminal.

If the agent reports that localhost:3000 refuses connections, the daemon is
not running. The agent cannot start it for you.

## A typical session

```sh theme={"theme":"css-variables"}
tesser exec -- pnpm install
tesser exec -- pnpm test
BOX=$(tesser dev web)          # the agent tells you to open http://localhost:3000
# the agent edits files, then:
tesser sync "$BOX"
tesser logs "$BOX" -f          # to read the dev server's output
tesser rm "$BOX"               # when the branch is finished
```