ncode CLI / Features

Project instructions, memory and config

Everything on this page lives in files you can read, edit and commit: instruction files in the project, and a .swarm_code folder for memory, commands, agent definitions, workflows and the project file. The desktop app reads the same files.

Instructions and memory#

Project instructions#

Instruction files tell agents how your project works: conventions, commands, things to avoid. In every folder of the project down to three levels below the root, ncode reads the first of these files that exists:

1. AGENTS.override.md
2. AGENTS.md
3. NCODE.md
4. SWARMCODE.md (the earlier name, still read)
5. CLAUDE.md

The root's file comes first. At most 12 files and 32,000 characters in total reach the prompt. Instructions are used only after you trust the project.

When you edit instructions from ncode, it edits the first of AGENTS.md, NCODE.md, SWARMCODE.md or CLAUDE.md that exists in the project root, or creates AGENTS.md.

Memory#

Memory is a short list of durable facts, one dated line each (- [2026-09-01] the API uses SQLite). Agents add to it with the remember tool, and you can edit it yourself.

• Project memory: .swarm_code/MEMORY.md in the project.
• Global memory: MEMORY.md in ~/Library/Application Support/SwarmCode, for facts about you that hold in every project.

Both reach every system prompt, capped at 16,000 characters.

Custom commands#

A custom command is a Markdown file that becomes a slash command: review-api.md becomes /review-api.

• Project commands live in .swarm_code/commands/; global ones in commands/ inside ~/Library/Application Support/SwarmCode. A project command overrides a global one with the same name.
• Optional front matter: description, swarm (true runs it as a swarm) and mode (plan or build).
• $ARGUMENTS in the body is replaced by whatever you type after the command.

---
description: Review one API endpoint
swarm: false
---
Review the endpoint $ARGUMENTS for input validation and error handling.

If a name is taken twice, a built-in command wins over a workflow, and a workflow wins over a custom command.

Agent definitions#

An agent definition is a Markdown file with front matter (name, description, tools, model, effort, prewalk, max_turns); its body is added to that agent's instructions. Agents can pick a definition by name when they start a sub-agent. Definitions are looked up in the project (.swarm_code/agents/), then your home folder (~/.swarm_code/agents/), then the three bundled ones: implementer, reviewer and scout.

Skills#

A skill is a folder with a SKILL.md file (plus any assets it needs) that an agent can load for a specific job. Project skills win over your own, and yours over the bundled html-report skill.

In the terminal#

• Instructions and hooks take effect only in a trusted project: type /trust once (see Approvals and trust).
• Settings has a Memory & instructions section, and a Library section for your custom commands, agent definitions, skills and workflows.
• /agents lists the agent definitions a swarm can use.
• ncode config path prints where the project's config.json, MEMORY.md and instruction file are.

The project file and hooks#

The project file#

A project can carry settings in .swarm_code/config.json, committed with the code so the whole team shares them. ncode reads two keys from it: hooks and profiles.

{
  "hooks": {
    "session_start": [{ "command": "git log --oneline -5" }],
    "pre_tool_use": [{ "matcher": "run_command", "command": "./scripts/guard.sh", "timeout_ms": 5000 }]
  },
  "profiles": {
    "careful": { "effort": "high", "swarm_effort": "high" }
  }
}

A project file can never set where requests go or what they cost: provider choices, keys, the monthly budget and the workflow budget are ignored if a file contains them.

Hooks#

Hooks are shell commands that run at three moments:

Each hook has a command, an optional matcher (a regular expression tested against the tool name, for example run_command or write_file|edit_file), a timeout_ms between 1 and 30,000 (default 10,000) and an output_cap (how much of its output is kept) between 1 and 16,384 (default 4,096).

A hook runs only in a trusted project, with the same cleaned environment agent commands get. It can read these variables: NCODE_EVENT (the hook name), NCODE_PROJECT (the project folder) and, for tool hooks, NCODE_TOOL (the tool name). The same three values are also set under their earlier names, SWARMCODE_EVENT, SWARMCODE_PROJECT and SWARMCODE_TOOL, so existing hook scripts keep working.

Profiles#

A profile is a named set of choices you switch a conversation to in one step. Names are 1 to 32 letters, digits, _ or -. A profile may set model, swarm_model, effort and swarm_effort; the conversation keeps its provider, so a model must be one your current provider offers.

Hooks also receive the same values under their earlier names, SWARMCODE_EVENT, SWARMCODE_PROJECT and SWARMCODE_TOOL, so older hook scripts keep working; read the NCODE_ names in new ones.

The project file in the terminal#

The terminal shows the project file in Settings → Project file, read-only: edit .swarm_code/config.json in your editor and commit it. There is no /profile command in the terminal; switch a conversation's model and effort with /model and /effort (see Modes and run types).