Commands, Layers, Agents, and Prompts

Octomind provides four mechanisms for extending AI capabilities beyond the base session.

Layers

Layers execute via ACP (Agent Client Protocol). Model, system prompt, and MCP tool access live in [[roles]] config — layers reference roles via the command field. Layers are workflow building blocks; commands are interactive layer shortcuts.

Configuration

[[layers]]
name = "task_refiner"
description = "Refines and clarifies user requests for better processing"
command = "octomind acp task_refiner"
input_mode = "last"
output_mode = "none"
output_role = "assistant"

Input Modes

How the layer receives conversation input:

Mode	Description
`"last"`	Only the last assistant/message from the session (default for workflow stages)
`"all"`	Entire conversation history from the session
`"summary"`	A summarized version of the conversation history

Output Modes

How the layer's output affects the session:

Mode	Description
`"none"`	Intermediate processing, doesn't modify session (for workflow stages like task_refiner)
`"append"`	Adds output as a new message to the session
`"replace"`	Replaces entire session content with layer output (reducer functionality)
`"last"`	Append only the last response to session (ignore multiple outputs)
`"restart"`	Replace session with only the last response (fresh start with last message)

Built-in Layers

The default configuration includes layers that reference built-in roles:

Layer	Command	Purpose
`task_refiner`	`octomind acp task_refiner`	Query cleanup and initial file guessing
`task_researcher`	`octomind acp task_researcher`	Context gathering via code analysis

Layer Fields

Field	Type	Required	Description
`name`	string	yes	Layer identifier
`description`	string	yes	Human-readable purpose (shown in help)
`command`	string	yes	ACP command to execute: `octomind acp <role_name>`
`workdir`	string	no	Working directory (default: `"."`)
`input_mode`	string	yes	`"last"`, `"all"`, or `"summary"`
`output_mode`	string	yes	`"none"`, `"append"`, `"replace"`, `"last"`, `"restart"`
`output_role`	string	no	`"assistant"` (default) or `"user"` — role for output messages

Key Architecture: Layers don't contain model/system/mcp config. Those live in [[roles]]. The command field references which role to spawn via ACP.

Example role definition (in config or from taps):

[[roles]]
name = "task_refiner"
model = "openrouter:openai/gpt-4.1-mini"
system = "You are a query processor..."
temperature = 0.3

[roles.mcp]
server_refs = []
allowed_tools = []

Custom Commands

Commands are layers triggered interactively via /run <name>. Same configuration as layers.

[[commands]]
name = "reduce"
description = "Compress session history for cost optimization during ongoing work"
command = "octomind acp reduce"
input_mode = "all"
output_mode = "replace"
output_role = "assistant"

Usage

/run              # List available commands
/run reduce       # Execute the reduce command

Layers vs Commands

Feature	Layer	Command
Triggered by	Workflows, code	User via `/run`
Config section	`[[layers]]`	`[[commands]]`
Interactive	No	Yes
Typical use	Pipeline stages	User-initiated actions

Both use identical configuration fields.

Agents

Agents are specialized AI instances that run as separate processes via ACP (Agent Client Protocol). Each agent becomes an MCP tool.

Configuration

[[agents]]
name = "context_gatherer"
description = "Gather detailed context from files and codebase."
command = "octomind acp context_gatherer"
workdir = "."

How Agents Work

Define agent in [[agents]] with name, description, and command
Agent becomes MCP tool agent_<name> (e.g., agent_context_gatherer)
When called, Octomind spawns the command as a child process
Communication happens via JSON-RPC over stdio (ACP protocol)
Agent's final response is returned as the tool result

Agent Fields

Field	Type	Required	Description
`name`	string	yes	Unique ID. Tool becomes `agent_<name>`.
`description`	string	yes	MCP tool description shown to AI
`command`	string	yes	Shell command starting ACP server over stdio
`workdir`	string	no	Working directory (default: `"."`)

Agent Tool Parameters

Each agent tool accepts:

task (string, required): Task description in human language
async (boolean, default: false): Run asynchronously

Async Agents

async: true returns immediately. Result appears as a user message when complete.

Use async when:

Task takes 30+ seconds
You can continue other work
You don't need the result immediately

Max concurrent async jobs is configurable. Jobs cancelled on session exit.

Dynamic Agents

Create agents at runtime using the agent MCP tool:

{"action": "add", "name": "reviewer", "description": "Code reviewer", "system": "You review code..."}
{"action": "enable", "name": "reviewer"}

See MCP Tools Reference.

Prompt Templates

Reusable prompts injected into the session via /prompt <name>.

[[prompts]]
name = "review"
description = "Request code review with focus on best practices"
prompt = """Please review the code above focusing on:
- Code quality and best practices
- Security considerations
- Performance implications"""

[[prompts]]
name = "explain"
description = "Ask for detailed explanation"
prompt = "Please provide a detailed explanation of the code/concept above."

[[prompts]]
name = "test"
description = "Request test cases"
prompt = """Please help create comprehensive tests:
- Unit test cases
- Edge cases and error conditions
- Integration test considerations"""

Usage

/prompt              # List available prompts
/prompt review       # Inject the review prompt