Maki

https://maki.sh/docs
Admin
Maki is a terminal coding agent written in Rust, built to read, search, edit, and run code while...
Tokens:47,404
Snippets:391
Trust Score:6.5
Update:1 month ago
Show doc for...
Tokens:
Raw
### Quick Start Commands

Source: https://maki.sh/docs/quick-start

Installation commands for Linux/macOS, Windows, Nix, and Cargo; provider authentication; first session; default model configuration; project structure.

```bash
curl -fsSL https://maki.sh/install.sh -o install.sh
cat install.sh

# Then run.
chmod +x install.sh && sh install.sh
```

```bash
curl -fsSL https://maki.sh/install.sh | sh
```

```powershell
irm https://maki.sh/install.ps1 -OutFile install.ps1
Get-Content install.ps1
```

```bash
cargo install --locked --git https://github.com/tontinton/maki.git maki
```

```bash
nix run github:tontinton/maki
```

```bash
maki auth login              # interactive picker (OAuth or API key)
export ANTHROPIC_API_KEY=... # or just export a key
```

```bash
maki
```

```lua
-- ~/.config/maki/init.lua
maki.setup({
    provider = {
        default_model = "anthropic/claude-sonnet-4-6",
    },
})
```

```text
.maki/
├── init.lua           # overrides global config
├── permissions.toml   # permission rules
├── mcp.toml           # MCP server config
├── commands/          # custom slash commands (.md files)
└── skills/            # project skills (each dir has a SKILL.md)
AGENTS.md              # always in context
AGENTS.local.md        # personal per-project instructions (gitignored)
```

--------------------------------

### Install a package by hand into pack directory

Source: https://maki.sh/docs/packages

Shows the directory layout for manually installing a package into a Neovim-style package directory. Use any group name except core, which Maki reserves and never scans. A start package loads at startup; an opt package stays installed until activated. Manual placement grants the package exactly the permissions its plugin.toml requests without an approval step.

```text
<maki-data>/site/pack/<group>/start/<name>/
<maki-data>/site/pack/<group>/opt/<name>/

```

--------------------------------

### Instruction file loading example

Source: https://maki.sh/docs/context

Shows which instruction files are loaded at session start. Maki walks from the git root down to the working directory, loading one project file per directory (first match wins) plus AGENTS.local.md if present. Closer directories win on conflicts, and a global ~/.config/maki/AGENTS.md is always loaded.

```text
~/repo/AGENTS.md           loaded (root)
~/repo/AGENTS.local.md     loaded (yours, gitignored)
~/repo/api/CLAUDE.md       loaded when cwd is ~/repo/api, wins over root
~/repo/web/AGENTS.md       not loaded yet...
~/.config/maki/AGENTS.md   loaded (global)
```

--------------------------------

### Everyday maki CLI usage examples

Source: https://maki.sh/docs/cli

A set of everyday command-line examples for the maki CLI, covering TUI usage, one-shot prompts, session continuation, model listing, authentication, and tool inspection.

```bash
# TUI on a project
cd ~/code/my-app && maki

# One-shot with YOLO and a model pin
maki -p --yolo -m anthropic/claude-sonnet-4-6 "summarize the architecture"

# Resume yesterday's session
maki --continue

# List models, then log in
maki models
maki auth login

# Inspect tools without starting a session
maki prompt --tools --names
```

--------------------------------

### Start ACP server

Source: https://maki.sh/docs/acp

Command to start the Maki ACP server over stdio.

```bash
maki acp
```

--------------------------------

### Telemetry configuration example in init.lua

Source: https://maki.sh/docs/telemetry

Example of setting up telemetry in maki.setup with enabled flag, exporters, protocol, endpoint, headers, and resource attributes. All durations are in milliseconds and floored at 100ms. Exporter values can be otlp, console, none, or a comma-separated mix. Protocols are grpc, http/protobuf, and http/json.

```lua
maki.setup({
    telemetry = {
        enabled = true,
        metrics_exporter = "otlp",
        logs_exporter = "otlp",
        protocol = "grpc",
        endpoint = "http://localhost:4317",
        headers = { ["x-api-key"] = "secret" },
        resource_attributes = { team = "core", env = "dev" },
    },
})
```

--------------------------------

### Configure bundled plugins in maki.setup

Source: https://maki.sh/docs/configuration

Example of configuring the `plugins` table in `maki.setup`. Shows disabling `websearch` and setting a custom `timeout_secs` for `bash`. All bundled plugins are on by default; set `enabled = false` to turn one off.

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

--------------------------------

### Install packages from Git with maki.pack.add

Source: https://maki.sh/docs/packages

