Agent configuration reference¶

An agent is a Markdown file in the agents directory (configured by agentsDir). The filename, without the .md extension, is the agent's ID — the value passed to --agentId in action commands.

You can see what agents are discoverable by running the list-agents command.

File format¶

The general structure of agent files is a subset of the Markdown structure that OpenCode uses.

Agent files use Markdown with YAML frontmatter:

---
model: "anthropic/claude-sonnet-4-6"
description: "A helpful assistant for code review"
temperature: 0.7
---
You are an expert code reviewer. Focus on correctness, clarity, and potential
security issues. Be concise and constructive.

The content after the closing --- is the system prompt sent to the model at the start of every run. Everything before and including the closing --- is frontmatter and is not sent to the model.

Frontmatter fields¶

model (required)¶

Format: provider/model-name

The model to use. The provider prefix determines which API credentials are used (configured in knosh.json).

description¶

Type: string
Default: none

A human-readable description of the agent's purpose. Shown by list-agents.

temperature¶

Type: number (0.0–1.0)
Default: none (model default)

Sampling temperature. Higher values produce more varied responses; lower values are more deterministic. Can be overridden at runtime with --temperature.

contextLength¶

Type: integer
Default: 131072

Maximum context length in tokens.

disable¶

Type: boolean
Default: false

When true, the agent is disabled. Any attempt to use it returns an error. Useful for temporarily disabling an agent without deleting the file.

permission¶

Restricts which tools the agent can use and which filesystem paths those tools may access. If permission is omitted, all tools are allowed with no path restrictions.

Tool permissions¶

Each tool can be given a simple allow/deny, or a list of path-based rules.

Simple form — allows or denies the tool entirely:

permission:
  text-write: "deny"
  web-fetch: "allow"

Pattern form — controls access by path. Rules are evaluated in order; the last matching rule wins. A "*" base rule is required to cover any paths not matched by more specific rules:

permission:
  text-write:
    "*": "deny"
    "/Users/alice/projects/my-app/*": "allow"
  text-edit:
    "*": "deny"
    "/Users/alice/projects/my-app/src/**": "allow"

For tools that take no filesystem paths (get-working-directory, web-fetch), only the simple form applies.

external_directory¶

Controls which absolute paths outside the project root the agent's filesystem tools may access. Deny wins: if any matching rule denies a path, access is refused even if another rule allows it. If no rule matches, access is refused.

Relative paths passed to tools are always allowed. ~ and $HOME are expanded before matching.

permission:
  external_directory:
    "~/.config/knosh/*": "allow"
    "/tmp/*": "allow"
    "*": "deny"

Available tool IDs¶

See the Tools reference for details on each tool.

Shared instructions (AGENTS.md)¶

In addition to an agent's own system prompt, Knosh looks for AGENTS.md files and appends their contents to the system prompt of every agent. This lets you define instructions that apply across all agents — global conventions, project-specific context, and the like — without repeating them in each agent file.

Knosh reads AGENTS.md from two locations, in this order:

1. The global config directory (~/.config/knosh/AGENTS.md)
2. The current working directory (./AGENTS.md)

Both are optional. The assembled system prompt is the agent's own prompt first, then the global AGENTS.md body, then the working-directory AGENTS.md body, with each part separated by a horizontal rule (---). Blank files are skipped.

If an AGENTS.md file begins with YAML frontmatter, the frontmatter is stripped and only the body is used.

This means you can keep machine-wide instructions in ~/.config/knosh/AGENTS.md and layer per-project instructions in a project's AGENTS.md, and both are merged into whatever agent you run.

Complete example¶

---
model: "anthropic/claude-sonnet-4-6"
description: "Read-only code reviewer restricted to the current project"
temperature: 0.5
contextLength: 200000
permission:
  text-write: "deny"
  text-edit: "deny"
  delete-file: "deny"
  move-content: "deny"
  create-directory: "deny"
  external_directory:
    "~/.config/knosh/*": "allow"
    "*": "deny"
---
You are an expert code reviewer. Analyze the code you are asked to review and
provide clear, actionable feedback. You may read any file in the project but
must not make any changes.