Schedules

No CI setup, no GitHub Actions config. Pick a plugin, a repo, and a time. Tessl runs it for you.

Takeaways:

• A schedule runs a plugin against a repo on a cron, with no CI or GitHub Actions config needed.
• You need a Tessl account, GitHub connected, a plugin, and an environment before you create one.
• Use --instructions to point a generic plugin at a specific job without creating a new plugin.
• The runs table shows five statuses; Agent Failed means the plumbing worked but the agent could not complete the task.

What is a schedule?

A schedule runs a plugin on a cron. You pick a plugin, a repo, and a time, and Tessl runs the plugin against that repo on that schedule. Each time the schedule fires, Tessl starts a cloud run and reports the result back so you can see what happened.

Tessl skips a tick if the previous run from the same schedule is still active when the next one would start. There is no queue: a skipped tick does not run later.

Think of it as two parts working together. The plugin describes the task: it tells the agent what to do. The schedule describes the timing: it tells Tessl when to do it.

What you need first

• A Tessl account with a workspace.
• GitHub connected to your workspace. See Connect Tessl to GitHub.
• A plugin that describes the task. See Create a plugin.
• An environment. A scheduled run cannot mint its own GitHub token, so it needs a GITHUB_TOKEN from its environment to check out your repo and open PRs. The environment also holds any other secrets the plugin needs. See Environments.

How to create a schedule

You can create a schedule from the CLI or from the web app. Both produce the same result.

CLI

Use tessl schedule create. Pass the plugin as the first argument, then the repo, the cron, and the environment:

tessl schedule create tessl/changelog-writer \
  --repo my-org/my-repo \
  --cron "0 9 * * 5" \
  --environment production

This runs the changelog-writer plugin against my-org/my-repo every Friday at 9:00 UTC.

Common flags:

Flag	What it does
--repo	The repository the plugin runs against. Required.
--cron	When the schedule fires, as a cron expression. Required.
--environment	The workspace environment the run executes in. It supplies the GitHub token and any other secrets or API keys the plugin needs. Required when you specify the plugin, repo, and environment directly.
--timezone	The timezone for the cron expression. Optional; defaults to UTC.
--agent	Which agent runs the plugin (for example claude-code, cursor, codex, tessl-agent). Optional.
--model	Which model the agent uses. Optional.
--instructions	Extra directions layered on top of the plugin for this schedule. Optional.
--base-branch	The branch to check out and open PRs against. Optional.

The cron expression has five fields: minute, hour, day of month, month, and day of week. 0 9 * * 5 means "at 9:00 UTC on every Friday". 0 8 * * * means "at 8:00 UTC every day".

Use --instructions to point a generic plugin at a specific job:

tessl schedule create tessl/docs-audit \
  --repo my-org/my-repo \
  --cron "0 8 * * *" \
  --environment production \
  --instructions "Focus on the API reference section only"

Web app

Open Automations > Schedules and choose Create schedule. The form asks for the schedule (cron), a name, a description, and an environment. These are the primary fields.

Below the environment and mode selection is an Advanced options control. Expand it to set the agent, model, inputs, instructions, and base branch. Leave it collapsed to accept the defaults.

How instructions work

The --instructions flag layers extra directions on top of whatever the plugin already says. The plugin is the base recipe; instructions are the per-schedule customization. The plugin still runs its normal task. The instructions steer it for this one schedule.

This lets you reuse one plugin for several jobs. The same docs-audit plugin, pointed two ways:

# Schedule 1: only the API reference
tessl schedule create tessl/docs-audit \
  --repo my-org/my-repo \
  --cron "0 8 * * 1" \
  --environment production \
  --instructions "Focus on the API reference section only"

# Schedule 2: only the getting-started guide
tessl schedule create tessl/docs-audit \
  --repo my-org/my-repo \
  --cron "0 8 * * 3" \
  --environment production \
  --instructions "Focus on the getting-started guide and its code samples"

Same plugin, two schedules, two different jobs.

Monitoring your runs

Each schedule keeps a table of its past runs. Open a schedule in the web app to see its full run history, including output and duration. From the CLI, tessl schedule runs <id> lists runs with their ID, status, skill, repo, workspace, creator, and creation time.

Status	What it means	What to do
In Progress	Still running	Wait
Completed	Agent finished and reported success	Nothing. Check the output.
Failed	The run hit an error before completing	Check the run's failure detail
Agent Failed	The run completed but the agent couldn't do the task	Check the output for why
Cancelled	Someone stopped the run	Nothing

Next steps

• Connect Tessl to GitHub
• Create a plugin
• Keep docs in sync
• Weekly changelog
• Review pattern mining
• Test health monitor
• Release readiness check