Session templates and issues
JSON templates in the repository that set a new session's harness, model, worktree, MCP servers, name and first prompt, and sessions started from a GitHub or GitLab issue.
A session template is a JSON file in the repository that sets up a new session: which harness and model its chat runs, whether it works in a new worktree, which MCP servers it gets, its name and its first prompt. Templates can read an open GitHub or GitLab issue, whose title, body, number and link fill their variables.
Where templates live
Templates are the .json files in .krad-ade/templates at the group's root folder. The file name, without .json, is the template's id: letters, digits, dashes, dots and underscores, not starting with a dot. Commit the folder to share the templates with everyone who works on the repository.
.krad-ade/
templates/
fix-issue.json
docs.jsonStart a session from a template
When a group has templates, the new session button opens the New session sheet instead of a blank chat. The command palette's New session from a template… opens it too.
- Blank session is a chat with the default model.
- Templates lists the group's templates. A template that opens a new worktree says "new worktree", and one that reads an issue says "asks for an issue". A file that does not parse shows "Not a valid template:" and the reason.
- From an issue… lists the open issues of the project; As variants… opens the variants draft.
Picking a template that asks for an issue goes on to the issue list first. The new session opens in the selected group with its chat on the template's harness and model, and sends the first prompt when there is one.
The format
{
"format": 1,
"name": "Fix an issue",
"harness": "ClaudeCode",
"model": "sonnet",
"worktree": { "branch": "fix/{{issue.slug}}" },
"mcp_servers": ["github"],
"session_name": "#{{issue.number}} {{issue.title}}",
"prompt": "Fix {{issue.url}} on the branch {{branch}}.\n\n{{issue.body}}\n\nAdd a test that fails before the fix."
}| Field | Required | Meaning |
|---|---|---|
format | Yes | The template format, 1. Another number is refused with "format N is not supported; this app reads format 1". |
name | Yes | The name shown in the sheet; it cannot be empty. |
harness | No | ClaudeCode, Codex, Opencode, Gateway or Acp:<id>. Shell is refused, since it cannot open a chat. |
model | No | The model id the chat starts with. |
worktree | No | An object; when present, the session works in a new worktree. Its optional branch is the branch name pattern. |
mcp_servers | No | Names of servers from Settings › MCP the chat starts with, instead of every server that is on. |
session_name | No | The session's name. |
prompt | No | The first message the chat sends. |
Unknown fields are refused, so a misspelt field shows as an invalid template rather than being ignored.
Variables
worktree.branch, session_name and prompt can hold variables written as {{name}}:
| Variable | Value |
|---|---|
{{issue.title}} | The issue's title |
{{issue.body}} | The issue's description |
{{issue.number}} | The issue's number |
{{issue.url}} | The issue's web address |
{{issue.slug}} | The title in lowercase ASCII words joined by dashes |
{{branch}} | The worktree branch the session got |
A variable with no value, such as an issue variable when no issue was picked, becomes empty. An unknown variable or a {{ that is never closed makes the template invalid. {{branch}} cannot be used inside worktree.branch itself.
What fills in when a field is left out
| Field | Without it |
|---|---|
session_name | #<number> <title> with an issue, otherwise the template's name |
worktree.branch | issue-<number>-<title slug> with an issue, otherwise a slug of the session name |
prompt | With an issue, "Work on issue #N: title", its body and an "Issue:" line with its link; without one, no first message |
Branch names are cut to 60 characters at a word boundary, with accents folded to plain letters. If no usable branch name comes out, the template does not start: "The template gives no usable worktree branch name".
Start from an issue
Sign in to the code host
The group's origin remote must point at a GitHub or GitLab project, and you must be signed in to that code host in Settings › Integrations. See Review.
Pick the issue
Run Start a session from an issue… from the command palette, or choose From an issue… in the New session sheet. Open issues lists the project's open issues.
Work on it
Without a template, the session uses the built-in Issue template: a new worktree named after the issue, the session named #<number> <title> and the issue as the first message.
If the remote is on no code host, the sheet says "The group's origin remote does not point at a GitLab or GitHub project"; if you are signed out, it asks you to sign in on the GitHub or GitLab page of Settings.