Files & configuration
How the main .nt file is organized, how to split it into pieces, and how to set project defaults.
As your agent grows, one file can get long. NT lets you split your project into
several files and tie them together from one entry file. This page explains
that setup and the config block that holds your project settings.
The entry file
The entry file is the main file NT reads first. It usually does two things:
- Pulls in the other files with
import. - Defines your main agent.
import ./config.nt
import ./tools.nt
import ./skills.nt
import ./mcp/local.nt
import ./subagents/researcher.nt
agent age
description: Guesses a person's age from clues.
model: anthropic/claude-sonnet-5
tools:
- current_year
- local_demo.echo
skills:
- estimation
subagents:
- researcher
instructions: |
Guess the person's most likely age from the clues.
input:
clues: string
output:
age: number
reason: stringIf your entry file is named age.nt and sits in the current folder, you do not
need to name it. Every command uses age.nt by default:
nt run ageTo load a different file, add --file:
nt run age --file other.ntSplitting into pieces
You do not have to split anything. A single file works fine. But once you have a few tools and helpers, it is tidier to keep each kind in its own file.
A common layout looks like this:
age.nt the entry file: imports + the main agent
config.nt project settings and the AI provider
sandboxes.nt the agent's isolated workspace
skills.nt reusable instructions
tools.nt custom shell and HTTP tools
mcp/local.nt a selected MCP server and tool policy
mcp/echo-server.mjs the starter's local server process
subagents/researcher.nt a helper agent
workflows.nt a multi-step workflowStart from this layout
nt setup --template full writes exactly this arrangement and wires it together. Trust and check
the generated local server with nt mcp trust local_demo and nt mcp doctor local_demo; setup
prints both commands for you.
import
import pulls in another file. Put imports at the top, one per line. Paths start
with ./ and are relative to the current file.
import ./config.nt
import ./tools.nt
import ./mcp/local.nt
import ./subagents/researcher.ntYou can also import a whole folder, which pulls in every .nt file inside it:
import ./subagentsTwo ways to load a project
With no options, NT loads age.nt from the current folder and follows its imports. Point it at a
different entry file with --file other.nt, or at a whole folder with --dir ./my-project. All
three end up with the same kind of project.
The config block
The config block holds settings for the whole project: default values your
agents share, which agent to run by default, and the AI provider.
config
entry: age
audit: ~/.nt/audit
defaults:
model: anthropic/claude-sonnet-5
thinking: medium
max_tokens: 8000
providers:
anthropic:
api: anthropic
api_key: env(ANTHROPIC_API_KEY)entry
The name of the agent (or workflow) to run when you type nt up. In the example
above, that is the age agent.
audit
Where to record every tool call your agents make. It takes one of two values:
| Value | What happens |
|---|---|
| A folder path | Tool calls are appended to a daily .jsonl file in that folder. |
off | Nothing is logged. |
Leave it out and NT logs to ~/.nt/audit. A ~ means your home folder, and a
relative path such as ./logs is measured from the file that declares it.
config
audit: off # no logging at allRead the log back with nt audit. Secrets are removed before anything is
written — see Audit the tool calls.
show_tool_calls
Set it to true and the terminal's thinking line names each tool call and
delegation as it happens, on every nt up, nt run, and nt chat — the same
thing the --show-tool-calls flag does for a single run.
config
show_tool_calls: trueLeave it out and the line shows only the rotating thinking words unless the flag is passed.
defaults
Values every agent uses unless it sets its own. This saves you repeating the same lines in every agent.
| Setting | What it does |
|---|---|
model | The default AI model, written as provider/model-name. |
sandbox | The default workspace agents run in. |
thinking | How hard the model thinks. One of off, minimal, low, medium, high, xhigh, max. |
max_tokens | The model's maximum output-token budget for one reply. |
providers
Where the AI comes from. anthropic (Claude) and openai are built in and read
ANTHROPIC_API_KEY or OPENAI_API_KEY without a declaration. Add a provider
entry only to override a built-in or configure another OpenAI-compatible
service. See Connect a model for details.
Keep your key safe
Always write your key as env(ANTHROPIC_API_KEY), not the real key. That reads it from your
environment instead of saving it in the file.