Skip to content
Docs menu

Session templates and learned templates

Start a session from a saved setup (prompt, gear, mode, tools, checks) and save jobs you repeat as templates.

View .md

A template is a saved starting setup for a job you do again and again: a bug fix, a release, a migration, a dependency bump. It is a prompt with placeholders plus the session it should start: a gear, a permission mode, allow rules, plan-then-execute and checks to run at the end. The repository's reference is docs/templates.md.

Quick start

venom new                                   # list the templates
venom new bug-fix issue="checkout 500s when the cart is empty"
venom new dependency-bump package=vitest --model venom-smart

In a session: /template opens a picker, /template dependency-bump package=vitest runs one. venom new <template> [args] starts a normal session whose first message is /template <template> <args>, so every other flag works. A required placeholder you leave out is asked for on screen.

Where templates come from

A nearer source replaces a farther one of the same name:

Source Where Notes
project .venom/templates/<name>.md read only once you trust the project
yours ~/.venom/templates/<name>.md
your org the team library: a prompt tagged template hide one with library.hidden (Team library)
built in bug-fix, release, migration, dependency-bump, flaky-test-fix

The file

---
description: "Bump a dependency and fix what it breaks"
argument-hint: "package=<name> [to=<version>]"
params:
  - name: package
    description: "The package to bump"
    required: true
  - name: to
    default: latest
gear: eco
mode: accept-edits
tools: ["bash(npm install:*)"]
plan-exec: true
checks: ["npm test", "npm run lint"]
---
Bump {{package}} to {{to}} and fix what breaks.
Field What
description, argument-hint shown in lists and the picker
params name, description, required, default; used as {{name}}. $ARGUMENTS, $1 also work
gear switch to this gear (skipped with a notice if not available)
mode plan, default or accept-edits; never auto or yolo, and capped by your policy
tools allow rules for this session, in the permission engine's syntax
plan-exec plan first, approve, then run each step on a worker
checks commands the agent must run and fix before finishing; they go through the normal permission flow

Nothing in a template runs as a shell command, and a template gets no more power than your own allow rules would. Templates cost nothing until you run one: they never change the system prompt or tool list.

Learned templates

After you finish the same kind of job three times in 60 days (similar goals, same kinds of changed files, judged locally from your session summaries), venom makes one request to your gear's summary role (at most one a day, at most five drafts waiting) and writes a draft to ~/.venom/templates/proposed/. At your next start one line tells you. /template learn (or venom template learn) lets you save it for yourself or the project, edit it first, export it as a team-library draft, or dismiss that kind of job. Nothing is saved or shared without you. learn: false in venom.yaml turns detection off.

Commands

Command What
venom new [<template> [args…]] start a session from a template; no name lists them
venom template list [--json] templates and their source
venom template show <name> one template with its setup
venom template export <name> a team-library draft for any template
venom template learn drafts waiting for review
venom template learn show|accept|dismiss <name> [--project] review one draft
venom template learn export <name> a draft as a team-library proposal
/template [name] [args…], /template list, /template learn the same in a session