← All docs

DOCS

  1. Getting Started
  2. Configuration
  3. Tools
  4. Sessions
  5. Compaction & Branch Summarization
  6. Subagents
  7. Extensions
  8. Themes
  9. Memory System
  10. Skills
  11. Code intelligence (LSP)
  12. Termux Support
  13. Environment variables
  14. Custom Providers
  15. JSON Event Stream Mode
  16. Keybindings
  17. Prompt Templates
  18. RPC Mode
  19. Session File Format
  20. Shell Aliases
  21. Terminal Setup
  22. tmux Setup
DOCS
  1. Getting Started
  2. Configuration
  3. Tools
  4. Sessions
  5. Compaction & Branch Summarization
  6. Subagents
  7. Extensions
  8. Themes
  9. Memory System
  10. Skills
  11. Code intelligence (LSP)
  12. Termux Support
  13. Environment variables
  14. Custom Providers
  15. JSON Event Stream Mode
  16. Keybindings
  17. Prompt Templates
  18. RPC Mode
  19. Session File Format
  20. Shell Aliases
  21. Terminal Setup
  22. tmux Setup
ON THIS PAGE
  1. Directory Structure
  2. Settings
  3. Model & Provider
  4. Behavior
  5. Compaction
  6. Memory
  7. Retry
  8. UI
  9. Skills & Extensions
  10. MCP
  11. Images
  12. Notifications (Termux)
  13. Session
  14. AGENTS.md
  15. Keybindings
  16. Prompt Templates

Configuration

Neo Code uses JSON settings files and a directory structure for configuration.

#Directory Structure

~/.neo-code/
├── agent/
│   ├── auth.json           Credentials from neo login
│   ├── settings.json       Global settings
│   ├── keybindings.json    Custom keybindings
│   ├── models.json         Custom provider/model configuration
│   ├── bin/                Managed binaries (fd, rg)
│   ├── memories/           Memory entries (markdown files)
│   ├── sessions/           Session history per workspace
│   ├── skills/             User-installed skills
│   ├── extensions/         Global extensions
│   ├── agents/             Subagent definitions
│   └── prompts/            Custom prompt templates

Per-project configuration lives in .neo-code/ at the project root:

your-project/
├── .neo-code/
│   ├── settings.json       Project-specific settings
│   ├── skills/             Project-local skills
│   ├── extensions/         Project-local extensions
│   ├── agents/             Project-local subagent definitions
│   ├── prompts/            Project-local prompt templates
│   └── todos.json          Task plan state
├── AGENTS.md               Project instructions for the agent

#Settings

Settings are JSON files. Project settings override global settings.

Access via /settings in the TUI, or /config to view effective values.

#Model & Provider

KeyTypeDescription
defaultProviderstringProvider to use (default: neosantara)
defaultModelstringModel ID to use
transportstringauto, sse, websocket, websocket-cached
defaultThinkingLevelstringoff, minimal, low, medium, high, xhigh
thinkingBudgetsobjectCustom token budgets per thinking level
enabledModelsstring[]Model patterns enabled for Shift+M cycling

#Behavior

KeyTypeDescription
agentModestringDefault workflow mode (default, ask, read-only, plan, accept-edits, full)
steeringModestringSteering message delivery: all or one-at-a-time
followUpModestringFollow-up message delivery: all or one-at-a-time
hideThinkingBlockbooleanHide thinking blocks in conversation (default: true)
quietStartupbooleanSuppress startup messages
enableInstallTelemetrybooleanSend anonymous version/update ping after changelog-detected updates
shellPathstringCustom shell path for bash tool
shellCommandPrefixstringPrefix prepended to all shell commands
npmCommandstring[]Custom npm command (e.g. ["pnpm"])
doubleEscapeActionstringDouble-Escape behavior: fork, tree, or none
treeFilterModestringDefault /tree filter: default, no-tools, user-only, labeled-only, or all

#Compaction

KeyTypeDescription
compaction.enabledbooleanEnable auto-compaction (default: true)
compaction.reserveTokensnumberTokens to reserve for response
compaction.keepRecentTokensnumberRecent tokens to preserve during compaction
branchSummary.reserveTokensnumberTokens reserved for branch summary
branchSummary.skipPromptbooleanSkip the prompt and do not generate a branch summary

