Profiles

Profiles define the agent's identity, tools, and behaviour for a specific domain.

Profile definition (navi/profiles/base.py)

Each profile is loaded from a directory under navi/profiles/<id>/:

• config.json — all fields below
• system_prompt.txt — domain-specific instructions
• subagent_system_prompt.txt — injected into subagents spawned from this profile (optional)

All config.json fields

Identity

LLM

Tools

tools.agent controls what the main loop sees. tools.subagent controls what sub-agents spawned from this profile see. If tools.subagent is empty, it falls back to tools.agent.

spawn_agent may receive an optional profile_id. If omitted, the subagent uses the parent session's current profile. If provided, the subagent uses the selected profile's model, prompt, planning flags, and tools.subagent fallback.

MCP tool groups

Inside tools.{agent,subagent}.mcp, each key is an MCP server name and each value is a list of group names (or "*" for all groups). Named groups resolve to concrete tools via the server's config in mcp_servers.d/. Example:

{
  "mcp": {
    "navi-web": ["search", "browse", "request"]
  }
}

This exposes the tools mcp__navi-web__web_search, mcp__navi-web__web_view, and mcp__navi-web__http_request. * expands to every tool advertised by that server.

Deprecated tool fields

Older configs used enabled_tools, subagent_tools, and mcp_servers as flat top-level fields. The loader still auto-migrates them into tools.agent / tools.subagent for backward compatibility, but new profiles should use the explicit tools structure.

When tools.subagent is non-empty, only MCP groups listed there are exposed to the sub-agent. This prevents a profile's main MCP servers from leaking into restricted sub-agent contexts.

Thinking mechanics

Planning

The planning pipeline runs before the main tool-calling loop and produces a structured execution plan. It has three phases:

• Phase 1 — Analysis: reformulates the task, identifies subtasks and unknowns. Can output DIRECT to skip to execution immediately.
• Phase 2 — Structured review: one LLM call critiques the Phase 1 analysis through Critic / Pragmatist / Detailer sections and emits Plan Adjustments. Runs only when Phase 1 signals REFLECT: yes.
• Phase 3 — Execution plan: assigns each subtask to TOOL / AGENT / SELF and uses adaptive plan depth.

Sub-agent planning

Active profiles

All profiles share a base tool set. User tools from tools/enabled.json are merged in at runtime.

navi_code

Terminal-first local coding assistant. Designed for the Navi Code CLI and single-user local deployments:

• Native tools: todo, scratchpad, reflect, switch_profile, list_profiles, filesystem, code_exec, terminal, memory, list_tools, tool_manual, spawn_agent, schedule_recall, manage_recall.
• MCP tools: disabled ("mcp": {}) for the terminal experience.
• Excluded: share_file, content_publish, ssh_exec, gmail, image_view, mcp__navi-web.
• Planning: Phase 1 and Phase 3 enabled, Phase 2 disabled to reduce latency.
• Safety: the system prompt asks Navi to confirm destructive operations (rm, overwrites) before executing them.

Use it with NAVI_DEFAULT_PROFILE_ID=navi_code so POST /sessions without a profile_id creates a navi_code session automatically. See docs/navi_code.md for the full local-terminal setup.

System prompt construction

The LLM sees (injected fresh on every call, never stored in session):

{persona.txt content}

---

{profile system_prompt.txt content}

persona.txt — global layer: personality, CONTEXT FIRST principle, self-extension rules, scratchpad/todo/memory instructions, delegation rules.

system_prompt.txt — domain layer: tool priorities, workflow, safety rules for this profile.

Adding a profile

1. Create directory navi/profiles/my_profile/
2. Add config.json (minimal example):

   {
   "id": "my_profile",
   "name": "My Profile",
   "description": "...",
   "short_description": "...",
   "model": ["gemma4:31b-cloud", "gemma4:26b-a4b-it-q4_K_M"],
   "temperature": 0.5,
   "max_iterations": 20,
   "tools": {
    "agent": {
      "native": ["todo", "scratchpad", "filesystem", "terminal"],
      "mcp": {
        "navi-web": ["search"]
      }
    },
    "subagent": {
      "native": ["todo", "filesystem", "terminal"],
      "mcp": {}
    }
   },
   "planning_enabled": true,
   "planning_mandatory": false,
   "planning_phase1_enabled": true,
   "planning_phase2_enabled": false,
   "planning_phase3_enabled": true,
   "think_enabled": true,
   "iteration_budget_enabled": true,
   "goal_anchoring_enabled": true,
   "goal_anchoring_interval": 5,
   "anti_stall_enabled": true,
   "anti_stall_threshold": 8,
   "step_validation_enabled": false,
   "adaptive_replan_enabled": false,
   "subagent_planning_enabled": false
   }

3. Add system_prompt.txt with domain-specific instructions.
4. Optionally add subagent_system_prompt.txt.
5. The profile is auto-discovered at startup — no registration needed.

Profile switching

switch_profile tool updates session.profile_id in the DB. After each tool execution batch, run_stream() checks for a profile change and reloads profile + tools. Takes effect on the next LLM call.

Rules (in persona): don't switch for a single off-topic question; switch when the domain clearly changes; never switch back and forth repeatedly.