Guide

Subagents

The model can delegate work to subagents with the task tool. Each subagent gets a fresh context window, its own system prompt and a restricted tool set. Only its final message comes back, so broad searches and self-contained changes don't fill the main context. Several task calls in one turn run in parallel.

Built-in agents:

• general-purpose: all tools. Runs on the worker role.
• explore: read-only search with read, grep and glob. Runs on the explore role.

Both use the main model until those roles are set (see Mixing cheap and strong models).

To add your own, write <name>.md in .larik/agents/ or .claude/agents/, or in ~/.config/larik/agents/ or ~/.claude/agents/. The format is the same as Claude Code's, and a definition overrides a built-in with the same name:

---
name: reviewer
description: Reviews a diff for bugs and missing tests. Use after making changes.
tools: Read, Grep, Glob, Bash # optional; omit for all tools. mcp__<server> allows a whole server
model: worker # optional: inherit (default), a role (worker, explore, smart, opus/sonnet/haiku, your own), or provider/model
isolation: worktree # optional: always run in its own git worktree
---

You are a meticulous code reviewer. ...

What subagents share with the main agent:

• Permissions: the same rules and mode. Plan mode keeps subagents read-only too, and a subagent's permission prompts appear in your UI, labelled with the subagent and queued when several ask at once.
• Hooks: the same hooks, with SubagentStop in place of Stop.
• Checkpoints: the same store, so /undo reverts subagent edits along with the turn. Worktree subagents are the exception (see below).

Other behavior:

• Subagent tool calls are shown nested under their task. Their cost is included in the session totals, and each subagent's transcript is saved next to the session file.
• Subagents can't start further subagents.

Worktree isolation: inside a git repository, task accepts isolation: "worktree", or an agent definition can set it. The subagent then works in its own git worktree on a new branch larik/task-xxxxxx, so parallel agents never overwrite each other's edits or yours.

• Where it runs: the worktree is created under ~/.local/share/larik/worktrees/ from the current HEAD commit. Uncommitted changes in your checkout are not included. The subagent's working directory, path permissions and relative paths all point into the worktree.
• Confinement: file writes outside the worktree ask for permission, as for any path outside the working directory. When the sandbox is on, bash may write only to the worktree and to the repository's .git, so commits work. .git/hooks, .git/config and the other git files that choose which code git runs stay read-only.
• Finishing: when the subagent ends, leftover changes are committed on its branch.
  • If nothing changed, the worktree and branch are deleted.
  • Otherwise both are kept, and the result tells the main agent the branch name, the changed files, and how to review (git diff base...branch), merge and clean up. Nothing reaches your working tree until someone merges.
• Not shared: worktree subagents skip /undo checkpoints (the branch is the undo) and don't use the lsp tool, because the language servers index your checkout.
• Cleanup: /worktrees lists kept worktrees and how many commits each has that aren't in HEAD. /worktrees remove <branch|all> deletes a worktree and its branch.

Background subagents:

• Starting one: with run_in_background: true, task returns an ID (bg-1) immediately and the main agent keeps working.
• Delivery: when the subagent finishes, its result reaches the model as a <task-notification>. If the agent is mid-turn, the notification rides along with its next request. If the agent is idle, Larik starts a short turn automatically so the model can act on it.
• Tools for the model: task_wait blocks on specific tasks (or all of them) and returns their results. task_stop cancels one.
• Lifetime: background tasks survive Esc on the foreground turn. /tasks lists them, /tasks stop <id> cancels one, and quitting stops them all.
• Visibility: the status bar shows how many are running, and their permission prompts appear even while the agent is idle.
• Limits: at most 8 run at once. In -p mode Larik exits only after every background task has finished and been delivered.
• The task call itself never asks for permission; each tool call inside the subagent is checked on its own.
• /agents lists the available agents.