Getting Started

~5.1k tokens

Configuration

Settings go in init.lua, a Lua script that calls maki.setup(). Same language as plugins.

Two places, both optional:

Global: ~/.config/makima/init.lua
Project: .makima/init.lua (relative to your working directory)

When both exist, project settings override global ones. Neither file is required.

Example

maki.setup({
    ui = {
        splash_animation = true,
        mouse_scroll_lines = 5,
        autocomplete_height = 0.7,
        theme = "tokyonight",
        tool_output_lines = {
            bash = 8,
            read = 5,
        },
    },
    agent = {
        max_output_lines = 3000,
    },
    provider = {
        default_model = "anthropic/claude-sonnet-4-6",
        allowed_models = { "anthropic/*", "openai/gpt-5" },
        excluded_models = { "*/*-preview" },
    },

    storage = {
        max_log_files = 5,
    },
    plugins = {
        bash = { timeout_secs = 180 },
        index = { max_file_size_mb = 4 },
    },
})

All fields are optional. Typos in field names cause an error right away.

provider.allowed_models is a list of glob patterns for qualified provider/model-id specs. * also matches /, so opencode/* includes nested model IDs. When the list is empty or omitted, every model is allowed. provider.excluded_models removes matching models after that, so exclusions always win. A project list replaces the matching global list; omit it to inherit or use {} to clear it. The policy applies to selectors, CLI and API model changes, delegation, and makima models.

maki.setup() can only be called once per init.lua.

Full Reference

Top-level

Field	Type	Default	Description
`always_yolo`	bool	`false`	Start every session with YOLO mode (skip permission prompts, deny rules still apply)
`always_automode`	bool	`false`	Start every session with bash auto mode (classify every bash command)
`always_fast`	bool	`false`	Start every session with fast mode (Anthropic Opus or eligible Codex subscription models, ignored elsewhere)
`always_workflow`	bool	`false`	Start every session with workflow mode (task callable inside code_execution)
`always_thinking`	bool \| string	`false`	Start every session with extended thinking (true/"adaptive", "off", an effort level ("minimal" to "max"), or a token budget)

`ui`

Field	Type	Default	Min	Description
`splash_animation`	bool	`true`	-	Show splash animation on startup
`scrollbar`	bool	`true`	-	Show vertical scrollbar in scrollable areas
`inline_images`	bool	`true`	-	Render inline images in terminals with graphics support (Kitty graphics and tmux passthrough are detected automatically without manual multiplexer flags), falling back to an [image] line when off
`notifications`	string	`auto`	-	Terminal notification method: auto, osc9, bell, or off
`flash_duration_ms`	u64	`1500`	-	Duration of flash messages (ms)
`typewriter_ms_per_char`	u64	`4`	-	Typewriter effect speed (ms/char)
`mouse_scroll_lines`	u32	`3`	1	Lines per mouse wheel scroll
`max_input_lines`	u32	`20`	1	Maximum visible input lines
`autocomplete_height`	number	`0.7`	-	Fraction of terminal height used for slash command-argument suggestions; must be finite and in (0, 1]
`show_thinking`	bool	`true`	-	When true (default), show full model reasoning live and persisted. When false, hide reasoning behind an indicator (thinking> ...) with a click-to-expand hint, both while thinking and after it completes
`clock_format`	String	`system`	-	Clock format for timestamps: "12h", "24h", or "system" (follow the OS preference, 24h when unknown)

`ui.theme`

Name of the color theme to load at startup, overriding the theme you last picked interactively. If unset, Makima keeps your last selection (the built-in default on first run). An unknown name is ignored with a warning.

Available themes: ayu_dark, ayu_light, ayu_mirage, carbonfox, catppuccin_frappe, catppuccin_latte, catppuccin_macchiato, catppuccin_mocha, dark_daltonized, dracula, everforest_dark, fleet_dark, github_dark, gruvbox, gruvbox_light, kanagawa, kanagawa_ink, kanagawa_plum, makima, material_darker, monokai_pro, night_owl, nightfox, nord, onedark, rose_pine, rose_pine_dawn, rose_pine_midnight, rose_pine_moon, solarized_dark, solarized_light, tokyonight, vscode_dark_plus, zenburn.

You can add your own themes too. Drop a <name>.toml file into themes/ inside your Makima config directory, for example ~/.config/makima/themes/. If it reuses a built-in name, yours wins.

Themes use 24-bit colors, but not every terminal can show them. Makima checks the environment, terminfo, and the terminal itself, and when truecolor is missing it quietly falls back to the closest of the 256 classic terminal colors. If detection gets it wrong, set MAKIMA_TRUECOLOR=1 to force truecolor or MAKIMA_TRUECOLOR=0 to force the fallback.

A theme TOML file can define optional italic and bold_italic keys inside its [ui] table. These are theme styles, not fields in the ui table passed to maki.setup(). Without [ui].italic, Markdown italics use the foreground from the markup.italic syntax scope. An explicit [ui].italic takes precedence. Makima adds the italic modifier in either case.

Without [ui].bold_italic, bold italics preserve the resolved bold style, including its colors and modifiers, and add italic. An explicit [ui].bold_italic takes precedence and receives both bold and italic modifiers, even when it only specifies a color.

[ui]
italic = { fg = "yellow" }
bold_italic = { fg = "orange" }

Theme files can also carry an optional [completion] table that recolors the @ reference popup per candidate kind. Each key takes the same style definition as other UI styles: fg and bg (a palette color name or a #rrggbb value) plus a modifiers array ("bold", "italic", "underlined").

Key	Meaning	Falls back to
`file`	File and directory candidates	`accent`
`skill`	Skill references	`accent`
`subagent`	Subagent references	`accent`
`model`	Model references	`accent`

Kinds registered by your own completion sources (via maki.api.register_completion_source) fall back to the plain item style until your theme defines them.

`ui.tool_output_lines`

How many lines of output to show per tool in the UI. All values are usize with a minimum of 1.

Field	Default
`bash`	5
`code_execution`	5
`task`	5
`index`	3
`grep`	3
`read`	3
`write`	7
`web`	3
`other`	3

`ui.bell`

Ring the terminal bell (\x07) on these events. All values are bool, defaulting to true. Disable any of them to silence just that event.

Field	Default
`turn_complete`	true
`ask`	true
`permission`	true

`agent`

Field	Type	Default	Min	Description
`max_output_bytes`	usize	`51200`	1024	Max tool output size (bytes)
`max_output_lines`	usize	`2000`	10	Max tool output lines
`max_line_bytes`	usize	`1000`	80	Max bytes of one line shown by read and grep; longer lines are cut, and write and edit_lines refuse to alter them
`max_continuation_turns`	u32	`3`	1	Max automatic continuation turns
`max_turn_output`	u32	`32768`	1024	Output tokens one turn asks for, raised where an effort level needs the room and capped by the model's own limit
`max_concurrent_agent_turns`	usize	`8`	1	Max agent turns running concurrently
`max_agent_depth`	usize	`4`	1	Max nesting depth for child agents
`max_children_per_agent`	usize	`16`	1	Max child agents created by one agent
`max_live_agents`	usize	`64`	1	Max live agents in one outer session
`compaction_buffer`	u32 \| string	`20%`	-	Context reserved for compaction: token count or percent of the context window (e.g. "20%")
`compaction_instructions`	String	`none`	-	Extra instructions appended to the compaction summary prompt
`post_compaction_instructions`	String	`none`	-	Extra instructions the agent receives after any compaction (e.g. re-read plan.md)
`stale_read_check`	bool	`true`	-	Require re-reading a file that changed on disk before editing it
`rtk`	bool	`true`	-	Rewrite bash commands with rtk when it is installed

`provider`

Field	Type	Default	Min	Description
`default_model`	String	`none`	-	Default model identifier (e.g. `anthropic/claude-sonnet-4-6`)
`allowed_models`	string[]	`[]`	-	Glob patterns for permitted qualified model specs; empty permits all models
`excluded_models`	string[]	`[]`	-	Glob patterns for excluded qualified model specs; exclusions take precedence
`connect_timeout_secs`	u64	`10`	1	HTTP connect timeout (seconds)
`low_speed_timeout_secs`	u64	`120`	1	Low speed timeout (seconds with less than 1 byte received)
`stream_timeout_secs`	u64	`300`	10	Streaming response timeout (seconds)
`retry_base_ms`	u64	`2000`	1	Base delay between retries (milliseconds, grows per attempt)
`retry_max_ms`	u64	`60000`	1	Cap on the guessed retry backoff (milliseconds)
`max_retries`	u32	`5`	-	Max retries on a rate limit the server sent no Retry-After for, 0 to never retry them
`max_timeout_retries`	u32	`10`	-	Max retries on stream timeouts

`storage`

Field	Type	Default	Min	Description
`max_log_bytes_mb`	u64	`200`	1	Max total log size (MB)
`max_log_files`	u32	`10`	1	Max number of log files to keep
`input_history_size`	usize	`100`	10	Number of input history entries to retain

`net`

Field	Type	Default	Description
`allowed_private_hosts`	string[]	`[]`	Hosts allowed to resolve to a private or loopback address, as `host`, `host:port`, or a CIDR range. Plain `http://` is kept for them instead of being upgraded to `https://`

maki.net refuses private, loopback and metadata addresses, because the model picks the URLs. List a host here to let it through:

maki.setup({
    net = {
        allowed_private_hosts = { "localhost:8080", "nas.lan", "10.0.0.0/8" },
    },
})

An entry with no port covers every port. A name you list is allowed whatever it resolves to. A name you did not list stays blocked when DNS lands it on a private address, unless that address falls in a range you allowed, so keep ranges as small as the service needs. Every redirect hop is checked against the same list. Permissions covers what the guard protects.

`trust`

Answers the folder trust question in advance. Read from the global ~/.config/makima/init.lua only, since a project file that could set it would be trusting itself:

maki.setup({
    trust = {
        paths = { "~/src/me/*", "/workspace" },
        prompt = false,
    },
})

paths is a list of globs matched against the project root, empty by default. prompt is a bool, true by default. Setting it to false drops the startup card and leaves the folder restricted unless a paths entry matches. Folder Trust covers glob syntax and which run modes apply the policy.

Plugins

The plugins table turns plugins on or off and passes options to them. All bundled plugins are on by default. Set enabled = false to turn one off.

A plugin that is off never loads, so its tool name is free for one of your own plugins to take. Permission rules are keyed by the tool name alone, and names such as bash, write, and task already have rules in maki. A plugin that takes one of them inherits those rules, together with any "always allow" you saved. Maki warns you at load when this happens.

Each plugin checks its own options at startup. A typo, a wrong type, or an unknown plugin name gives you a clear error right away.

The edit plugin's extra tools are options too: plugins.edit = { multiedit = false, edit_lines = true }. The old tools table is gone. If your config still uses it, Makima stops at startup and shows you the new form.

This table is for bundled plugins only. Your own plugins go in ~/.config/makima/lua/, see Plugins.

maki.setup({
    plugins = {
        bash = { timeout_secs = 180 },
        websearch = { enabled = false },
    },
})

`plugins.bash`

Field	Type	Default	Min	Description
`auto_mode`	boolean	`false`	-	Classify every bash command before executing it (accept/deny with reason).
`auto_model`	string	-	-	Model spec for the bash auto-mode classifier. Unset: inherits the current session model.
`auto_timeout_secs`	integer	`30`	5	Stop the auto-mode classifier after this many seconds and fall back to normal permission handling.
`max_output_bytes`	integer	-	-	Override `agent.max_output_bytes` for this tool.
`max_output_lines`	integer	-	-	Override `agent.max_output_lines` for this tool.
`timeout_secs`	integer	`120`	5	Kill the command after this many seconds of execution. Approval time is excluded. A call's `timeout` param overrides it.

`plugins.code_execution`

Field	Type	Default	Min	Description
`max_memory_mb`	integer	`50`	10	Memory limit for the Python sandbox (MB).
`max_output_bytes`	integer	-	-	Override `agent.max_output_bytes` for this tool.
`max_output_lines`	integer	-	-	Override `agent.max_output_lines` for this tool.
`timeout_secs`	integer	`30`	5	Script execution time budget in seconds; waiting on tool calls does not count. A call's `timeout` param overrides it.

`plugins.edit`

Field	Type	Default	Min	Description
`edit_lines`	boolean	`true`	-	Provide the `edit_lines` tool.
`insert_lines`	boolean	`false`	-	Provide the opt-in `insert_lines` tool.
`multiedit`	boolean	`true`	-	Provide the `multiedit` tool.

`plugins.glob`

Field	Type	Default	Min	Description
`max_output_bytes`	integer	-	-	Override `agent.max_output_bytes` for this tool.
`max_output_lines`	integer	-	-	Override `agent.max_output_lines` for this tool.
`search_result_limit`	integer	`100`	10	Max files returned per search.

`plugins.grep`

Field	Type	Default	Min	Description
`max_output_bytes`	integer	-	-	Override `agent.max_output_bytes` for this tool.
`max_output_lines`	integer	-	-	Override `agent.max_output_lines` for this tool.
`search_result_limit`	integer	`100`	10	Max match groups per search. A call's `limit` param overrides it.

`plugins.index`

Field	Type	Default	Min	Description
`max_file_size_mb`	integer	`2`	1	Refuse to index files larger than this many MB.

`plugins.read`

Field	Type	Default	Min	Description
`max_output_bytes`	integer	-	-	Override `agent.max_output_bytes` for this tool.
`max_output_lines`	integer	-	-	Override `agent.max_output_lines` for this tool.

`plugins.skill`

Field	Type	Default	Min	Description
`plugin_dev`	boolean	`true`	-	Offer the builtin maki-plugin-dev skill for writing maki plugins.

`plugins.splashes`

Field	Type	Default	Min	Description
`splash`	string	-	-	Splash to select at startup, e.g. 'aurora' or 'default'. Wins over the persisted selection, re-wins on every boot, and updates the persisted selection to its value.

`plugins.task`

Field	Type	Default	Min	Description
`allow_model`	boolean	`false`	-	Expose a `model` input that overrides the subagent model. Only enable if you trust callers to pick an exact model themselves.
`max_concurrent`	integer	`8`	1	Deprecated. Process-wide fallback limit for unmanaged frontends; managed TUI sessions use agent.max_concurrent_agent_turns.

`plugins.webfetch`

Field	Type	Default	Min	Description
`max_output_bytes`	integer	-	-	Override `agent.max_output_bytes` for this tool.
`max_output_lines`	integer	-	-	Override `agent.max_output_lines` for this tool.
`max_response_bytes`	integer	`5242880`	1024	Stop reading a response after this many bytes.

`plugins.websearch`

Field	Type	Default	Min	Description
`max_output_bytes`	integer	-	-	Override `agent.max_output_bytes` for this tool.
`max_output_lines`	integer	-	-	Override `agent.max_output_lines` for this tool.
`max_response_bytes`	integer	`5242880`	1024	Stop reading a response after this many bytes.
`provider`	string	`"exa"`	-	Search backend: "exa" (default) or "youcom" (You.com MCP).

Validation

If a value is below its minimum, Makima shows a ConfigError with the field name, value, and minimum.

Directory layout

Makima follows platform directory conventions. On Linux and macOS that is XDG. On Windows, config, data, state, and logs all live under Roaming AppData (Windows has no separate state dir in this layout).

Purpose	Linux / macOS	Windows
Config	`~/.config/makima/`	`%APPDATA%\makima\`
Data	`~/.local/share/makima/`	`%APPDATA%\makima\`
State	`~/.local/state/makima/`	`%APPDATA%\makima\`
Logs	`~/.local/logs/makima/`	`%APPDATA%\makima\`
Cache	`~/.cache/makima/`	`%LOCALAPPDATA%\makima\`

Config holds init.lua, permissions.toml, mcp.toml, providers.toml, and commands/. State holds sessions, auth tokens, memories, plans, and model-tier overrides. The install script puts the binary under %LOCALAPPDATA%\makima on Windows; that is separate from these runtime dirs.

~/.makima/ (or %USERPROFILE%\.makima\) is checked as a legacy fallback. If that directory still exists, maki uses it for everything until you migrate.

Migrating from ~/.makima/

makima migrate xdg

This safely moves sessions, auth, plans, memories, logs, and preferences to the platform locations above. Where both old and new files exist, they are merged (input history, model tiers, etc.). Nothing is deleted until it has been copied. At the end you get a summary of where everything lives now.

Safe to run more than once.

Personal Instructions

On top of the project instruction files Makima loads from the git root down to the cwd (AGENTS.md, CLAUDE.md, and friends; see Context), you can add:

AGENTS.local.md in any of those project directories for per-directory preferences (gitignored)
~/.config/makima/AGENTS.md for preferences that apply to all projects

All of these are added to the system prompt at the start of every session.

Memory

The memory tool and /memory command store small Markdown notes under the state directory, scoped per project:

…/state/makima/projects/<project-id>/memories/

(Linux/macOS: ~/.local/state/makima/…; Windows: %APPDATA%\makima\…). Use them for non-obvious gotchas and decisions that should survive across sessions. They are separate from skills and from AGENTS.md.

Related pages: Skills, CLI, Providers.