Declares managed packages in the global init.lua, normally ~/.config/maki/init.lua. Each entry is a source string or a table with src, version, name, and data. Maki shows all new packages in one install prompt and writes the selected commit to pack-lock.json.

```lua
maki.pack.add({
  "https://github.com/example/maki-goal",
  {
    src = "https://github.com/example/maki-review",
    version = "v1.2.0",
  },
})
```

--------------------------------

### Example skill directory path

Source: https://maki.sh/docs/skills

Shows the directory layout for a skill named 'git-release' under the project's .maki/skills folder.

```text
.maki/skills/git-release/SKILL.md

```

--------------------------------

### Complete Configuration Example

Source: https://maki.sh/docs/configuration

Shows the full set of optional settings for maki.setup() in init.lua. All fields are optional; typos cause an immediate error. A project init.lua runs only after folder trust is granted. The provider policy with allowed and excluded models applies to selectors, CLI/API changes, delegation, and the `maki models` command. maki.setup() can only be called once per init.lua.

```lua
maki.setup({
    ui = {
        splash_animation = true,
        mouse_scroll_lines = 5,
        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 },
    },
})
```

--------------------------------

### Install package with confirm = false

Source: https://maki.sh/docs/packages

Sets confirm = false to skip the install prompt when the package source is already trusted and Maki must run without a terminal. This option does not approve package permissions. Maki rejects HTTP sources with credentials.

```lua
maki.pack.add({ "https://github.com/example/maki-goal" }, {
  confirm = false,
})
```

--------------------------------

### maki acp: start ACP server

Source: https://maki.sh/docs/cli

Start an ACP server on stdio for editors like Zed. Subcommand flags are only `-m`/`--model` and `--yolo`. Global flags like `--no-jit` must come before the subcommand.

```bash
maki acp
maki acp -m anthropic/claude-sonnet-4-6
maki acp --yolo
maki --no-jit acp
```

--------------------------------

### Example SKILL.md for git-release

Source: https://maki.sh/docs/skills

A complete SKILL.md file with optional frontmatter providing name and description, followed by the skill steps. The frontmatter is optional; without it the directory name becomes the name and the whole file is the body.

```markdown
---
name: git-release
description: Cut a tagged release and open the changelog PR
---

## Steps

1. Read `CHANGELOG.md` and the commits since the last tag.
2. Propose a semver bump and a short release summary.
3. Only tag after the user confirms.

```

--------------------------------

### maki index: print file skeleton

Source: https://maki.sh/docs/cli

Run the `index` tool on a file and print the skeleton, so you can see what the agent will get before a session. Builtin plugins always load here; `--no-plugins` only skips user `init.lua`.

```bash
maki index path/to/file.rs
```

--------------------------------

### MCP prompt slash command examples

Source: https://maki.sh/docs/mcp

Examples of Maki slash commands for MCP prompts. Use /server:prompt-name syntax. Prompts can have no arguments, one argument, or multiple positional arguments. Skipping a required argument shows a usage hint.

```plaintext
/github:create-pr           # no arguments
/analytics:report monthly   # one argument
/review:code src tests      # multiple, positional
```

--------------------------------

### Configure allowed_private_hosts in maki.setup

Source: https://maki.sh/docs/configuration

Configure the net guard to allow specific private hosts. The example lists localhost:8080, nas.lan, and the CIDR range 10.0.0.0/8. An entry without a port covers every port; a listed name is allowed whatever it resolves to, and every redirect hop is checked against the same list.

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

--------------------------------

### index vs read: skeleton then targeted read

Source: https://maki.sh/docs/token-economy

Compares reading a whole file versus using the index tool to get a tree-sitter skeleton (imports, types, signatures, line numbers) and then reading only the needed ranges.

```text
read main.rs                 index main.rs
────────────                 ─────────────────────────────
1400 lines in context        60 lines of signatures
                             + read offset=812 limit=40
```

--------------------------------

### Enable YOLO mode always in init.lua

Source: https://maki.sh/docs/permissions

Configure Maki to start in YOLO mode every time by setting always_yolo = true in the init.lua configuration file. This skips prompts on gated tools, but explicit deny rules still apply.

```lua
-- ~/.config/maki/init.lua
maki.setup({
    always_yolo = true,
})
```

--------------------------------

### Remove all undeclared packages with /packdel ++all

Source: https://maki.sh/docs/packages

Removes every installed package that is no longer declared. Maki displays the packages it is about to remove and waits for acceptance. Packages still active in this or another Maki process are refused. Use /packdel! to skip the review; refusals still apply.

```text
/packdel ++all
```

--------------------------------

### permissions.toml with per-tool allow/deny lists

Source: https://maki.sh/docs/permissions

