Configuration

DimAgent stores persistent data locally. The default base directory is ~/.dimcode/v2/.

Tip: Prefer configuring inside the TUI (Ctrl+P, /connect, /models, /plugins, /mcp) for day-to-day use.

Directory Layout

~/.dimcode/
  v2/                          # v2 data home
    dimcode.sqlite             # main storage database (sessions, providers, etc.)
    credentials.json           # global credentials
    credentials/               # per-provider credentials
      <providerId>.json
    mcp.json                   # MCP server configuration
  config.json                  # legacy config (migrated to v2 on first run)

Path Resolution

DimAgent uses DIMCODE_HOME as the base-directory override:

1. If DIMCODE_HOME is set:
   • Home dir: $DIMCODE_HOME
2. Default:
   • Home dir: ~/.dimcode/v2

File locations:

• Storage database: <home-dir>/dimcode.sqlite
• Credentials: <home-dir>/credentials.json or <home-dir>/credentials/<providerId>.json
• MCP config: <home-dir>/mcp.json
• Project MCP config: <cwd>/.mcp.json

Storage Database

DimAgent v2 uses SQLite (dimcode.sqlite) as the primary storage for:

• Session state and history
• Provider configuration
• Usage records
• Tool execution logs
• Blob storage (images, attachments)

This is a change from v1 which used separate JSON files. On first run with v2, data from legacy JSON files is automatically migrated.

Credentials

Credentials are stored per-provider:

~/.dimcode/v2/credentials/<providerId>.json

Or in a global credentials file:

~/.dimcode/v2/credentials.json

Use /connect in the TUI or dim provider add to manage credentials.

mcp.json

Purpose: MCP server configuration.

The recommended v2 format uses a top-level mcpServers object. Each key is the server id, and name is an optional display label.

{
  "mcpServers": {
    "MiniMax": {
      "name": "MiniMax",
      "command": "uvx",
      "args": ["minimax-coding-plan-mcp"],
      "env": {
        "MINIMAX_API_KEY": "${MINIMAX_API_KEY}",
        "MINIMAX_MCP_BASE_PATH": "${HOME}/.dimcode/minimax",
        "MINIMAX_API_HOST": "https://api.minimaxi.com"
      },
      "enabled": true
    },
    "remote-api": {
      "name": "Remote API",
      "type": "http",
      "url": "https://example.com/mcp",
      "auth": {
        "type": "bearer",
        "token": "${MCP_TOKEN}"
      },
      "headers": {
        "x-client": "dimcode"
      },
      "enabled": true
    }
  }
}

Manage this through:

• TUI: /mcp or Ctrl+P -> MCP
• CLI: dim mcp add, dim mcp add-json, dim mcp list, dim mcp test, dim mcp toggle, dim mcp remove

Project-level MCP config can be placed at <project>/.mcp.json.

User-level and project-level config both use the mcpServers object format.

MCP Transport

Bearer tokens can be stored as auth: { "type": "bearer", "token": "${TOKEN}" }. Put ordinary headers under headers.

The CLI config reader reports warnings for sse, streamable_http, and unknown transport values, then skips that server.

stdio Examples

dim mcp add filesystem -- npx -y @modelcontextprotocol/server-filesystem .
dim mcp add --scope project github \
  --env 'GITHUB_TOKEN=${GITHUB_TOKEN}' \
  -- npx -y @modelcontextprotocol/server-github

HTTP Examples

dim mcp add --transport http remote https://example.com/mcp
dim mcp add --transport http secure-api https://api.example.com/mcp \
  --header 'Authorization: Bearer ${API_TOKEN}'

Environment Templates

MCP config supports environment templates in command, args, env, cwd, url, and headers.

Missing required environment variables skip that server with a warning. Other MCP servers and the main flow continue.

Legacy Config

The v1 config files may still exist at ~/.dimcode/:

• config.json: provider connections and UI settings (migrated to SQLite)
• tools.json: WebSearch settings
• dimcode/cache.json: cached preferences
• dimcode/auth.json: auth tokens
• dimcode/state/: session state store

On first run of v2, relevant data is automatically imported from these files.

Environment Variables

Environment variables override saved files at runtime.

Common variables:

• OPENAI_API_KEY
• OPENAI_BASE_URL / DIMCODE_OPENAI_BASE_URL
• GOOGLE_API_KEY
• DIMCODE_GEMINI_BASE_URL
• ANTHROPIC_API_KEY
• DIMCODE_ANTHROPIC_BASE_URL
• DIMCODE_PROVIDER_ADAPTER (openai / openai-responses / gemini / anthropic)
• DIMCODE_MODEL
• DIMCODE_TEMPERATURE
• DIMCODE_CONTEXT_WINDOW
• DIMCODE_TOOL_APPROVALS (auto / approve-for-me / normal)
• DIMCODE_SESSION_ID (session ID for one-shot mode)
• DIMCODE_HOME
• DIMCODE_STATE_DIR
• DIMCODE_DISABLE_AUTOUPDATE=1
• DIMCODE_AUTOUPDATE=0
• DIMCODE_DEBUG_LOG

Reset

This removes all v2 data:

rm -rf ~/.dimcode/v2

To also remove legacy v1 data:

rm -rf ~/.dimcode/config.json ~/.dimcode/tools.json
rm -rf ~/.dimcode/dimcode

Start dim again and run /connect to set up providers.