ncode Desktop / Customize

Instructions, memory and project config

Agents start every turn knowing nothing about your project except what you give them. This page covers the three ways to give them context: instruction files, memory, and the project file with its hooks and profiles.

Editing instructions in the app#

Open the ⋯ menu of a project in the sidebar and choose Edit AGENTS.md. ncode opens the project's instruction file in an editor; save to write it. If the project has none, saving creates AGENTS.md in the project root.

A good instruction file is short and concrete: how to build and test, the conventions agents keep breaking, the folders not to touch.

# Notes for agents
- Build: `npm run build`. Test: `npm test -- --run`.
- Use the existing `api/` client for HTTP; do not add new HTTP libraries.
- Never edit files under `generated/`; run `npm run codegen` instead.

Editing memory in the app#

Open Settings → Memory. Pick a project to edit its memory, and edit your global memory below it. Clear empties one list. Agents add lines themselves with the remember tool when they learn something worth keeping.

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.

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.

Switching profiles#

In a conversation, type /profile <name> in full (it is not in the / list) to apply a profile from the project file; ncode confirms with Switched to profile: careful. /profile alone lists the available profiles, and with none defined it tells you to add them to .swarm_code/config.json.