How to Create, Edit, and Utilize Custom Roles for Specialized AI Tasks in nGPT

Developers can create reusable AI personas in nGPT by using the --role-config command to manage JSON-based system prompts, then apply them with --role to inject specialized behavior into any session.

nGPT is an open-source CLI tool for interacting with large language models. To help developers maintain consistent AI behavior across different tasks, nGPT supports custom roles—persistent system prompts that define specialized personas. This guide explains how to create, edit, and utilize these roles based on the actual implementation in the nazdridoy/ngpt repository.

Understanding nGPT's Custom Role Architecture

The role system in nGPT consists of three integrated components: CLI argument parsing, file-based storage, and runtime prompt injection.

Role Storage and JSON Structure

Custom roles are stored as individual JSON files in an OS-specific configuration directory. The get_role_directory() function in ngpt/cli/handlers/role.py (lines 16-35) automatically creates the appropriate path:

• Linux: ~/.config/ngpt/ngpt_roles/
• macOS: ~/Library/Application Support/ngpt/ngpt_roles/
• Windows: %APPDATA%\ngpt\ngpt_roles\

Each role file follows this JSON structure:

{
  "name": "json_generator",
  "system_prompt": "You are an expert JSON generator. Always respond with valid, well‑formatted JSON based on the user's requirements. Never include explanations or markdown."
}

CLI Integration and Prompt Injection

The handle_role_config_args function in ngpt/cli/args.py (lines 81-85) parses the --role-config and --role arguments. When a user specifies --role <name>, the main entry point in ngpt/cli/main.py (lines 80-86) calls get_role_prompt() to load the stored system prompt and assigns it to args.preprompt. This injection happens before any request is sent to the language model, ensuring the AI adopts the specified persona for the entire session.

Creating and Managing Custom Roles

The role management interface uses the --role-config flag followed by a sub-command. The handle_role_config function in ngpt/cli/handlers/role.py (lines 45-65) implements the dispatcher for these operations.

Creating a New Role

To create a custom role, use the create sub-command with a unique name:

ngpt --role-config create json_generator

This launches an interactive multiline editor where you paste the system prompt. Finish with Ctrl+D (or Ctrl+Z on Windows). The command validates the input and writes the JSON file to your roles directory.

Listing and Editing Existing Roles

To view all available roles:

ngpt --role-config list

Output example:

Available Roles:
 • json_generator
 • linux_expert
 • code_reviewer

To modify an existing role:

ngpt --role-config edit json_generator

The current system_prompt pre-loads in the editor. Modify the text and save to update the role definition immediately.

Removing Roles

To delete a role permanently:

ngpt --role-config remove json_generator

This removes the JSON file from the configuration directory without confirmation, so verify the role name before executing.

Utilizing Custom Roles in AI Tasks

Once defined, roles integrate seamlessly into standard nGPT workflows through the --role parameter.

Command-Line Usage

Apply a custom role to any query by specifying its name:

ngpt --role json_generator "Generate a user profile with name, email, address, and preferences"

Behind the scenes, main.py executes get_role_prompt('json_generator'), retrieves the stored system prompt, and injects it as args.preprompt. The LLM receives the specialized instructions before processing your query, ensuring consistent JSON formatting without requiring repetitive prompt engineering.

You can combine roles with other CLI options:

ngpt --role linux_expert --temperature 0.2 "Explain how to diagnose high CPU usage"

Programmatic Access

For Python applications building on nGPT, import the role utilities directly:

from ngpt.cli.handlers.role import get_role_prompt

# Load a custom role's system prompt

prompt = get_role_prompt("json_generator")
if prompt:
    print("Loaded role prompt:", prompt)
    # Use this prompt with your API client

The get_role_prompt function (lines 98-108 in role.py) handles file path resolution, JSON parsing, and error handling, returning None if the role does not exist while printing a friendly warning to stderr.

Summary

• Custom roles in nGPT are JSON files containing name and system_prompt fields, stored in OS-specific configuration directories.
• Use --role-config with sub-commands (create, edit, list, remove) to manage roles via ngpt/cli/handlers/role.py.
• The get_role_directory() function ensures cross-platform storage in ~/.config/ngpt/ngpt_roles/ (Linux), ~/Library/Application Support/ngpt/ngpt_roles/ (macOS), or %APPDATA%\ngpt\ngpt_roles\ (Windows).
• Activate roles during usage with --role <name>, which triggers get_role_prompt() in main.py to inject the stored prompt into args.preprompt.
• Access roles programmatically by importing get_role_prompt from ngpt.cli.handlers.role.

Frequently Asked Questions

How do I create a custom role that always outputs valid JSON?

Use the create sub-command to define a role with strict JSON formatting instructions. Run ngpt --role-config create json_generator, then enter a system prompt like: "You are an expert JSON generator. Always respond with valid, well-formatted JSON. Never include explanations or markdown." When you use ngpt --role json_generator, every response will follow these constraints without requiring repetitive prompting.

Where are custom role files stored on my system?

nGPT stores roles in OS-specific configuration directories managed by the get_role_directory() function in ngpt/cli/handlers/role.py. On Linux, roles reside in ~/.config/ngpt/ngpt_roles/; on macOS, in ~/Library/Application Support/ngpt/ngpt_roles/; and on Windows, in %APPDATA%\ngpt\ngpt_roles\. Each role is a separate JSON file containing the role name and system prompt.

Can I use custom roles programmatically in Python scripts?

Yes, you can import the role utilities directly from the nGPT package. Import get_role_prompt from ngpt.cli.handlers.role to load the system prompt string for any stored role. This function handles file resolution, JSON parsing, and error handling, returning the prompt text that you can then pass to your own API client or LLM interface.

What happens if I specify a role that doesn't exist?

If you use --role nonexistent_role, the get_role_prompt() function in ngpt/cli/handlers/role.py checks the roles directory and finds no matching JSON file. It prints a friendly warning message to stderr indicating the role was not found, and returns None. The application continues without injecting a system prompt, effectively falling back to default behavior without the specialized persona.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}