ViberglassViberglassDocs
← Back to site

Claws (Scheduled Tasks)

A claw is a recurring task. Where a ticket is a one-shot work item driven by a person, a claw runs on its own, on a schedule, against the same instructions every time. Use claws for the things you want to happen automatically: dependency updates, weekly housekeeping, periodic dependency security audits, or anything else you would otherwise add to a cron job.

Each project has its own claws page, which you reach from the project sidebar under Claws.

The two halves of a claw

The Claws page has two tabs:

  • Schedules — when and how often to run.
  • Task Templates — what to run.

The two are decoupled. You build the work once as a task template and then attach as many schedules to it as you like. Multiple schedules can share a template (for example, an hourly health check during business hours plus a nightly deep scan), and one schedule belongs to exactly one template.

Task templates

A task template is the unit of "what". To create one, open Task Templates and click New Template. Fill in:

  • Name — the human label, shown in lists and on schedules.
  • Description (optional) — a one-line summary.
  • Clanker — which clanker should run the task. The clanker decides the agent (Claude Code, Codex, Gemini CLI, etc.) and where it runs (Lambda, ECS, Docker).
  • Task instructions — the prompt body. Describe what the agent should do every time the task runs. This is the prompt that drives every execution; keep it self-contained.
  • Credentials — the secrets that should be injected into the worker alongside the clanker's own credentials. Tick the secrets the task needs (for example, GITHUB_TOKEN for git operations and MINIMAX_API_KEY for the LLM).

When editing an existing template, leaving Task instructions blank keeps the previously stored instructions. The form deliberately doesn't show the existing prompt to discourage accidental clobbering.

Schedules

A schedule is the unit of "when". On the Schedules tab click New Schedule and fill in:

  • Name — the schedule label.
  • Description (optional).
  • Task template — which task template to run.
  • Schedule type — pick Interval for simple recurring runs, or Cron for fine-grained control.
  • Interval — when schedule type is Interval: a number plus a unit. The unit dropdown supports Minutes, Hours, Days, and Weeks. For example, 1 Hours or 7 Days.
  • Cron expression — when schedule type is Cron: a 6-field cron expression with explicit seconds (sec min hour day month dow). Example: 0 0 9 * * 1-5 runs at 9:00 every weekday.
  • Timezone — defaults to UTC. Use a tz database name like America/New_York if you want runs anchored to a local timezone.

Schedules can be Active or Paused. Use the Pause action in the schedule row to temporarily stop runs without losing the schedule definition; click Resume to start it again.

Watching claws run

Each scheduled execution becomes a job with kind = claw, visible in the project's Jobs page alongside other agent runs. The schedules table shows run counts and failure counts per schedule.

Webhook notifications

A schedule can optionally fire a webhook on started, completed, and failed events. Use this to notify Slack, PagerDuty, or your own services when a claw runs or fails. The webhook configuration lives on the schedule itself; ask your admin to enable the feature if you don't see the option in the form.

A typical example

A "Daily Dependency update" claw might look like this:

  • Task Template — Update Dependencies, clanker OpenCode Minimax, instructions: "Run the dependency upgrade workflow on the linked repository, open a pull request with the changes, and summarise the upgrades in the PR body." Credentials: MINIMAX_API_KEY, GITHUB_TOKEN.
  • Schedule — Daily Dependency update, type Interval, value 1 Days, timezone UTC.

That's it. The schedule fires every 24 hours, the worker boots, runs the task, and opens a PR (or skips when nothing needs upgrading).

Tips

  • Re-use templates. A single "Run unit tests" template can power many schedules — hourly during the day, daily after hours, or on demand from a one-off ticket.
  • Pin secrets explicitly. Only the secrets you tick are injected into the worker. Forgetting GITHUB_TOKEN is the most common reason a dependency-update claw fails to push its branch.
  • Match the timezone to your team. Cron expressions in UTC work fine if your team thinks in UTC; otherwise switch the schedule to your office timezone so the cron times match the wall clock.
  • Mind interval drift. Interval schedules count from the last completed run, not from a fixed wall-clock anchor. Use cron when you need a specific time of day.
Next
Secrets