Using Niah

Agents

Agents take a goal, break it into steps, and carry them out across your repository — reading files, running commands, and proposing edits. What they are allowed to do without asking is yours to configure.

The Agents window

Open it with ⌘⇧A / Ctrl+Shift+A, or from the Agents menu in the title bar. Describe a goal and the agent plans the work, delegates parts of it to sub-agents, and reports progress as it goes.

Reach for an agent when a task spans several files, needs exploration before any edit makes sense, or has a verify step. For a change you can already point at, Quick Edit is faster.

Sub-agents

Work is delegated to focused sub-agents that run concurrently, each with its own thread and its own slice of the problem. The roles you will see most are:

Explorer	Searches and reads the codebase to answer a specific question. Several run in parallel.
Editor	Applies a scoped change once the shape of it is known.
Verifier	Checks that a change did what it was meant to do.

Additional roles — planner, debugger, reviewer, tester, documenter, and architect — are used as a task calls for them.

Sub-agents can spawn sub-agents. The main agent is depth 0, one it spawns is depth 1, and nesting is capped at depth 3 by default. Lower it with maxSubAgentDepth if you want flatter, more predictable runs.

Approval tiers

Every tool an agent can call carries an approval tier, which decides whether it runs on its own or waits for you:

`auto`	Runs without interruption. Suited to read-only tools.
`notify`	Runs, and tells you it did.
`confirm`	Waits for your approval before running.

Sensible defaults ship with the app; override them per tool and per project in .niahagent.

Constraining agents with `.niahagent`

Drop a .niahagent JSON file in your workspace root to set policy for that project. It is a good file to commit — everyone working in the repo then gets the same guardrails.

json

{
  "approvalTiers": {
    "edit_file": "auto",
    "run_shell": "notify"
  },
  "context": {
    "alwaysInclude": ["src/types/**", "docs/architecture.md"],
    "ignore": ["node_modules", "dist", ".git"]
  },
  "constraints": {
    "maxIterations": 50,
    "maxConcurrentSubAgents": 5,
    "maxConcurrentExplorers": 5,
    "allowedCommands": ["npm test", "npm run build"]
  },
  "memory": {
    "persistSession": true,
    "maxTokenBudget": 32000
  }
}

Execution limits

Key	Default	What it caps
`maxIterations`	50	Model iterations for a single task.
`maxConcurrentSubAgents`	5	Sub-agents running at once. 3 is a good working value.
`maxConcurrentExplorers`	5	Explorer sub-agents running at once.
`maxSubAgentDepth`	3	Nesting depth. 2 keeps runs easier to follow.
`maxSubAgentRounds`	20	Rounds for a non-explorer sub-agent with no explicit budget.

Terminal command policy

Terminal access is the sharpest edge an agent has, so it has its own control. When an agent proposes a command that policy forbids, the call is rejected and the run logs that it was blocked.

`allowedCommands`	Whitelist. An empty list — the default — allows anything not blocked.
`blockedCommands`	Blacklist of commands the agent may never run.

Start restrictive on shared repos. Setting allowedCommands to just your test and build commands means an agent can verify its own work and nothing more.

Context

context.alwaysInclude pins globs an agent should always have in view — a types file, an architecture note — and context.ignore keeps it out of directories that would only add noise. It defaults to node_modules, dist, .git, and *.lock.

For exclusions that should also apply to indexing and ordinary search, use .niahignore instead.

Memory

With memory.persistSession enabled, working memory is written to .niah/agent-memory.json so a long task survives a restart. maxTokenBudget caps how much of that memory is carried forward, and defaults to 32,000 tokens.

Compliance scanning

Run Niah: Run Workspace Compliance Scan from the Command Palette to scan the workspace with the Checks agent, then ask about what it found in plain language rather than reading a report.

NextModels & providers → ReferenceConfiguration →