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. Patterns are ordinarily written relative to the working directory, so one agent file works unchanged across every project it is used in:

permission:
  text-write:
    "*": "deny"
    "src/*": "allow"
  text-edit:
    "*": "deny"
    "src/*": "allow"

A pattern is resolved before matching:

• A pattern starting with * or ? is used verbatim, unanchored — this is what keeps a bare "*" base rule matching every path, including paths outside the working directory.
• A pattern starting with /, ~, or $HOME is already anchored; ~ and $HOME are expanded against the user's home directory.
• Any other pattern — like "src/*" above — is resolved against the working directory.

* matches any number of path segments, so it already crosses /: "src/*" matches src/main/Foo.kt just as readily as src/Foo.kt. There is no separate deep-match syntax.

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

external_directory¶

Controls which paths outside the working directory the agent's filesystem tools may access. Every path a tool receives is resolved and lexically normalized against the working directory before this check runs, so .. segments cannot be used to escape the working directory undetected. A path that resolves inside the working directory is always allowed, with no rule required. A path that resolves outside must match an external_directory rule: deny wins — if any matching rule denies the path, access is refused even if another rule allows it — and if no rule matches, access is refused.

~ and $HOME are expanded before matching. Symlinks are not resolved; a symlink whose target lies outside the working directory is not currently detected by this check. Real-path (symlink-aware) containment is a documented follow-up, not yet implemented.

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

Available tool IDs¶

See the Tools reference for details on each tool.

mcp¶

Type: map of server handle (or glob) → boolean
Default: none (no overrides; every server uses its global enabled value)

Overrides the global enabled state of MCP servers for this agent. Each key names an MCP server handle from knosh.json, or a glob (containing * or ?) matching several handles; each value is a plain boolean turning that server on or off for this agent, independent of the global setting. This applies identically to local and remote servers — an override key or glob matches on the server handle alone, regardless of type. Use list-mcp --agent to inspect the resolved effective state.

mcp:
  github: false
  "test-*": true

Precedence: an exact handle key always wins over a glob. Among multiple matching globs, the last one in YAML source order wins. A key that is neither an exact handle nor matched by any server is an error only when it is an exact (non-glob) key naming no configured server — an unmatched glob is not an error.

Validation: a non-boolean value, or an exact key naming no configured server, throws a configuration error when the agent loads.

There is no separate per-tool gate for MCP tools: toggling a server off here (or globally) withholds all of that server's tools from this agent. tools:'s built-in-only allowlist (above) does not apply to MCP tools; server-level enable/disable is the only lever an agent config has over them.

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.