Agents

Built-in agents

Switch between agents with Tab:

Agent	Description
Build (default)	Full access to all tools for development work
Plan	Read-only agent for analysis and code exploration

Subagents

Invoke with @name in your prompt:

Subagent	Description
General	Complex multi-step tasks
Explore	Fast read-only codebase exploration
Scout	External-repo research (experimental — see below)

Scout (experimental)

Scout is a read-only research subagent for code outside your workspace — dependency source, external GitHub repositories, and library documentation. It can clone repositories into a managed cache and inspect them with read, glob, and grep, but it cannot modify your workspace.

Use Scout when you want to:

• inspect a dependency's source or an external library implementation
• compare your local code against an upstream version
• research a public GitHub repository the environment can clone
• read third-party docs alongside their source

Like other subagents, you invoke it with @scout (or via the task tool with subagent: scout).

:::caution Experimental — off by default Scout is gated behind an experimental flag and is not enabled in a default install. When the flag is off, the Scout subagent is hidden, and the repo_clone / repo_overview tools it relies on are not registered. :::

Enabling Scout

Set either environment variable before launching Neusis Code:

# Enable Scout specifically
NEUSISCODE_EXPERIMENTAL_SCOUT=1 neusiscode

# Or enable all experimental features at once
NEUSISCODE_EXPERIMENTAL=1 neusiscode

The broad NEUSISCODE_EXPERIMENTAL switch turns Scout on unless NEUSISCODE_EXPERIMENTAL_SCOUT is explicitly set to disable it.

What Scout can do

Scout runs with a locked-down, read-only permission set. Everything is denied except:

Tool	Why
read	Read files in the workspace and the cache
glob, grep	Find and search files
webfetch, websearch	Look up external documentation
repo_clone	Clone a dependency/GitHub repo into the cache
repo_overview	Orient quickly in a freshly cloned repo

Cloned repositories land in a managed cache under your Neusis Code data directory (repos/); Scout is granted read access there. It cannot run edit, write, bash, or other workspace-modifying tools.

References

You can give Neusis Code named references to git repositories or local directories, then mention them in a prompt as @alias (or @alias/path to point at a file or subdirectory). Configure them under the reference key in neusiscode.json:

{
  "reference": {
    "react": { "repository": "facebook/react" },
    "router": { "repository": "https://github.com/remix-run/react-router", "branch": "main" },
    "design-system": { "path": "~/work/design-system" }
  }
}

Each entry is one of:

Form	Keys	Notes
Git	repository, optional branch	A git URL, host/path reference, or GitHub owner/repo shorthand
Local	path	Absolute, ~/, or workspace-relative path to a directory

A reference can also be written as a bare string: a value starting with ., /, or ~ is treated as a local path; anything else is treated as a git repository.

:::note Alias naming Aliases must not be empty and must not contain /, whitespace, a comma, or a backtick. :::

Typing @ in the prompt autocompletes your configured references. Reference autocomplete works regardless of the Scout flag — selecting one inserts the reference and points the agent at its resolved path.

:::caution Auto-materialization is gated behind Scout With Scout enabled, git references are automatically cloned ("materialized") into the local cache on startup so they are ready to inspect. With Scout disabled, references still autocomplete and resolve, but git references are not cloned for you — you'll need Scout (or repo_clone) to fetch them. :::

Custom agents

Define as markdown files in .neusiscode/agents/ or ~/.config/neusiscode/agents/:

---
description: What this agent does
mode: subagent
model: neusiscloud/claude-sonnet-4-5
---

System prompt content...

Or in neusiscode.json:

{
  "agent": {
    "my-agent": {
      "mode": "subagent",
      "model": "neusiscloud/claude-sonnet-4-5",
      "description": "What this agent does"
    }
  }
}