Example permissions.toml showing per-tool allow/deny lists and the default key. The [bash] section allows cargo and git commands while denying rm -rf and sudo. The [read] section sets default to allow, and MCP sections use allow/deny arrays. Note that in MCP sections, boolean allow/deny forms are deprecated; use default = "allow" or "deny" instead.

```toml
default = "deny"

[bash]
allow = [
    "cargo *",
    "git *",
]
deny = [
    "rm -rf *",
    "sudo *",
]

[read]
default = "allow"

[mcp.deepwiki]
allow = ["search", "fetch"]

[mcp.github]
deny = ["admin_delete"]
```

--------------------------------

### Send stream-json user message with --max-turns

Source: https://maki.sh/docs/headless

Quick example of sending a stream-json user message to Maki with --max-turns 3. One-shot --print always starts a new session in build mode; plan mode and session resume need the SDK path or the TUI.

```bash
echo '{"type":"user","message":{"content":"explain this repo"}}' \
  | maki --print --input-format stream-json --max-turns 3
```

--------------------------------

### maki update and rollback

Source: https://maki.sh/docs/cli

Update to the latest release or roll back to the previous version. `-y` skips confirmation, `--no-color` disables colored output. Uses the same install locations as the install scripts.

```bash
maki update            # install latest release
maki update -y         # skip confirmation
maki update --no-color
maki rollback          # previous version
```

--------------------------------

### Install package with custom load function

Source: https://maki.sh/docs/packages

Sets load to a function when the package needs a custom entry point. The function runs as the package owner and receives the package spec and its installed path. The data field can contain any Lua value.

```lua
maki.pack.add({
  {
    src = "https://github.com/example/maki-review",
    data = { module = "review" },
  },
}, {
  load = function(package)
    require(package.spec.data.module).setup()
  end,
})
```

--------------------------------

### Complete 'glob' tool plugin in Lua (register_options and register_tool)

Source: https://maki.sh/docs/plugins

