Task guides

Short, goal-shaped recipes for common jobs. Each guide points at the deeper feature pages; use those when you need full schemas or edge cases.

Related references: Hooks guide, Non-interactive mode, MCP, Skills, Memory, Branching, Sandbox.

Automate a check on every edit (hooks)

Goal: every time the agent finishes an edit, run a deterministic check and fail closed when it breaks.

The shipped hook model is a TypeScript module discovered under .veyyon/hooks/ (project) or ~/.veyyon/agent/hooks/ (user). The module exports a factory that registers handlers with pi.on(...).

// .veyyon/hooks/post-edit-check.ts
export default (pi) => {
  pi.on("PostToolUse", async (event) => {
    if (!/^(edit|write)$/.test(event.tool)) return;
    // run your check (spawn a test/linter) and block on failure
  });
};

The Bun runtime imports the module at startup; restart or /reload to pick up changes. See Hooks guide for the event names and handler contract.

Spec — not shipped: JSON hooks.json / config.yml hooks: tables and the { type: "command" } subprocess model with PreToolUse / PostToolUse matchers. Veyyon runs TS pi.on(...) modules, not external subprocess commands.

Run a bounded task from a script or CI

Use a one-shot prompt when the trigger lives outside the agent (pre-commit, CI, entr, watchexec):

$ veyyon --approval-mode auto-edit \
    "Run the focused tests for the files changed in the last commit and fail if any regress"

The prompt can be an argument or piped on stdin. Pick auto-edit for unattended write access with an exec prompt, or --yolo to auto-approve everything in a trusted, ideally externally-sandboxed environment. Keep the smoke set small; put heavy suites in CI.

Spec — not shipped: a dedicated veyyon exec subcommand with --json event streams, -o final-message capture, and veyyon review --uncommitted. See Non-interactive mode for the current scripted surface, and use /review in the TUI for a review pass.

Give the agent a new tool (MCP or skills)

Goal: teach Veyyon a capability you do not want to bake into the binary.

Choose the surface

Path 1: add an MCP server

Add it from the TUI, which writes mcp.json for you:

/mcp add

Or edit ~/.veyyon/agent/mcp.json (user) / .veyyon/mcp.json (project) directly:

{
  "mcpServers": {
    "database": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/db-mcp-server/index.js"],
      "env": { "DB_PATH": "/var/data/app.db" }
    }
  }
}

Confirm discovery with /mcp (or /mcp list), then ask the agent to use the new tool by name. If the server needs OAuth, run /mcp reauth <name>. Details: MCP, MCP setup.

Path 2: author a skill

Create a skill directory in user or project scope, for example ~/.veyyon/agent/skills/audit-config/SKILL.md (or .veyyon/skills/… in a repo):

---
name: audit-config
description: Audit Veyyon config.yml for unsafe approval and tool-policy combinations.
metadata:
  short-description: Config safety audit
---

# Audit config

When asked to audit configuration:
1. Read the active config.yml and any project overrides.
2. Flag `yolo` approval paired with broad tool allow-lists on untrusted repos.
3. Prefer concrete remediations over generic advice.

Restart or open a new session so skill discovery picks it up. Skills are data — you can version them in git and share them without shipping a new veyyon build. Prefer a skill when the “tool” is mostly prompting and local scripts; prefer MCP when the capability is a long-lived external process. See Skills.

Share context across sessions (memory and branching)

Goal: keep decisions, conventions, and alternate explorations available without pasting transcripts by hand.

Memory: carry guidance into new threads

Cross-session memory is off by default. Turn on a backend with memory.backend in config.yml:

# ~/.veyyon/agent/config.yml
memory:
  backend: mnemopi        # off (default), local, hindsight, mnemopi

Operate it from the TUI with /memory (/memory stats, /memory diagnose). Keep memory on for repos where conventions matter; leave it off for throwaway scratch sessions. See Memory.

Branching: explore without losing the main line

Use the session tree when you need parallel context inside one problem.

Typical flow: reach a decision point, /fork or /clone to try an alternate approach, and keep the branch worth keeping. Full behavior: Branching and Sessions.

Memory vs branching

• Memory shares durable, consolidated knowledge across different sessions and days.
• Branching shares live transcript context within or beside the current problem.
• Use both: branch to explore, then let memory capture the decision you kept.

See also

• Configuration for the keys these guides touch
• Examples for prompt-shaped tasks