How to Configure Apache Maka: Complete Guide to Settings.json, CLI, and UI

Apache Maka stores all user-editable configuration in a settings.json file inside the Electron userData directory, which you can modify through the Desktop UI, CLI commands, or direct file edits.

Apache Maka is an open-source desktop application that centralizes configuration management through a structured JSON schema. Whether you are customizing themes, configuring AI model connections, or adjusting workspace defaults, you configure Apache Maka through three complementary interfaces that all write to the same underlying AppSettings object defined in the core source code.

Where Apache Maka Stores Configuration

All persistent settings live in a JSON file named settings.json located within the Electron userData directory. The typical path is ~/.config/maka/workspaces/default/ on Linux, with equivalent locations on macOS and Windows.

At startup, the Runtime Host initializes the SettingsStore by calling createSettingsStore(workspaceRoot) in packages/storage/src/settings-store.ts. The FileSettingsStore class reads the JSON file through its get() method, validates the structure using normalization helpers from packages/core/src/settings.ts, and caches the resulting AppSettings object for use by both the UI and CLI.

Three Ways to Configure Apache Maka

Desktop UI Settings

The simplest method to configure Apache Maka is through the built-in Settings drawer. Click the gear icon to open apps/desktop/src/renderer/settings/settings-modal.tsx, which renders form controls for each settings section defined in the core schema. Changes made in the UI are sent via IPC through apps/desktop/src/main/settings-ipc-helpers.ts to the main process, which calls FileSettingsStore.update(patch) to persist the changes.

Command Line Interface

For automation and scripting, use the built-in settings command:

# Set the default AI model

maka settings set models defaultModel claude-3-opus

# Enable the web-search sub-agent

maka settings set subagents.enabled true

# Configure search API key

maka settings set search.apiKey YOUR_TAVILY_KEY

The CLI sends patches to the same FileSettingsStore.update() method used by the UI, ensuring consistency across interfaces.

Direct JSON Editing

For bulk changes or version-controlled configurations, edit settings.json directly:

{
  "appearance": {
    "theme": "dark",
    "themePalette": "nord",
    "appIcon": "sky",
    "appIconDark": "ink"
  },
  "models": {
    "defaultModel": "gpt-4o",
    "connections": [
      {
        "id": "openai-gpt4o",
        "type": "openai",
        "apiKey": "YOUR_OPENAI_KEY",
        "model": "gpt-4o",
        "provider": "openai"
      }
    ]
  },
  "permissions": {
    "permissionMode": "managed"
  }
}

Save the file and restart Maka to load the new configuration. The normalizeSettings function in packages/core/src/settings.ts validates the structure on next launch.

Key Configuration Sections

The AppSettings schema in packages/core/src/settings.ts organizes configuration into typed sections:

• general: Global defaults including locale and autoUpdate behavior.
• appearance: Theme control through theme, themePalette, appIcon, and appIconDark options.
• projects: Workspace configuration with defaultWorkspace and workspaceRoot paths.
• memory: Local cache settings including enabled flag and maxEntries limits.
• models: AI provider configuration using the ModelConnection type, including defaultModel and API keys in the connections array.
• subagents: Toggle built-in agents like web-search and code-review via the enabled boolean and options object.
• external-agents: User-supplied agent definitions stored in the agents array (type ExternalAgentConfig).
• search: Web-search provider setup with apiKey and rateLimit for services like Tavily.
• permissions: Security mode selection via permissionMode (managed or bypass) and associated labels.
• usage: Telemetry configuration with enabled, range, and status fields.
• daily-review: Automated scheduling using cron expressions and reviewPrompt settings.

How the Configuration System Works

The configuration pipeline follows a strict validation flow:

1. Initialization: The Runtime Host invokes createSettingsStore() with the workspace root path.
2. Validation: FileSettingsStore.get() reads settings.json and applies normalizeSettings() from packages/core/src/settings.ts to ensure type safety and default values.
3. Distribution: The validated AppSettings object travels via IPC (apps/desktop/src/main/settings-ipc-helpers.ts) to the Renderer process for UI consumption.
4. Persistence: Updates from any interface call FileSettingsStore.update(patch), which merges changes, re-normalizes the data, and atomically writes back to disk.

Summary

• Apache Maka configuration resides in settings.json within the Electron userData directory (e.g., ~/.config/maka/workspaces/default/).
• The SettingsStore class in packages/storage/src/settings-store.ts manages all read/write operations.
• You can configure Apache Maka via the Desktop Settings UI, the maka settings CLI, or direct JSON manipulation.
• The AppSettings schema in packages/core/src/settings.ts defines all valid sections including appearance, models, permissions, and subagents.
• All configuration methods ultimately invoke FileSettingsStore.update() to persist changes after validation.

Frequently Asked Questions

Where is the settings.json file located on my system?

The file is located in the Electron userData directory under workspaces/default/settings.json. On Linux this is typically ~/.config/maka/workspaces/default/settings.json, while macOS uses ~/Library/Application Support/maka/ and Windows uses %APPDATA%/maka/.

Can I configure Apache Maka without opening the desktop application?

Yes. You can use the CLI command maka settings set <section> <key> <value> to modify configuration from the terminal, or edit the settings.json file directly with a text editor. Both methods work while the application is closed and take effect on next launch.

What happens if I edit settings.json while Maka is running?

The application may overwrite your manual changes if it persists any UI state to disk. To avoid conflicts, close Maka before editing settings.json directly, or use the CLI maka settings commands which safely acquire file locks and merge patches through the FileSettingsStore.update() API.

How do I add a new AI model connection via configuration?

Add a new object to the models.connections array in settings.json with the ModelConnection structure: include id, type (e.g., "openai"), provider, model, and apiKey. Alternatively, use the CLI: maka settings set models.connections '[{"id":"custom","type":"openai","apiKey":"KEY","model":"gpt-4"}]'.

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