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

New sessions use Alpha (alpha-v3). Use the restricted planning profile when you want analysis and a plan before implementation; its edit tools are denied by default.

Use the agent selector or Tab to switch among agents exposed by the active client. The @ mention menu is likewise host- and configuration-dependent; do not assume delegated subagents are directly selectable.

---

Types

There are two types of agents in AlphaBase: primary agents and subagents. The visible set depends on the client and configuration.

---

Primary agents

Primary agents are the main assistants you interact with directly. You can cycle through visible primary agents using the Tab key, or your configured switch_agent keybind. Tool access is controlled by the permission engine; there is no universal “full access” guarantee for a primary agent.

Tip

You can use the Tab key to switch between primary agents during a session.

The current visible default primary agent is Alpha. Restricted and legacy profiles may also be present in the runtime, but hidden profiles are not normal choices in the agent selector.

---

Subagents

Subagents are specialized assistants that primary agents can invoke for specific tasks. They are delegated workers, not ordinary user-facing primary-agent choices.

The delegated subagents are General and Explore. A primary agent can invoke them when task delegation and the active permission policy allow it. A host may expose additional custom workers, but availability is configuration-dependent.

---

Built-in

AlphaBase provides one current visible primary default, a restricted planning profile, and two delegated subagents.

---

Use Alpha

Mode: primary

Alpha (alpha-v3) is the current visible default. It is the universal AlphaBase assistant: it can execute directly, use connected services, and coordinate specialists when the task and permissions allow it.

Fresh sessions select Alpha unless a valid project or global configuration chooses another visible primary agent.

---

Use 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. The built-in profile denies edit tools by default and allows plan artifacts in the supported plan locations. Other tools still follow the active permission configuration; do not assume that every shell or network action is blocked.

This profile is useful when you want the model to analyze code, suggest changes, or create a plan before implementation.

---

Use general

Mode: subagent

A general-purpose agent for researching complex questions and executing multi-step tasks. Its default profile permits delegation and denies todo tools, while file and system access remains subject to the active permission configuration. Use this to run multiple units of work in parallel when the primary agent delegates them.

---

Use explore

Mode: subagent

A fast exploration agent for finding files by patterns, searching code, and answering questions about a codebase. File edit tools are denied by default. Search, web, and shell capabilities are still permission-controlled, so treat the profile as read-oriented rather than as a general security boundary.

---

Use compaction

Mode: primary

Hidden system agent that compacts long context into a smaller summary. It runs automatically when needed and is not selectable in the UI.

---

Use title

Mode: primary

Hidden system agent that generates short session titles. It runs automatically and is not selectable in the UI.

---

Use summary

Mode: primary

Hidden system agent that creates session summaries. It runs automatically and is not selectable in the UI.

---

Usage

1. For visible 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 and the active permission policy. Use the primary-agent selector or Tab for user-facing agent changes; do not assume a delegated subagent is directly selectable in every host.

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 alphabase.json config file:

alphabase.json

{
  "$schema": "https://alphabase.extremeharness.com/config.json",
  "agent": {
    "alpha-v3": {
      "mode": "primary",
      "model": "<provider>/<model-id>",
      "prompt": "{file:./prompts/alpha.txt}",
      "permission": {
        "edit": "ask",
        "bash": "ask"
      }
    },
    "plan": {
      "mode": "primary",
      "model": "<provider>/<model-id>",
      "permission": {
        "edit": "deny"
      }
    },
    "code-reviewer": {
      "description": "Reviews code for best practices and potential issues",
      "mode": "subagent",
      "model": "<provider>/<model-id>",
      "prompt": "You are a code reviewer. Focus on security, performance, and maintainability.",
      "permission": {
        "edit": "deny"
      }
    }
  }
}

---

Markdown

You can also define agents using markdown files. Place them in:

• Global: ~/.config/alphabase/agents/
• Per-project: .alphabase/agents/

~/.config/alphabase/agents/review.md

---
description: Reviews code for quality and best practices
mode: subagent
model: <provider>/<model-id>
temperature: 0.1
permission:
  edit: deny
  bash: deny
---

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.

alphabase.json

{
  "agent": {
    "review": {
      "description": "Reviews code for best practices and potential issues"
    }
  }
}

This option is optional, but a clear description improves the agent picker and helps the runtime and delegated agents choose the right specialist.

---

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.

alphabase.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

alphabase.json

{
  "agent": {
    "analyze": {
      "temperature": 0.1,
      "prompt": "{file:./prompts/analysis.txt}"
    },
    "alpha-v3": {
      "temperature": 0.3
    },
    "brainstorm": {
      "temperature": 0.7,
      "prompt": "{file:./prompts/creative.txt}"
    }
  }
}

If no temperature is specified, AlphaBase leaves the effective default to the selected provider/model and its runtime configuration. Do not assume one global temperature across providers.

---

Max steps

Control the maximum number of agentic iterations an agent can perform before the runtime ends the turn’s active work. This allows users who wish to control costs to set an explicit limit on agentic actions.