Full implementation of the bundled 'glob' tool. Opens with maki.api.register_options, which bundled plugins use but your own plugins skip. It demonstrates tool registration (name, kind, description, schema, header, restore), (value, err) handling from maki.fs.glob, error reporting via { llm_output = 

```lua
local truncate = require("maki.truncate")
local ToolView = require("maki.tool_view")
local shorten_path = require("maki.shorten_path")
local output_limits = require("maki.output_limits")

local NO_FILES_FOUND = "No files found"

local opts = maki.api.register_options(output_limits.extend({
  search_result_limit = { default = 100, min = 10, desc = "Max files returned per search." },
}))

local function glob_view_opts(ctx)
  local tol = ctx:tool_output_lines()
  return { max_lines = (tol and tol.other) or 3, keep = "head" }
end

maki.api.register_tool({
  name = "glob",
  kind = "search",
  description = [[Find files by glob pattern.

- Respects .gitignore.
- Returns absolute paths sorted by modification time (newest first).
- Prefer speculative parallel searches over sequential rounds of glob+grep.]],

  schema = {
    type = "object",
    properties = {
      pattern = { type = "string", description = "Glob pattern (e.g. **/*.rs, src/**/*.ts)", required = true },
      path = { type = "string", description = "Directory to search in (default: cwd)" },
    },
  },

  header = function(input)
    local buf = maki.ui.buf()
    local spans = { { shorten_path(input.pattern or ""), "tool" } }
    if input.path then
      spans[#spans + 1] = { " in ", "dim" }
      spans[#spans + 1] = { shorten_path(input.path), "path" }
    end
    buf:line(spans)
    return buf
  end,

  restore = function(_input, output, _is_error, ctx)
    return ToolView.restore(output, glob_view_opts(ctx))
  end,

  handler = function(input, ctx)
    local pattern = input.pattern
    if not pattern then
      return { llm_output = "error: pattern is required", is_error = true }
    end

    local limit = opts.search_result_limit
    local max_lines, max_bytes = output_limits.resolve(opts, ctx)

    local files, err = maki.fs.glob(pattern, {
      path = input.path,
      gitignore = true,
      sort = "mtime",
      limit = limit,
    })

    if not files then
      return { llm_output = "error: " .. err, is_error = true }
    end

    if #files == 0 then
      return { llm_output = NO_FILES_FOUND }
    end

    local lines = {}
    for i, f in ipairs(files) do
      lines[i] = shorten_path(f)
    end
    local text = table.concat(lines, "\n")
    local llm_output = truncate(text, max_lines, max_bytes)

    local buf = maki.ui.buf()
    local view = ToolView.new(buf, glob_view_opts(ctx))
    for _, line in ipairs(lines) do
      view:append(line)
    end
    view:finish()
    buf:on("click", function()
      view:toggle()
    end)

    return {
      llm_output = llm_output,
      body = buf,
    }
  end,
})

```

--------------------------------

### CLI usage syntax

Source: https://maki.sh/docs/cli

Shows the two top-level CLI forms: running the TUI with optional options and prompt, or invoking a subcommand. Use this as a quick reference for the command syntax.

```text
maki [OPTIONS] [PROMPT]
maki <COMMAND>
```

--------------------------------

### Model identifier examples

Source: https://maki.sh/docs/providers

Shows the provider/model_id format used to reference models in Maki. The prefix can be omitted if the model name is unique across providers.

```text
anthropic/claude-sonnet-4-6
openai/gpt-4.1
xai/grok-4.6
zai/glm-4.7
```

--------------------------------

### Activate a package with maki.packadd

Source: https://maki.sh/docs/packages

Activates an installed package or a managed package declared with load = false. Call it from init.lua or from another package; Maki loads the named package after the calling Lua task returns.

```lua
maki.packadd("my-package")
```

--------------------------------

### maki prompt: inspect prompt and tools

Source: https://maki.sh/docs/cli

Debug helper for inspecting the prompt and tool surface the agent sees. `--plan` is rejected on non-system variants.

```bash
maki prompt                  # rendered system prompt (default: system variant)
maki prompt research
maki prompt general
maki prompt --plan           # system prompt + plan-mode reminder (system only)
maki prompt --tools          # tool definitions as JSON
maki prompt --tools --names  # tool names only, one per line
```

--------------------------------

### Boot without user init.lua using maki --no-plugins

Source: https://maki.sh/docs/keybindings

Use this command to recover from a bad keymap that leaves Maki stuck, such as a rebound Ctrl+C or a plugin that throws on load. It skips user init.lua files (global and project) but keeps the Lua host and builtin plugins running, so tools still work. The default keymap lives in Rust, so it is never dropped.

```bash
maki --no-plugins
```

--------------------------------

### Load plugin with require

Source: https://maki.sh/docs/plugins

Loads the plugin module from init.lua. The module name is the path under lua/ without the extension.

```lua
require("hello")
```

--------------------------------

### maki models: list models and refresh catalog

Source: https://maki.sh/docs/cli

List models. One spec per line, warnings on stderr. Built-in and script providers are listed live; catalog-backed providers come from the models.dev cache, which expires after 24 hours and supplies pricing and context windows. `--refresh` refetches the catalog; if the refetch fails, the cached catalog stays in place, the list still prints, and the command exits non-zero.

```bash
maki models
maki models --refresh    # refetch the models.dev catalog
```

--------------------------------

### maki auth: login, logout, status

Source: https://maki.sh/docs/cli

Manage authentication for providers. `login` stores credentials under the state directory and can write plan/base URL choices into `providers.toml`. OpenAI and Copilot have dedicated flows; other providers prompt for a key (and a plan when the provider has more than one). `status` shows each provider as configured (key on disk), env-only, or missing.

```bash
maki auth login [provider]   # interactive picker if omitted
maki auth logout <provider>
maki auth status
```

--------------------------------

### Restore an archived session with shell commands

Source: https://maki.sh/docs/context

Commands to restore an archived session file. Move the live log aside, copy the archive into place, then start Maki with the session ID. This drops the session's current state, so back it up first.

```bash
cd ~/.local/state/maki/sessions
mv <session-id>.jsonl <session-id>.jsonl.bak
cp archive/<session-id>/<n>.jsonl <session-id>.jsonl
maki -s <session-id>
```

--------------------------------

### Register a tool with maki.api.register_tool

Source: https://maki.sh/docs/plugins

Registers a tool named 'hello' that the LLM can call. The handler returns an llm_output string. Place this in a plugin file under the config dir.

```lua
maki.api.register_tool({
  name = "hello",
  description = "Say hello to a name.",
  parameters = { type = "object", properties = { name = { type = "string" } }, required = { "name" } },
  handler = function(args)
    return { llm_output = "hello " .. args.name }
  end,
})
```

--------------------------------

### Declare and wrap a custom plugin slot

Source: https://maki.sh/docs/hooks

Defines a custom extension point with declare_slot and wraps it with set_slot. The declaring plugin owns the name and supplies the default; anyone can wrap it. Names starting with tool. are reserved for maki, which fires them at guaranteed ordering points.

```lua
-- owner
local render = maki.api.declare_slot("myplugin.render", function(text)
  return text:upper()
end)

-- anyone
maki.api.set_slot("myplugin.render", function(prev, text)
  return "[" .. prev(text) .. "]"
end)

-- render("hi") now returns "[HI]"
```
Tokens:
Raw