Configuration

LongerAgent loads bundled defaults from the installed package and user overrides from ~/.longeragent/. Run longeragent init to create the initial configuration.

Directory Structure

~/.longeragent/
├── tui-preferences.json   # Model selection, local provider config, preferences
├── .env                   # API keys and managed provider slots (0600 permissions)
├── mcp.json               # MCP server configurations (optional, user-edited)
├── auth.json              # OAuth tokens (auto-managed)
├── agent_templates/       # User template overrides
├── skills/                # User skills
└── prompts/               # User prompt overrides

tui-preferences.json

The primary configuration file. Created and managed by longeragent init. Stores:

• Model selection and UI preferences
• Local provider configurations (model, base URL, context length)
• Legacy env-var mappings for cloud providers that still use direct environment bindings

GLM, Kimi, and MiniMax do not rely on runtime provider-to-env mappings anymore. LongerAgent resolves those providers from fixed internal env slots in ~/.longeragent/.env.

This file is auto-managed. While you can edit it by hand, running longeragent init is the recommended way to make changes.

.env

API keys are stored in this file with 0600 permissions (readable only by you). The init wizard creates it automatically.

# Example ~/.longeragent/.env
ANTHROPIC_API_KEY=sk-ant-...
OPENAI_API_KEY=sk-...
OPENROUTER_API_KEY=sk-or-...
LONGERAGENT_GLM_CODE_API_KEY=...
LONGERAGENT_KIMI_API_KEY=...
LONGERAGENT_MINIMAX_CN_API_KEY=...

For GLM, Kimi, and MiniMax, LongerAgent stores endpoint-specific managed slots here and resolves them directly at startup. External env vars such as MOONSHOT_API_KEY, GLM_CODE_API_KEY, or MINIMAX_API_KEY are only detected and imported during longeragent init or when /model prompts for a missing key. OpenAI (ChatGPT Login) does not use .env; its OAuth tokens live in auth.json.

mcp.json

Optional. Configure MCP (Model Context Protocol) servers for additional tools. Create this file manually.

{
  "server-name": {
    "transport": "stdio",
    "command": "npx",
    "args": ["-y", "@modelcontextprotocol/server-something"],
    "env": {
      "API_KEY": "${MY_API_KEY}"
    }
  }
}

See MCP Integration for the full reference. Use /mcp inside LongerAgent to connect the configured servers and inspect the discovered tool list.

auth.json

Auto-managed. Stores OAuth tokens for the ChatGPT login flow. Do not edit this file directly. Use longeragent oauth commands instead.

See ChatGPT OAuth Login for details.

agent_templates/

Override the built-in sub-agent templates by placing custom versions here:

~/.longeragent/agent_templates/
├── main/
│   └── system_prompt.md
├── explorer/
│   └── system_prompt.md
└── executor/
    └── system_prompt.md

Templates in this directory take priority over the bundled defaults. Only the templates you place here are overridden -- the rest fall through to the defaults.

See Sub-Agents for details on templates.

skills/

User-installed skills. Each skill is a directory containing a SKILL.md file:

~/.longeragent/skills/
├── explain-code/
│   └── SKILL.md
├── skill-manager/
│   └── SKILL.md
└── .staging/           # Temporary work area (ignored by skill loader)

See Skills for how to create and manage skills.

prompts/

Override bundled prompt files. Place custom prompt markdown files here to change the agent's default behavior.

AGENTS.md Files

Two AGENTS.md files are loaded on every turn for persistent project memory:

• ~/AGENTS.md -- Global preferences across all projects. Place this in your home directory.
• <project>/AGENTS.md -- Project-specific notes. Place this in the project root.

These are not inside ~/.longeragent/ -- they live in your home directory and project directories respectively.

The agent reads them for context and can write to them to save long-term knowledge. They persist across sessions and context resets.

CLI Flags

CLI flags override file-based configuration:

longeragent --version           # Show the current version
longeragent --templates <path>  # Use a specific templates directory
longeragent --verbose           # Enable debug logging

Asset Discovery Order

LongerAgent discovers templates, prompts, and skills using this priority chain:

1. CLI flag (e.g., --templates)
2. ~/.longeragent/ directory
3. Current working directory

For each asset type (templates, prompts, skills), the first location that contains the directory wins. This means project-local overrides are possible by placing directories in the project root.