If this is not set, the runtime derives a bounded execution policy from the active agent and request. The exact budget is implementation- and policy-dependent; set steps when you need a predictable per-agent limit.

alphabase.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 runtime stops further agentic work and returns a terminal response according to the active execution policy.

Caution

The legacy maxSteps field is deprecated. Use steps instead.

---

Disable

Set to true to disable the agent.

alphabase.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.

alphabase.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 AlphaBase 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 while subagents will use the model of the primary agent that invoked the subagent.

alphabase.json

{
  "agent": {
    "plan": {
      "model": "<provider>/<model-id>"
    }
  }
}

The model ID in your AlphaBase config uses the format provider/model-id. For example, if you’re using AlphaBase Zen, you would use alphabase/<model-id>.

---

Tools

Use the permission config to control whether individual tools are allowed, require approval, or are denied. The older boolean tools field is retained as a compatibility alias; new configurations should use permission.

alphabase.json

{
  "$schema": "https://alphabase.extremeharness.com/config.json",
  "permission": {
    "edit": "allow",
    "bash": "ask"
  },
  "agent": {
    "plan": {
      "permission": {
        "edit": "deny",
        "bash": "deny"
      }
    }
  }
}

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:

alphabase.json

{
  "$schema": "https://alphabase.extremeharness.com/config.json",
  "agent": {
    "readonly": {
      "permission": {
        "mymcp_*": "deny",
        "edit": "deny"
      }
    }
  }
}

Learn more about 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

alphabase.json

{
  "$schema": "https://alphabase.extremeharness.com/config.json",
  "permission": {
    "edit": "deny"
  }
}

You can override these permissions per agent.

alphabase.json

{
  "$schema": "https://alphabase.extremeharness.com/config.json",
  "permission": {
    "edit": "deny"
  },
  "agent": {
    "alpha-v3": {
      "permission": {
        "edit": "ask"
      }
    }
  }
}

You can also set permissions in Markdown agents.

~/.config/alphabase/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.

alphabase.json

{
  "$schema": "https://alphabase.extremeharness.com/config.json",
  "agent": {
    "alpha-v3": {
      "permission": {
        "bash": {
          "git push": "ask",
          "grep *": "allow"
        }
      }
    }
  }
}

This can take a glob pattern.

alphabase.json

{
  "$schema": "https://alphabase.extremeharness.com/config.json",
  "agent": {
    "alpha-v3": {
      "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.

alphabase.json

{
  "$schema": "https://alphabase.extremeharness.com/config.json",
  "agent": {
    "alpha-v3": {
      "permission": {
        "bash": {
          "*": "ask",
          "git status *": "allow"
        }
      }
    }
  }
}

Learn more about permissions.

---

Mode

Control the agent’s mode with the mode config. The mode option is used to determine how the agent can be used.

alphabase.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.

alphabase.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

Hidden status applies to any agent. Hidden agents are omitted from normal user selectors and autocomplete; the runtime may still use them internally when their permissions allow it.

---

Task permissions

Control which subagents an agent can invoke via the Task tool with permission.task. Uses glob patterns for flexible matching.

alphabase.json

{
  "agent": {
    "harness": {
      "mode": "primary",
      "permission": {
        "task": {
          "*": "deny",
          "harness-*": "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, harness-planner matches both * (deny) and harness-* (allow), but since harness-* comes after *, the result is allow.

Caution

Task permissions and user-facing visibility are separate controls. A denied, hidden, or unexposed agent may be unavailable both to delegated work and to the @ autocomplete menu; direct invocation is only possible when the host exposes the agent and the active permissions allow it.

---

Color

Customize the agent’s visual appearance in the UI with the color option. This affects how the agent appears in the interface.

Use a valid hex color (e.g., #FF5733) or theme color: primary, secondary, accent, success, warning, error, info.

alphabase.json

{
  "agent": {
    "creative": {
      "color": "#ff6b6b"
    },
    "code-reviewer": {
      "color": "accent"
    }
  }
}

---

Top P

Control response diversity with the top_p option. Alternative to temperature for controlling randomness.

alphabase.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:

alphabase.json

{
  "agent": {
    "deep-thinker": {
      "description": "Agent that uses high reasoning effort for complex problems",
      "model": "<provider>/<model-id>",
      "reasoningEffort": "high",
      "textVerbosity": "low"
    }
  }
}

These additional options are model and provider-specific. Check your provider’s documentation for available parameters.

Tip

Run alphabase models to see a list of the available models.

---

Create agents

You can create new agents using the following command:

alphabase 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.

• Alpha: General implementation, connected work, and specialist coordination
• Plan: Analysis and planning with edit tools denied by default
• 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.

---

Documentation agent

~/.config/alphabase/agents/docs-writer.md

---
description: Writes and maintains project documentation
mode: subagent
permission:
  bash: deny
---

You are a technical writer. Create clear, comprehensive documentation.

Focus on:

- Clear explanations
- Proper structure
- Code examples
- User-friendly language

---

Security auditor

~/.config/alphabase/agents/security-auditor.md

---
description: Performs security audits and identifies vulnerabilities
mode: subagent
permission:
  edit: deny
---

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