Tasks

A task is a shell command you can run from the editor and rerun with a keystroke. Output goes to the terminal. Tasks can read a few values from the editor, such as the current file or the selected text.

Run a task

cmd-shift-r opens the task list (Spawn Task in the Run menu). Pick a task and press enter.
cmd-alt-r reruns the last task.
ctrl-alt-shift-r opens the task list and shows the output in the center of the window.

The list contains your tasks plus tasks that language support adds, such as test runners for the current file. Type a command into the box and press alt-enter to run it once without saving it. Press tab on a task to copy its command into the box and edit it first.

By default a rerun reuses the same terminal and waits for the previous run to finish.

Define tasks

Tasks live in a tasks.json file. Edit your global tasks with tyrn: open tasks, or the project’s with tyrn: open project tasks (also Edit tasks.json… in the Run menu).

Global: ~/.config/tyrn/tasks.json. Available in every project.
Project: .tyrn/tasks.json. Available in that project only.

[
  {
    "label": "Run tests for this file",
    "command": "npm",
    "args": ["test", "--", "$ZED_RELATIVE_FILE"],
    "cwd": "$ZED_WORKTREE_ROOT",
    "env": { "CI": "1" },
    "use_new_terminal": false,
    "allow_concurrent_runs": false,
    "reveal": "always",
    "hide": "never",
    "save": "current"
  }
]

Field	What it does
`label`	Name shown in the list. Required.
`command`, `args`	What to run
`cwd`	Working folder. Defaults to the project root.
`env`	Extra environment variables
`use_new_terminal`	Open a new terminal tab for each run. Default `false`.
`allow_concurrent_runs`	Allow several runs at once. Default `false`.
`reveal`	After start: `"always"` (default), `"no_focus"` or `"never"`
`hide`	After finish: `"never"` (default), `"always"` or `"on_success"`
`shell`	`"system"` (default), `{ "program": "sh" }` or `{ "with_arguments": { "program": "/bin/bash", "args": ["--login"] } }`
`show_summary`, `show_command`	Show the task line and command line in the output. Default `true`.
`save`	Save before running: `"all"`, `"current"` or `"none"`
`tags`	Attach the task to runnable markers. See below.

Tasks run in a login shell, so your shell profile is loaded. To change the shell, set terminal.shell.

Variables

Use environment-style variables in command, args, cwd and label. Write them exactly as shown.

Variable	Value
`$ZED_FILE`	Absolute path of the open file
`$ZED_FILENAME`	File name
`$ZED_DIRNAME`	Absolute path of the file’s folder
`$ZED_RELATIVE_FILE`	Path relative to the project root
`$ZED_RELATIVE_DIR`	Folder path relative to the project root
`$ZED_STEM`	File name without extension
`$ZED_ROW`, `$ZED_COLUMN`	Cursor line and column
`$ZED_SYMBOL`	The symbol at the cursor, as in the breadcrumbs
`$ZED_SELECTED_TEXT`	The selected text
`$ZED_LANGUAGE`	Language of the open file
`$ZED_WORKTREE_ROOT`	Root folder of the project
`$ZED_MAIN_GIT_WORKTREE`	The main checkout, which differs from the root in a linked git worktree

Give a default with ${ZED_SELECTED_TEXT:no text selected}. A task that uses a variable with no value, and no default, is hidden from the list.

Quote paths that may contain spaces. Pass them as an argument ("args": ["$ZED_FILE"]) or escape quotes in the command string.

Bind a task to a key

[
  {
    "context": "Workspace",
    "bindings": {
      "alt-g": ["task::Spawn", { "task_name": "Run tests for this file" }],
      "alt-t": ["task::Rerun", { "reevaluate_context": true }]
    }
  }
]

By default a rerun reuses the values captured the first time. reevaluate_context reads the current file and selection again. Add "reveal_target": "center" to task::Spawn to show the output in the center area.

Runnable markers

Language support can mark runnable code, such as tests, with an indicator. Run it from code actions (cmd-.). To make a marker run your own task, add the marker’s name to the task’s tags. Project tasks win over global ones, and both win over language defaults.

Hooks

A task with "hooks": ["create_worktree"] runs automatically after Tyrn creates a linked git worktree. It runs with $ZED_WORKTREE_ROOT set to the new worktree and $ZED_MAIN_GIT_WORKTREE set to the original checkout.

[
  {
    "label": "copy .env into new worktree",
    "command": "cp",
    "args": ["$ZED_MAIN_GIT_WORKTREE/.env", "$ZED_WORKTREE_ROOT/.env"],
    "hooks": ["create_worktree"],
    "reveal": "no_focus",
    "hide": "on_success"
  }
]

See Run sessions in parallel for how worktrees fit into agent work.

Settings

{
  "tasks": {
    "enabled": true,
    "prefer_lsp": true,
    "variables": {}
  }
}

prefer_lsp shows tasks from language servers ahead of the ones built into language support.

Shell scripts

Open a .sh or .bash file and the script appears in the task list, tagged bash-script.