#Memory

KeyTypeDescription
memories.enabledbooleanEnable memory injection (default: true)
memories.autoExtractbooleanAuto-extract memories from conversation (default: true)
memories.maxStorednumberMaximum memories to keep
memories.maxInjectednumberMax memories injected per session (default: 10)
memories.maxInjectionCharsnumberMax chars injected per session (default: 4000)
memories.pruneAfterDaysnumberAuto-prune memories older than N days (default: 90)

#Retry

KeyTypeDescription
retry.enabledbooleanEnable automatic retry on failure
retry.maxRetriesnumberMaximum retry attempts
retry.baseDelayMsnumberBase delay between retries
retry.provider.timeoutMsnumberSDK/provider request timeout
retry.provider.maxRetriesnumberSDK/provider retry attempts
retry.provider.maxRetryDelayMsnumberMax server-requested retry delay

#UI

KeyTypeDescription
themestringTUI color theme
terminal.showImagesbooleanShow inline images when the terminal supports them
terminal.imageWidthCellsnumberPreferred inline image width in terminal cells
terminal.clearOnShrinkbooleanClear empty rows when content shrinks
terminal.showTerminalProgressbooleanShow progress in terminal title
collapseChangelogbooleanAuto-collapse changelog on startup
spinnerTipsEnabledbooleanShow tips during loading
spinnerTipsOverrideobjectReplace or supplement built-in spinner tips
statusline.itemsarrayConfigure footer status line items
editorPaddingXnumberHorizontal padding for input editor
autocompleteMaxVisiblenumberMax visible autocomplete items
showHardwareCursorbooleanShow terminal cursor for IME support
markdown.codeBlockIndentstringCode block indent string

#Skills & Extensions

KeyTypeDescription
skillsstring[]Additional skill paths to load
enableSkillCommandsbooleanRegister skills as /skill:name commands
extensionsstring[]Local extension file paths
packagesarraynpm/git package sources for extensions
promptsstring[]Local prompt template paths
themesstring[]Local theme file paths

#MCP

KeyTypeDescription
mcpServersobjectMCP server configuration (name → {command, args, env})

#Images

KeyTypeDescription
images.autoResizebooleanResize images for model compatibility
images.blockImagesbooleanBlock all images from being sent

#Notifications (Termux)

KeyTypeDescription
notifications.termux.enabledbooleanEnable Termux notifications
notifications.termux.minDurationMsnumberMin turn duration to trigger notification
notifications.termux.vibratebooleanVibrate on notification
notifications.termux.soundbooleanPlay sound on notification

#Session

KeyTypeDescription
sessionDirstringCustom session storage directory

#AGENTS.md

The AGENTS.md file at your project root provides instructions to the agent about your project. It's loaded automatically on every session.

Create one with /init or /agents init.

Common contents:

  • Build/test commands
  • Code conventions
  • Architecture overview
  • Forbidden operations

#Keybindings

Custom keybindings in ~/.neo-code/agent/keybindings.json:

{
  "app.interrupt": "escape",
  "app.mode.cycle": "shift+tab",
  "app.transcript.view": "ctrl+t",
  "app.tools.expand": "ctrl+e",
  "app.session.new": "ctrl+j",
  "app.session.resume": "ctrl+r"
}

#Prompt Templates

Custom system prompts in prompts/ directories:

  • ~/.neo-code/agent/prompts/ — global
  • .neo-code/prompts/ — per-project

Files are loaded and appended to the system prompt.

ON THIS PAGE

  1. Directory Structure
  2. Settings
  3. Model & Provider
  4. Behavior
  5. Compaction
  6. Memory
  7. Retry
  8. UI
  9. Skills & Extensions
  10. MCP
  11. Images
  12. Notifications (Termux)
  13. Session
  14. AGENTS.md
  15. Keybindings
  16. Prompt Templates
Previous← Getting StartedNextTools →

Neo Code

Neosantara-first AI coding agent for your terminal.

Product

  • Docs
  • Pricing
  • GitHub

Neosantara

  • Dashboard
  • API

Legal

  • Terms
  • Privacy

2026 Neosantara. All rights reserved.