@neocode-ai/web 1.1.1

package/src/content/docs/agents.mdx

@@ -0,0 +1,720 @@
+---
+title: Agents
+description: Configure and use specialized agents.
+---
+
+Agents are specialized AI assistants that can be configured for specific tasks and workflows. They allow you to create focused tools with custom prompts, models, and tool access.
+
+:::tip
+Use the plan agent to analyze code and review suggestions without making any code changes.
+:::
+
+You can switch between agents during a session or invoke them with the `@` mention.
+
+---
+
+## Types
+
+There are two types of agents in NeoCode; primary agents and subagents.
+
+---
+
+### Primary agents
+
+Primary agents are the main assistants you interact with directly. You can cycle through them using the **Tab** key, or your configured `switch_agent` keybind. These agents handle your main conversation. Tool access is configured via permissions — for example, Build has all tools enabled while Plan is restricted.
+
+:::tip
+You can use the **Tab** key to switch between primary agents during a session.
+:::
+
+NeoCode comes with two built-in primary agents, **Build** and **Plan**. We'll
+look at these below.
+
+---
+
+### Subagents
+
+Subagents are specialized assistants that primary agents can invoke for specific tasks. You can also manually invoke them by **@ mentioning** them in your messages.
+
+NeoCode comes with two built-in subagents, **General** and **Explore**. We'll look at this below.
+
+---
+
+## Built-in
+
+NeoCode comes with two built-in primary agents and two built-in subagents.
+
+---
+
+### Build
+
+_Mode_: `primary`
+
+Build is the **default** primary agent with all tools enabled. This is the standard agent for development work where you need full access to file operations and system commands.
+
+---
+
+### Plan
+
+_Mode_: `primary`
+
+A restricted agent designed for planning and analysis. We use a permission system to give you more control and prevent unintended changes.
+By default, all of the following are set to `ask`:
+
+- `file edits`: All writes, patches, and edits
+- `bash`: All bash commands
+
+This agent is useful when you want the LLM to analyze code, suggest changes, or create plans without making any actual modifications to your codebase.
+
+---
+
+### General
+
+_Mode_: `subagent`
+
+A general-purpose agent for researching complex questions and executing multi-step tasks. Has full tool access (except todo), so it can make file changes when needed. Use this to run multiple units of work in parallel.
+
+---
+
+### Explore
+
+_Mode_: `subagent`
+
+A fast, read-only agent for exploring codebases. Cannot modify files. Use this when you need to quickly find files by patterns, search code for keywords, or answer questions about the codebase.
+
+---
+
+## Usage
+
+1. For primary agents, use the **Tab** key to cycle through them during a session. You can also use your configured `switch_agent` keybind.
+
+2. Subagents can be invoked:
+   - **Automatically** by primary agents for specialized tasks based on their descriptions.
+   - Manually by **@ mentioning** a subagent in your message. For example.
+
+     ```txt frame="none"
+     @general help me search for this function
+     ```
+
+3. **Navigation between sessions**: When subagents create their own child sessions, you can navigate between the parent session and all child sessions using:
+   - **\<Leader>+Right** (or your configured `session_child_cycle` keybind) to cycle forward through parent → child1 → child2 → ... → parent
+   - **\<Leader>+Left** (or your configured `session_child_cycle_reverse` keybind) to cycle backward through parent ← child1 ← child2 ← ... ← parent
+
+   This allows you to seamlessly switch between the main conversation and specialized subagent work.
+
+---
+
+## Configure
+
+You can customize the built-in agents or create your own through configuration. Agents can be configured in two ways:
+
+---
+
+### JSON
+
+Configure agents in your `neocode.json` config file:
+
+```json title="neocode.json"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "agent": {
+    "build": {
+      "mode": "primary",
+      "model": "anthropic/claude-sonnet-4-20250514",
+      "prompt": "{file:./prompts/build.txt}",
+      "tools": {
+        "write": true,
+        "edit": true,
+        "bash": true
+      }
+    },
+    "plan": {
+      "mode": "primary",
+      "model": "anthropic/claude-haiku-4-20250514",
+      "tools": {
+        "write": false,
+        "edit": false,
+        "bash": false
+      }
+    },
+    "code-reviewer": {
+      "description": "Reviews code for best practices and potential issues",
+      "mode": "subagent",
+      "model": "anthropic/claude-sonnet-4-20250514",
+      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
+      "tools": {
+        "write": false,
+        "edit": false
+      }
+    }
+  }
+}
+```
+
+---
+
+### Markdown
+
+You can also define agents using markdown files. Place them in:
+
+- Global: `~/.config/neocode/agents/`
+- Per-project: `.neocode/agents/`
+
+```markdown title="~/.config/neocode/agents/review.md"
+---
+description: Reviews code for quality and best practices
+mode: subagent
+model: anthropic/claude-sonnet-4-20250514
+temperature: 0.1
+tools:
+  write: false
+  edit: false
+  bash: false
+---
+
+You are in code review mode. Focus on:
+
+- Code quality and best practices
+- Potential bugs and edge cases
+- Performance implications
+- Security considerations
+
+Provide constructive feedback without making direct changes.
+```
+
+The markdown file name becomes the agent name. For example, `review.md` creates a `review` agent.
+
+---
+
+## Options
+
+Let's look at these configuration options in detail.
+
+---
+
+### Description
+
+Use the `description` option to provide a brief description of what the agent does and when to use it.
+
+```json title="neocode.json"
+{
+  "agent": {
+    "review": {
+      "description": "Reviews code for best practices and potential issues"
+    }
+  }
+}
+```
+
+This is a **required** config option.
+
+---
+
+### Temperature
+
+Control the randomness and creativity of the LLM's responses with the `temperature` config.
+
+Lower values make responses more focused and deterministic, while higher values increase creativity and variability.
+
+```json title="neocode.json"
+{
+  "agent": {
+    "plan": {
+      "temperature": 0.1
+    },
+    "creative": {
+      "temperature": 0.8
+    }
+  }
+}
+```
+
+Temperature values typically range from 0.0 to 1.0:
+
+- **0.0-0.2**: Very focused and deterministic responses, ideal for code analysis and planning
+- **0.3-0.5**: Balanced responses with some creativity, good for general development tasks
+- **0.6-1.0**: More creative and varied responses, useful for brainstorming and exploration
+
+```json title="neocode.json"
+{
+  "agent": {
+    "analyze": {
+      "temperature": 0.1,
+      "prompt": "{file:./prompts/analysis.txt}"
+    },
+    "build": {
+      "temperature": 0.3
+    },
+    "brainstorm": {
+      "temperature": 0.7,
+      "prompt": "{file:./prompts/creative.txt}"
+    }
+  }
+}
+```
+
+If no temperature is specified, NeoCode uses model-specific defaults; typically 0 for most models, 0.55 for Qwen models.
+
+---
+
+### Max steps
+
+Control the maximum number of agentic iterations an agent can perform before being forced to respond with text only. This allows users who wish to control costs to set a limit on agentic actions.
+
+If this is not set, the agent will continue to iterate until the model chooses to stop or the user interrupts the session.
+
+```json title="neocode.json"
+{
+  "agent": {
+    "quick-thinker": {
+      "description": "Fast reasoning with limited iterations",
+      "prompt": "You are a quick thinker. Solve problems with minimal steps.",
+      "steps": 5
+    }
+  }
+}
+```
+
+When the limit is reached, the agent receives a special system prompt instructing it to respond with a summarization of its work and recommended remaining tasks.
+
+:::caution
+The legacy `maxSteps` field is deprecated. Use `steps` instead.
+:::
+
+---
+
+### Disable
+
+Set to `true` to disable the agent.
+
+```json title="neocode.json"
+{
+  "agent": {
+    "review": {
+      "disable": true
+    }
+  }
+}
+```
+
+---
+
+### Prompt
+
+Specify a custom system prompt file for this agent with the `prompt` config. The prompt file should contain instructions specific to the agent's purpose.
+
+```json title="neocode.json"
+{
+  "agent": {
+    "review": {
+      "prompt": "{file:./prompts/code-review.txt}"
+    }
+  }
+}
+```
+
+This path is relative to where the config file is located. So this works for both the global NeoCode config and the project specific config.
+
+---
+
+### Model
+
+Use the `model` config to override the model for this agent. Useful for using different models optimized for different tasks. For example, a faster model for planning, a more capable model for implementation.
+
+:::tip
+If you don’t specify a model, primary agents use the [model globally configured](/docs/config#models) while subagents will use the model of the primary agent that invoked the subagent.
+:::
+
+```json title="neocode.json"
+{
+  "agent": {
+    "plan": {
+      "model": "anthropic/claude-haiku-4-20250514"
+    }
+  }
+}
+```
+
+The model ID in your NeoCode config uses the format `provider/model-id`. For example, if you're using [NeoCode Zen](/docs/zen), you would use `neocode/gpt-5.1-codex` for GPT 5.1 Codex.
+
+---
+
+### Tools
+
+Control which tools are available in this agent with the `tools` config. You can enable or disable specific tools by setting them to `true` or `false`.
+
+```json title="neocode.json" {3-6,9-12}
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "tools": {
+    "write": true,
+    "bash": true
+  },
+  "agent": {
+    "plan": {
+      "tools": {
+        "write": false,
+        "bash": false
+      }
+    }
+  }
+}
+```
+
+:::note
+The agent-specific config overrides the global config.
+:::
+
+You can also use wildcards to control multiple tools at once. For example, to disable all tools from an MCP server:
+
+```json title="neocode.json"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "agent": {
+    "readonly": {
+      "tools": {
+        "mymcp_*": false,
+        "write": false,
+        "edit": false
+      }
+    }
+  }
+}
+```
+
+[Learn more about tools](/docs/tools).
+
+---
+
+### Permissions
+
+You can configure permissions to manage what actions an agent can take. Currently, the permissions for the `edit`, `bash`, and `webfetch` tools can be configured to:
+
+- `"ask"` — Prompt for approval before running the tool
+- `"allow"` — Allow all operations without approval
+- `"deny"` — Disable the tool
+
+```json title="neocode.json"
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "permission": {
+    "edit": "deny"
+  }
+}
+```
+
+You can override these permissions per agent.
+
+```json title="neocode.json" {3-5,8-10}
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "permission": {
+    "edit": "deny"
+  },
+  "agent": {
+    "build": {
+      "permission": {
+        "edit": "ask"
+      }
+    }
+  }
+}
+```
+
+You can also set permissions in Markdown agents.
+
+```markdown title="~/.config/neocode/agents/review.md"
+---
+description: Code review without edits
+mode: subagent
+permission:
+  edit: deny
+  bash:
+    "*": ask
+    "git diff": allow
+    "git log*": allow
+    "grep *": allow
+  webfetch: deny
+---
+
+Only analyze code and suggest changes.
+```
+
+You can set permissions for specific bash commands.
+
+```json title="neocode.json" {7}
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "agent": {
+    "build": {
+      "permission": {
+        "bash": {
+          "git push": "ask",
+          "grep *": "allow"
+        }
+      }
+    }
+  }
+}
+```
+
+This can take a glob pattern.
+
+```json title="neocode.json" {7}
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "agent": {
+    "build": {
+      "permission": {
+        "bash": {
+          "git *": "ask"
+        }
+      }
+    }
+  }
+}
+```
+
+And you can also use the `*` wildcard to manage permissions for all commands.
+Since the last matching rule takes precedence, put the `*` wildcard first and specific rules after.
+
+```json title="neocode.json" {8}
+{
+  "$schema": "https://neo.khulnasoft.com/config.json",
+  "agent": {
+    "build": {
+      "permission": {
+        "bash": {
+          "*": "ask",
+          "git status *": "allow"
+        }
+      }
+    }
+  }
+}
+```
+
+[Learn more about permissions](/docs/permissions).
+
+---
+
+### Mode
+
+Control the agent's mode with the `mode` config. The `mode` option is used to determine how the agent can be used.
+
+```json title="neocode.json"
+{
+  "agent": {
+    "review": {
+      "mode": "subagent"
+    }
+  }
+}
+```
+
+The `mode` option can be set to `primary`, `subagent`, or `all`. If no `mode` is specified, it defaults to `all`.
+
+---
+
+### Hidden
+
+Hide a subagent from the `@` autocomplete menu with `hidden: true`. Useful for internal subagents that should only be invoked programmatically by other agents via the Task tool.
+
+```json title="neocode.json"
+{
+  "agent": {
+    "internal-helper": {
+      "mode": "subagent",
+      "hidden": true
+    }
+  }
+}
+```
+
+This only affects user visibility in the autocomplete menu. Hidden agents can still be invoked by the model via the Task tool if permissions allow.
+
+:::note
+Only applies to `mode: subagent` agents.
+:::
+
+---
+
+### Task permissions
+
+Control which subagents an agent can invoke via the Task tool with `permission.task`. Uses glob patterns for flexible matching.
+
+```json title="neocode.json"
+{
+  "agent": {
+    "orchestrator": {
+      "mode": "primary",
+      "permission": {
+        "task": {
+          "*": "deny",
+          "orchestrator-*": "allow",
+          "code-reviewer": "ask"
+        }
+      }
+    }
+  }
+}
+```
+
+When set to `deny`, the subagent is removed from the Task tool description entirely, so the model won't attempt to invoke it.
+
+:::tip
+Rules are evaluated in order, and the **last matching rule wins**. In the example above, `orchestrator-planner` matches both `*` (deny) and `orchestrator-*` (allow), but since `orchestrator-*` comes after `*`, the result is `allow`.
+:::
+
+:::tip
+Users can always invoke any subagent directly via the `@` autocomplete menu, even if the agent's task permissions would deny it.
+:::
+
+---
+
+### Color
+
+Customize the agent's visual appearance in the UI with the `color` option. This affects how the agent appears in the interface.
+
+```json title="neocode.json"
+{
+  "agent": {
+    "creative": {
+      "color": "#ff6b6b"
+    }
+  }
+}
+```
+
+Must be a valid hex color code like `#FF5733`.
+
+---
+
+### Top P
+
+Control response diversity with the `top_p` option. Alternative to temperature for controlling randomness.
+
+```json title="neocode.json"
+{
+  "agent": {
+    "brainstorm": {
+      "top_p": 0.9
+    }
+  }
+}
+```
+
+Values range from 0.0 to 1.0. Lower values are more focused, higher values more diverse.
+
+---
+
+### Additional
+
+Any other options you specify in your agent configuration will be **passed through directly** to the provider as model options. This allows you to use provider-specific features and parameters.
+
+For example, with OpenAI's reasoning models, you can control the reasoning effort:
+
+```json title="neocode.json" {6,7}
+{
+  "agent": {
+    "deep-thinker": {
+      "description": "Agent that uses high reasoning effort for complex problems",
+      "model": "openai/gpt-5",
+      "reasoningEffort": "high",
+      "textVerbosity": "low"
+    }
+  }
+}
+```
+
+These additional options are model and provider-specific. Check your provider's documentation for available parameters.
+
+:::tip
+Run `neocode models` to see a list of the available models.
+:::
+
+---
+
+## Create agents
+
+You can create new agents using the following command:
+
+```bash
+neocode agent create
+```
+
+This interactive command will:
+
+1. Ask where to save the agent; global or project-specific.
+2. Description of what the agent should do.
+3. Generate an appropriate system prompt and identifier.
+4. Let you select which tools the agent can access.
+5. Finally, create a markdown file with the agent configuration.
+
+---
+
+## Use cases
+
+Here are some common use cases for different agents.
+
+- **Build agent**: Full development work with all tools enabled
+- **Plan agent**: Analysis and planning without making changes
+- **Review agent**: Code review with read-only access plus documentation tools
+- **Debug agent**: Focused on investigation with bash and read tools enabled
+- **Docs agent**: Documentation writing with file operations but no system commands
+
+---
+
+## Examples
+
+Here are some example agents you might find useful.
+
+:::tip
+Do you have an agent you'd like to share? [Submit a PR](https://github.com/neopilot-ai/neocode).
+:::
+
+---
+
+### Documentation agent
+
+```markdown title="~/.config/neocode/agents/docs-writer.md"
+---
+description: Writes and maintains project documentation
+mode: subagent
+tools:
+  bash: false
+---
+
+You are a technical writer. Create clear, comprehensive documentation.
+
+Focus on:
+
+- Clear explanations
+- Proper structure
+- Code examples
+- User-friendly language
+```
+
+---
+
+### Security auditor
+
+```markdown title="~/.config/neocode/agents/security-auditor.md"
+---
+description: Performs security audits and identifies vulnerabilities
+mode: subagent
+tools:
+  write: false
+  edit: false
+---
+
+You are a security expert. Focus on identifying potential security issues.
+
+Look for:
+
+- Input validation vulnerabilities
+- Authentication and authorization flaws
+- Data exposure risks
+- Dependency vulnerabilities
+- Configuration security issues
+```